Maybe

Maybe represents a value that may or may not exist. It has two variants: Some for present values and None for absent values. This makes optional values explicit and safe — no more undefined is not a function.

Why Maybe?

No more null checks that silently pass or crash at runtime. Maybe makes absence a first-class concept.

// Without Maybe — crashes if user is undefined
const name = users.find(u => u.id === id).profile.displayName;

// With Maybe — safe and explicit
const name = maybe(users.find(u => u.id === id))
  .flatMap(u => maybe(u.profile))
  .map(p => p.displayName)
  .getOrElse('Anonymous');

Constructors

some

Creates a Some (present value).

import { some } from '@deessejs/fp';

some(5);         // Some<number>
some('hello');   // Some<string>
some({ id: 1 }); // Some<{ id: number }>

none

The None singleton (absent value).

import { none } from '@deessejs/fp';

none; // None

maybe

Creates Some from a non-null value, None from null or undefined.

import { maybe } from '@deessejs/fp';

maybe(5);         // Some(5)
maybe(null);      // None
maybe(undefined); // None
maybe(0);         // Some(0) — 0 is not null/undefined
maybe('');        // Some('') — empty string is not null/undefined

Transformation

map

Transforms the value if Some, passes through if None.

some(5).map(n => n * 2);   // Some(10)
none.map(n => n * 2);     // None

flatMap (chain)

Chains a Maybe-returning function. Short-circuits on None.

some(5).flatMap(n => some(n * 2));   // Some(10)
some(5).flatMap(() => none);         // None
none.flatMap(n => some(n * 2));      // None

filter

Returns Some if the predicate passes, None if it fails.

some(4).filter(n => n % 2 === 0); // Some(4)
some(3).filter(n => n % 2 === 0); // None
none.filter(n => n > 0);          // None

filterMap

Chains a Maybe-returning function. Alias for flatMap.

some(5).filterMap(n => n > 0 ? some(n * 2) : none); // Some(10)
some(-1).filterMap(n => n > 0 ? some(n * 2) : none); // None

tap

Runs a side effect on Some, returns the original Maybe unchanged.

some(5)
  .tap(n => console.log('Value:', n)) // logs 'Value: 5'
  .map(n => n * 2);                   // Some(10)

tapAsync

Async version of tap.

await some(5).tapAsync(async n => {
  await sendAnalytics('received', { value: n });
});

Pattern Matching

match

Transforms both variants to the same type.

some(5).match({
  some: (value) => `Got ${value}`,
  none: () => 'Nothing',
}); // 'Got 5'

fold

Alias for match. Transforms both variants to the same type.

some(5).fold(
  (value) => value * 2,
  () => 0,
); // 10

Unwrapping

getOrElse

Returns the value or a fallback.

some(5).getOrElse(0); // 5
none.getOrElse(0);    // 0

getOrNull

Returns the value or null.

some(5).getOrNull(); // 5
none.getOrNull();    // null

getOrUndefined

Returns the value or undefined.

some(5).getOrUndefined(); // 5
none.getOrUndefined();    // undefined

getOrThrow

Returns the value or throws.

some(5).getOrThrow(); // 5
none.getOrThrow();    // throws Error('Expected Some but got None')

Property Access

get

Safely accesses a property of the wrapped value. Returns Maybe for the property type.

const user = some({ name: 'Alice', address: { city: 'Paris' } });

user.get('name');              // Some('Alice')
user.get('address').get('city'); // Some('Paris')
user.get('email');            // None — property doesn't exist on type

This is especially useful for chaining through nested objects.

some({ user: { profile: { avatar: 'url' } } })
  .get('user')
  .get('profile')
  .get('avatar')
  .getOrElse('/default.png'); // Returns the avatar or default

Conversion

toResult

Converts Some to Ok and None to Err with a provided error value.

some(5).toResult('not found');    // Ok(5)
none.toResult('not found');       // Err('not found')

toArray

Converts to an array.

some(5).toArray(); // [5]
none.toArray();    // []

toIterable

Converts to an Iterable.

[...some(5)]; // [5]
[...none];    // []

Type Guards

isSome

Type guard that narrows to Some.

const maybe = some(5);

if (maybe.isSome()) {
  maybe.value; // number — TypeScript knows it's Some
}

isNone

Type guard that narrows to None.

const maybe = some(5);

if (maybe.isNone()) {
  // unreachable here
}

Type Utilities

SomeType

Extracts the inner type from a Maybe.

import type { SomeType } from '@deessejs/fp';

type T = SomeType<Maybe<string>>; // string

isMaybe

Type guard to check if a value is a Maybe.

import { isMaybe } from '@deessejs/fp';

isMaybe(some(5)); // true
isMaybe(none);    // true
isMaybe(5);       // false