typescript-monads/maybe/maybe.d.ts

Write cleaner TypeScript

import type { IResult } from '../result/result.interface';
import type { IMaybePattern, IMaybe } from './maybe.interface';
export declare class Maybe<T> implements IMaybe<T> {
    private readonly value?;
    constructor(value?: (T | null) | undefined);
    of(value: T): IMaybe<T>;
    static none<T>(): IMaybe<T>;
    static some<T>(value: T): IMaybe<T>;
    /**
     * Creates a Maybe from a Promise.
     *
     * Creates a Maybe that will resolve to:
     * - Some containing the resolved value if the promise resolves successfully
     * - None if the promise rejects or resolves to null/undefined
     *
     * @param promise The promise to convert to a Maybe
     * @returns A Promise that resolves to a Maybe containing the result
     *
     * @example
     * // Convert a promise to a Maybe
     * Maybe.fromPromise(api.fetchUser(userId))
     *   .then(userMaybe => userMaybe.match({
     *     some: user => console.log(user.name),
     *     none: () => console.log('User not found')
     *   }));
     */
    /**
     * Creates a Maybe from a Promise.
     *
     * Creates a Promise that will resolve to a Maybe that is:
     * - Some containing the resolved value if the promise resolves successfully to a non-nullish value
     * - None if the promise rejects or resolves to null/undefined
     *
     * Note on resolution preservation: This static method maps the Promise resolution semantics
     * to the Maybe context in a natural way:
     * - Promise resolution (success) becomes Some (presence of value)
     * - Promise rejection (failure) becomes None (absence of value)
     *
     * This provides a clean way to convert from error-based to optional-based handling,
     * which is often more appropriate for values that might legitimately be missing.
     *
     * @param promise The promise to convert to a Maybe
     * @returns A Promise that resolves to a Maybe containing the result
     *
     * @example
     * // Convert a promise to a Maybe and use in a chain
     * Maybe.fromPromise(api.fetchUser(userId))
     *   .then(userMaybe => userMaybe.match({
     *     some: user => renderUser(user),
     *     none: () => showUserNotFound()
     *   }));
     */
    static fromPromise<T>(promise: Promise<T>): Promise<IMaybe<NonNullable<T>>>;
    /**
     * Creates a Maybe from an Observable.
     *
     * Creates a Promise that will resolve to a Maybe that is:
     * - Some containing the first emitted value if the observable emits a non-nullish value
     * - None if the observable completes without emitting, errors, or emits a nullish value
     *
     * Note on resolution transformation: This method transforms the reactive semantics of
     * an Observable to the optional semantics of a Maybe:
     * - Observable emissions (data) become Some values (presence)
     * - Observable completion without emissions (empty success) becomes None (absence)
     * - Observable errors (failure) become None (absence)
     *
     * Note on timing model: This transformation changes from a continuous/reactive model
     * to a one-time asynchronous result. Only the first emission is captured, and the
     * reactive nature of the Observable is lost after transformation.
     *
     * @param observable The observable to convert to a Maybe
     * @returns A Promise that resolves to a Maybe containing the first emitted value
     *
     * @requires rxjs@^7.0
     * @example
     * // Convert an observable to a Maybe and use in a chain
     * Maybe.fromObservable(userService.getUser(userId))
     *   .then(userMaybe => userMaybe
     *     .map(user => user.name)
     *     .valueOr('Guest'))
     *   .then(name => displayUserName(name));
     */
    static fromObservable<T>(observable: import('rxjs').Observable<T>): Promise<IMaybe<NonNullable<T>>>;
    /**
     * Transforms an array of Maybe values into a Maybe containing an array of values.
     *
     * If all Maybes in the input array are Some, returns a Some containing an array of all values.
     * If any Maybe in the input array is None, returns None.
     *
     * @param maybes An array of Maybe values
     * @returns A Maybe containing an array of all values if all inputs are Some, otherwise None
     *
     * @example
     * // All Maybes are Some
     * const result1 = Maybe.sequence([maybe(1), maybe(2), maybe(3)]);
     * // result1 is Some([1, 2, 3])
     *
     * // One Maybe is None
     * const result2 = Maybe.sequence([maybe(1), maybe(null), maybe(3)]);
     * // result2 is None
     */
    static sequence<T>(maybes: ReadonlyArray<IMaybe<T>>): IMaybe<ReadonlyArray<T>>;
    isSome(): boolean;
    isNone(): boolean;
    valueOr(value: NonNullable<T>): NonNullable<T>;
    valueOrUndefined(): T | undefined;
    valueOrNull(): T | null;
    valueOrCompute(fn: () => NonNullable<T>): NonNullable<T>;
    valueOrThrow(msg?: string): NonNullable<T>;
    valueOrThrowErr(err?: Error): NonNullable<T>;
    tap(obj: Partial<IMaybePattern<T, void>>): void;
    tapNone(fn: () => void): void;
    tapSome(fn: (val: NonNullable<T>) => void): void;
    tapThru(val: Partial<IMaybePattern<T, void>>): IMaybe<T>;
    tapThruNone(fn: () => void): IMaybe<T>;
    tapThruSome(fn: (val: T) => void): IMaybe<T>;
    match<R>(pattern: IMaybePattern<T, R>): R;
    toArray(): ReadonlyArray<T>;
    map<R>(fn: (t: NonNullable<T>) => NonNullable<R>): IMaybe<R>;
    mapTo<R>(t: NonNullable<R>): IMaybe<R>;
    flatMap<R>(fn: (d: NonNullable<T>) => IMaybe<R>): IMaybe<R>;
    flatMapAuto<R>(fn: (d: NonNullable<T>) => R): IMaybe<NonNullable<R>>;
    project<R extends T[keyof T]>(fn: (d: NonNullable<T>) => R): IMaybe<NonNullable<R>>;
    filter(fn: (f: NonNullable<T>) => boolean): IMaybe<T>;
    apply<R>(maybeFn: IMaybe<(t: NonNullable<T>) => R>): IMaybe<NonNullable<R>>;
    toResult<E>(error: E): IResult<T, E>;
    flatMapPromise<R>(fn: (val: NonNullable<T>) => Promise<R>): Promise<IMaybe<NonNullable<R>>>;
    flatMapObservable<R>(fn: (val: NonNullable<T>) => import('rxjs').Observable<R>): Promise<IMaybe<NonNullable<R>>>;
    flatMapMany<R>(fn: (val: NonNullable<T>) => Promise<R>[]): Promise<IMaybe<NonNullable<R>[]>>;
    zipWith<R>(...args: unknown[]): IMaybe<R>;
}
//# sourceMappingURL=maybe.d.ts.map