eaux/dist/index.d.mts

A lightweight and functional-style library that provides robust abstractions for handling optional values and handling operations that can either succeed or fail. By making states explicit, it encourages precise and deliberate management of application lo

declare class ExpectationError extends Error {
    constructor(message: string);
}

/**
 * A robust abstraction for handling optional values.
 */
declare abstract class Maybe<TValue> {
    #private;
    [x: symbol]: () => string;
    protected constructor();
    protected abstract _and<TOtherValue>(other: Maybe<TOtherValue>): Maybe<TOtherValue>;
    protected abstract _andThen<TOtherValue>(f: (value: TValue) => Maybe<TOtherValue>): Maybe<TOtherValue>;
    protected abstract _expect(message: string): TValue;
    protected abstract _filter(predicate: (value: TValue) => boolean): Maybe<TValue>;
    protected abstract _getSuccessOr<TError extends NonNullable<unknown>>(error: TError): Result<TValue, TError>;
    protected abstract _inspect(f: (value: TValue) => void): Maybe<TValue>;
    protected abstract _isNothing(): boolean;
    protected abstract _isNothingOr(predicate: (value: TValue) => boolean): boolean;
    protected abstract _isSomething(): boolean;
    protected abstract _isSomethingAnd(predicate: (value: TValue) => boolean): boolean;
    protected abstract _map<TNewValue>(f: (value: TValue) => TNewValue): Maybe<TNewValue>;
    protected abstract _or(other: Maybe<TValue>): Maybe<TValue>;
    protected abstract _unwrap(): TValue;
    /**
     * If this is a `Something` {@link Maybe}, returns {@link other}.
     * If this is a `Nothing` {@link Maybe}, returns this {@link Maybe}.
     *
     * @param other The {@link Maybe} to return if this is a `Something` {@link Maybe}.
     */
    and<TOtherValue>(other: Maybe<TOtherValue>): Maybe<TOtherValue>;
    /**
     * If this is a `Something` {@link Maybe}, returns the result of applying {@link f} to the contained value.
     * If this is a `Nothing` {@link Maybe}, returns this {@link Maybe}.
     *
     * @param f The function to apply to the contained value.
     */
    andThen<TOtherValue>(f: (value: TValue) => Maybe<TOtherValue>): Maybe<TOtherValue>;
    /**
     * If this is a `Something` {@link Maybe}, returns the contained value.
     * If this is a `Nothing` {@link Maybe}, throws an {@link ExpectationError} with the provided {@link message}.
     *
     * @param message The message to include in the {@link ExpectationError}.
     */
    expect(message: string): TValue;
    /**
     * If this is a `Something` {@link Maybe}, returns this {@link Maybe} if the contained value satisfies the provided {@link predicate}.
     * If this is a `Nothing` {@link Maybe}, returns this {@link Maybe}.
     *
     * @param predicate The predicate to apply to the contained value.
     */
    filter(predicate: (value: TValue) => boolean): Maybe<TValue>;
    /**
     * If this is a `Something` {@link Maybe}, returns a `Success` {@link Result} containing the contained value.
     * If this is a `Nothing` {@link Maybe}, returns a `Failure` {@link Result} containing the provided {@link error}.
     *
     * @param error The error to include in the `Failure` {@link Result}.
     */
    getSuccessOr<TError extends NonNullable<unknown>>(error: TError): Result<TValue, TError>;
    /**
     * If this is a `Something` {@link Maybe}, applies {@link f} to the contained value and returns this {@link Maybe}.
     * If this is a `Nothing` {@link Maybe}, returns this {@link Maybe}.
     *
     * @param f The function to apply to the contained value.
     */
    inspect(f: (value: TValue) => void): Maybe<TValue>;
    /**
     * If this is a `Something` {@link Maybe}, returns `false`.
     * If this is a `Nothing` {@link Maybe}, returns `true`.
     */
    isNothing(): boolean;
    /**
     * If this is a `Something` {@link Maybe}, returns the result of applying {@link predicate} to the contained value.
     * If this is a `Nothing` {@link Maybe}, returns `true`.
     *
     * @param predicate The predicate to apply to the contained value.
     */
    isNothingOr(predicate: (value: TValue) => boolean): boolean;
    /**
     * If this is a `Something` {@link Maybe}, returns `true`.
     * If this is a `Nothing` {@link Maybe}, returns `false`.
     */
    isSomething(): boolean;
    /**
     * If this is a `Something` {@link Maybe}, returns the result of applying {@link predicate} to the contained value.
     * If this is a `Nothing` {@link Maybe}, returns `false`.
     *
     * @param predicate The predicate to apply to the contained value.
     */
    isSomethingAnd(predicate: (value: TValue) => boolean): boolean;
    /**
     * If this is a `Something` {@link Maybe}, returns a `Something` {@link Maybe} containing the result of applying {@link f} to the contained value.
     * If this is a `Nothing` {@link Maybe}, returns this {@link Maybe}.
     *
     * @param f The function to apply to the contained value.
     */
    map<TNewValue>(f: (value: TValue) => TNewValue): Maybe<TNewValue>;
    /**
     * If this is a `Something` {@link Maybe}, returns this {@link Maybe}.
     * If this is a `Nothing` {@link Maybe}, returns {@link other}.
     *
     * @param other The {@link Maybe} to return if this is a `Nothing` {@link Maybe}.
     */
    or(other: Maybe<TValue>): Maybe<TValue>;
    toString(): string;
    /**
     * If this is a `Something` {@link Maybe}, returns the contained value.
     * If this is a `Nothing` {@link Maybe}, throws an {@link ImproperUnwrapError}.
     */
    unwrap(): TValue;
}
/**
 * Checks if the provided {@link value} is a {@link Maybe}.
 *
 * @param value The value to check.
 */
declare function isMaybe(value: unknown): value is Maybe<unknown>;
/**
 * Creates and returns a new `Nothing` {@link Maybe}.
 */
declare function nothing<TValue = any>(): Maybe<TValue>;
/**
 * Creates and returns a new `Something` {@link Maybe} containing the provided {@link value}.
 *
 * @param value The value to contain in the new `Something` {@link Maybe}.
 */
declare function something<TValue = any>(value: TValue): Maybe<TValue>;

/**
 * A robust abstraction for handling operations that can either succeed or fail.
 */
declare abstract class Result<TValue, TError extends NonNullable<unknown>> {
    #private;
    [x: symbol]: () => string;
    protected constructor();
    protected abstract _and<TOtherValue>(other: Result<TOtherValue, TError>): Result<TOtherValue, TError>;
    protected abstract _andThen<TOtherValue>(f: (value: TValue) => Result<TOtherValue, TError>): Result<TOtherValue, TError>;
    protected abstract _expect(message: string): TValue;
    protected abstract _expectFailure(message: string): TError;
    protected abstract _getFailure(): Maybe<TError>;
    protected abstract _getSuccess(): Maybe<TValue>;
    protected abstract _inspect(f: (value: TValue) => void): Result<TValue, TError>;
    protected abstract _inspectFailure(f: (error: TError) => void): Result<TValue, TError>;
    protected abstract _isFailure(): boolean;
    protected abstract _isFailureAnd(predicate: (error: TError) => boolean): boolean;
    protected abstract _isSuccess(): boolean;
    protected abstract _isSuccessAnd(predicate: (value: TValue) => boolean): boolean;
    protected abstract _map<TNewValue>(f: (value: TValue) => TNewValue): Result<TNewValue, TError>;
    protected abstract _mapFailure<TNewError extends NonNullable<unknown>>(f: (error: TError) => TNewError): Result<TValue, TNewError>;
    protected abstract _or<TOtherError extends NonNullable<unknown>>(other: Result<TValue, TOtherError>): Result<TValue, TOtherError>;
    protected abstract _unwrap(): TValue;
    protected abstract _unwrapFailure(): TError;
    /**
     * If this is a `Success` {@link Result}, returns {@link other}.
     * If this is a `Failure` {@link Result}, returns this {@link Result}.
     *
     * @param other The {@link Result} to return if this is a `Success` {@link Result}.
     */
    and<TOtherValue>(other: Result<TOtherValue, TError>): Result<TOtherValue, TError>;
    /**
     * If this is a `Success` {@link Result}, returns the result of applying {@link f} to the contained value.
     * If this is a `Failure` {@link Result}, returns this {@link Result}.
     *
     * @param f The function to apply to the contained value.
     */
    andThen<TOtherValue>(f: (value: TValue) => Result<TOtherValue, TError>): Result<TOtherValue, TError>;
    /**
     * If this is a `Success` {@link Result}, returns the contained value.
     * If this is a `Failure` {@link Result}, throws an {@link ExpectationError} with the provided {@link message}.
     *
     * @param message The message to include in the {@link ExpectationError}.
     */
    expect(message: string): TValue;
    /**
     * If this is a `Success` {@link Result}, throws an {@link ExpectationError} with the provided {@link message}.
     * If this is a `Failure` {@link Result}, returns the contained error.
     *
     * @param message The message to include in the {@link ExpectationError}.
     */
    expectFailure(message: string): TError;
    /**
     * If this is a `Success` {@link Result}, returns a `Nothing` {@link Maybe}.
     * If this is a `Failure` {@link Result}, returns a `Something` {@link Maybe} containing the contained error.
     */
    getFailure(): Maybe<TError>;
    /**
     * If this is a `Success` {@link Result}, returns a `Something` {@link Maybe} containing the contained value.
     * If this is a `Failure` {@link Result}, returns a `Nothing` {@link Maybe}.
     */
    getSuccess(): Maybe<TValue>;
    /**
     * If this is a `Success` {@link Result}, applies {@link f} to the contained value and returns this {@link Result}.
     * If this is a `Failure` {@link Result}, returns this {@link Result}.
     *
     * @param f The function to apply to the contained value.
     */
    inspect(f: (value: TValue) => void): Result<TValue, TError>;
    /**
     * If this is a `Success` {@link Result}, returns this {@link Result}.
     * If this is a `Failure` {@link Result}, applies {@link f} to the contained error and returns this {@link Result}.
     *
     * @param f The function to apply to the contained error.
     */
    inspectFailure(f: (error: TError) => void): Result<TValue, TError>;
    /**
     * If this is a `Success` {@link Result}, returns `false`.
     * If this is a `Failure` {@link Result}, returns `true`.
     */
    isFailure(): boolean;
    /**
     * If this is a `Success` {@link Result}, returns `false`.
     * If this is a `Failure` {@link Result}, returns the result of applying {@link predicate} to the contained error.
     *
     * @param predicate The predicate to apply to the contained error.
     */
    isFailureAnd(predicate: (error: TError) => boolean): boolean;
    /**
     * If this is a `Success` {@link Result}, returns `true`.
     * If this is a `Failure` {@link Result}, returns `false`.
     */
    isSuccess(): boolean;
    /**
     * If this is a `Success` {@link Result}, returns the result of applying {@link predicate} to the contained value.
     * If this is a `Failure` {@link Result}, returns `false`.
     *
     * @param predicate The predicate to apply to the contained value.
     */
    isSuccessAnd(predicate: (value: TValue) => boolean): boolean;
    /**
     * If this is a `Success` {@link Result}, returns a `Success` {@link Result} containing the result of applying {@link f} to the contained value.
     * If this is a `Failure` {@link Result}, returns this {@link Result}.
     *
     * @param f The function to apply to the contained value.
     */
    map<TNewValue>(f: (value: TValue) => TNewValue): Result<TNewValue, TError>;
    /**
     * If this is a `Success` {@link Result}, returns this {@link Result}.
     * If this is a `Failure` {@link Result}, returns a `Failure` {@link Result} containing the result of applying {@link f} to the contained error.
     *
     * @param f The function to apply to the contained error.
     */
    mapFailure<TNewError extends NonNullable<unknown>>(f: (error: TError) => TNewError): Result<TValue, TNewError>;
    /**
     * If this is a `Success` {@link Result}, returns this {@link Result}.
     * If this is a `Failure` {@link Result}, returns {@link other}.
     *
     * @param other The {@link Result} to return if this is a `Failure` {@link Result}.
     */
    or<TOtherError extends NonNullable<unknown>>(other: Result<TValue, TOtherError>): Result<TValue, TOtherError>;
    toString(): string;
    /**
     * If this is a `Success` {@link Result}, returns the contained value.
     * If this is a `Failure` {@link Result}, throws an {@link ImproperUnwrapError}.
     */
    unwrap(): TValue;
    /**
     * If this is a `Success` {@link Result}, throws an {@link ImproperUnwrapError}.
     * If this is a `Failure` {@link Result}, returns the contained error.
     */
    unwrapFailure(): TError;
}
/**
 * Checks if the provided {@link value} is a {@link Result}.
 *
 * @param value The value to check.
 */
declare function isResult(value: unknown): value is Result<unknown, NonNullable<unknown>>;
/**
 * Creates and returns a new `Failure` {@link Result} containing the provided {@link error}.
 *
 * @param error The error to contain in the new `Failure` {@link Result}.
 */
declare function failure<TValue = any, TError extends NonNullable<unknown> = any>(error: TError): Result<TValue, TError>;
/**
 * Creates and returns a new `Success` {@link Result} containing the provided {@link value}.
 *
 * @param value The value to contain in the new `Success` {@link Result}.
 */
declare function success<TValue = any, TError extends NonNullable<unknown> = any>(value: TValue): Result<TValue, TError>;

declare class ImproperUnwrapError extends Error {
    constructor(message: string);
}

declare const VERSION: string;

export { ExpectationError, ImproperUnwrapError, Maybe, Result, VERSION, failure, isMaybe, isResult, nothing, something, success };