Type Alias Maybe<TypedValue>

Type Declaration

• { empty: true; error: NonNullish | undefined | null; ok: false; value: never }
• {
      empty: false;
      error: undefined | null;
      ok: true;
      value: Mandatory<TypedValue>;
  }

• Readonlyempty: boolean

  true if the monad does not hold a non-nullish value; always the inverse of ok.

  Example

  maybe(42).empty;   // false
  maybe(null).empty; // true
  Copy

• Readonlyerror: NonNullish | undefined | null

  The error associated with an empty monad, or null / undefined when no error is present (i.e. the monad is ok or was emptied via maybe.empty).

  Example

  maybe(42).error;                              // undefined
  maybe.empty().error;                          // null
  maybe.error(new Error('oops')).error;         // Error: oops
  maybe(() => { throw new Error('!'); }).error; // Error: !
  Copy

• Readonlyok: boolean

  true if the monad holds a non-nullish value; always the inverse of empty.

  Example

  maybe(42).ok;   // true
  maybe(null).ok; // false
  Copy

• Readonlyvalue: Mandatory<TypedValue>

  The non-nullish value held by an ok monad.

  Throws

  The associated error if one exists, or a ReferenceError when the monad is empty without an error.

  Example

  maybe(42).value;                      // 42
  maybe(null).value;                    // throws ReferenceError
  maybe.error(new Error('oops')).value; // throws Error: oops
  Copy

• catch: function

  • catch<TypedNext>(
        next: (error: {}) => Nullish | TypedNext,
    ): Maybe<TypedValue | TypedNext>

    Returns a new monad produced by next when the current monad has an error. Returns the current monad unchanged when ok or empty without an error.

    Factory errors thrown inside next are caught and produce a new error monad.

    Type Parameters

    • TypedNext

    Parameters

    • next: (error: {}) => Nullish | TypedNext

      A function that receives the current error and returns a recovery value or null / undefined to stay empty.

    Returns Maybe<TypedValue | TypedNext>

    A monad for the recovery value, or the current monad.

    Example

    maybe.error(new Error('oops'))
      .catch((err) => `recovered: ${err.message}`)
      .value; // 'recovered: oops'
    
    maybe(42).catch(() => 0).value;   // 42     (ok – no-op)
    maybe.empty().catch(() => 0).ok;  // false  (no error – no-op)
    Copy

• else: function

  • else<TypedNext>(
        next: TypedNext | (() => Nullish | TypedNext) | undefined,
    ): Maybe<TypedValue | TypedNext>

    Returns next wrapped in a monad when the current monad is empty and has no error. Returns the current monad unchanged in every other case (i.e. when ok, or when empty with an error).

    next may be a plain value, a zero-argument factory, or undefined. Factory errors are caught and produce an error monad.

    Type Parameters

    • TypedNext

    Parameters

    • next: TypedNext | (() => Nullish | TypedNext) | undefined

      Fallback value, factory, or undefined.

    Returns Maybe<TypedValue | TypedNext>

    A monad for next or the current monad.

    Example

    maybe<number>(null).else(0).value;         // 0
    maybe<number>(null).else(() => 0).value;   // 0
    maybe(42).else(0).value;                   // 42  (ok – no-op)
    maybe.error(new Error('!')).else(0).error; // Error: ! (error – no-op)
    Copy

• filter: function

  • filter<TypedNext = TypedValue>(
        predicate:
            | ((value: Mandatory<TypedValue>) => boolean)
            | ((value: TypedValue) => value is TypedNext),
    ): Maybe<TypedNext>

    Returns an empty monad when the current monad is ok but predicate returns false. Returns the current monad unchanged when empty.

    Supports type-guard predicates to narrow the result type.

    Type Parameters

    • TypedNext = TypedValue

    Parameters

    • predicate:
          | ((value: Mandatory<TypedValue>) => boolean)
          | ((value: TypedValue) => value is TypedNext)

      A boolean-returning test, or a type-guard, applied to the current value.

    Returns Maybe<TypedNext>

    A monad whose value satisfies the predicate, or an empty monad.

    Example

    maybe(42).filter((n) => n > 0).value; // 42
    maybe(-1).filter((n) => n > 0).empty; // true
    
    // Type-guard narrows the result type
    const m = maybe<string | number>('hello')
      .filter((v): v is string => typeof v === 'string');
    m.value; // 'hello' (typed as string)
    Copy

• map: function

  • map<TypedNext>(
        next: (
            value: Mandatory<TypedValue>,
        ) => Nullish | TypedNext | Maybe<TypedNext>,
    ): Maybe<TypedNext>

    Transforms the current value by applying next when the monad is ok. Returns an empty or error monad unchanged.

    If next returns a Maybe, that monad is returned as-is (flat-map behaviour). If next returns a nullish value, an empty monad is returned. Errors thrown inside next are caught and produce an error monad.

    Type Parameters

    • TypedNext

    Parameters

    • next: (value: Mandatory<TypedValue>) => Nullish | TypedNext | Maybe<TypedNext>

      A mapping function that receives the current value and returns the next value, Maybe, or null / undefined.

    Returns Maybe<TypedNext>

    A monad wrapping the mapped value.

    Example

    maybe(21).map((n) => n * 2).value;         // 42
    maybe('hello').map((s) => s.length).value; // 5
    maybe<number>(null).map((n) => n * 2).ok;  // false  (empty – no-op)
    
    // Flat-map: returning a Maybe is unwrapped
    maybe(42).map((n) => maybe(n > 0 ? n : null)).value; // 42
    
    // Errors thrown in next are caught
    maybe(42).map(() => { throw new Error('!'); }).error; // Error: !
    Copy

• toArray: function

  • toArray(): [] | [Mandatory<TypedValue>]

    Returns a single-element tuple containing the value when ok, or an empty tuple when empty. Useful for destructuring or spreading into other arrays.

    Returns [] | [Mandatory<TypedValue>]

    [value] when ok, otherwise [].

    Example

    maybe(42).toArray();   // [42]
    maybe(null).toArray(); // []
    
    const results = [maybe(1), maybe(null), maybe(3)]
      .flatMap((m) => m.toArray()); // [1, 3]
    Copy