@dancrumb/fpish/dist/Optional.d.ts

FP-friendly classes for Typescript

/**
 * An implementation of https://docs.oracle.com/javase/8/docs/api/java/util/fp/Optional.html
 */
export declare class Optional<T> {
    private readonly value;
    private constructor();
    /**
     * Create an empty Optional instance with type `ET`
     */
    static empty<ET>(): Optional<ET>;
    /**
     * Create a non-empty Optional instance with type `T`
     * @param value
     */
    static of<NT>(value: NT | Optional<NT> | undefined | null): Optional<NonNullable<NT>>;
    filter<S extends T>(predicate: (v: T) => v is S): Optional<S>;
    filter(predicate: (v: T) => boolean): Optional<T>;
    /**
     * Map the value of an Optional to another value of the same type.
     *
     * @param mapper
     */
    map<O>(mapper: (v: T) => Optional<O>): Optional<O>;
    /**
     * Map the value of an Optional to another value of a different type.
     *
     * @overload
     */
    map<U>(mapper: (v: T) => U | undefined | null): Optional<U>;
    /**
     * Map the value of an Optional to an Optional value of the same or a different type.
     *
     * This differs from `map`, such that the returned Optional is 'squashed' so that
     * the returned value is `Optional<U>` not `Optional<Optional<U>>`
     *
     * @param mapper
     */
    flatMap<U>(mapper: (val: T) => Optional<U | undefined | null>): Optional<U>;
    /**
     * Get the value of the optional or throw a `NoSuchElement` exception
     */
    get(): T | never;
    /**
     * If the Optional is non-empty, pass the value to a consuming function.
     *
     * The `consumer` should not return a value. If it does, this value is ignored.
     *
     * @param consumer
     */
    ifPresent(consumer: (val: T) => void): {
        orElse: (f: () => void) => void;
    };
    /**
     * Check whether the Optional is empty or not.
     */
    isPresent(): boolean;
    /**
     * Return the Optional's value if it is not empty, otherwise return the
     * provided value.
     *
     * @param other
     */
    orElse(other: T): T;
    /**
     * Return the Optional's value if it is not empty, otherwise return undefined.
     */
    orNothing(): T | undefined;
    /**
     * Return the Optional's value if it is not empty, otherwise return null.
     */
    orNull(): T | null;
    /**
     * Return the Optional's value if it is not empty, otherwise call `other` and
     * return that value.
     *
     * @param other
     */
    orElseGet(other: () => T): T;
    /**
     * Return the Optional's value if it is not empty, otherwise call `exceptionSupplier`
     * to generate an exception that is then thrown
     *
     * @param exceptionSupplier
     */
    orElseThrow(exceptionSupplier: () => Error): T | never;
    /**
     * Compares this Optional value to the provided on.
     *
     * Empty Optionals are never considered equal to anything, including other
     * empty Optionals.
     *
     * @param val
     * @param isEqual - an optional function for comparing equality
     */
    equals(val: Optional<T>, isEqual?: (a: T, b: T) => boolean): boolean;
    /**
     * Converts the internal type to another. `guard` is called to do the necessary
     * type checking. This is generally used for up- and down-casting.
     *
     * @param guard
     *
     * @deprecated just use `filter` with a type guard
     */
    cast<S extends T>(guard: (o: T | S) => boolean): Optional<S>;
    /**
     * @overload
     * @param key a property of the enclosed value
     */
    property<K extends keyof T>(key: K): T[K] | undefined;
    /**
     * @overload
     * @param key a property of the enclosed value
     * @param orElse a default value
     */
    property<K extends keyof T>(key: K, orElse: NonNullable<T[K]>): NonNullable<T[K]>;
    /**
     * See [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description)
     */
    toJSON(): T | undefined;
}