fluent-results/dist/Result.d.ts

Tiny, dependency-free TypeScript implementation of the Fluent Results pattern for railway-oriented programming.

import { AReason } from './AReason';
import { AError } from './AError';
export declare abstract class AResult {
    /** Informational messages *and* errors gathered so far. */
    protected _reasons: AReason[];
    /** Single‑slot cache for the latest successful value. */
    protected stateCache: any[];
    /** `true` when *no* {@link AError} has been recorded. */
    get isSuccess(): boolean;
    /** `true` when **at least one** {@link AError} exists. */
    get isFailed(): boolean;
    private _routineName;
    /**
     * A descriptive name for the routine, useful for logging or debugging.
     */
    get routineName(): string;
    private _parent?;
    private _child?;
    /**
     * The parent result that created this result (usually as to execute a contingent routine)
     */
    get parent(): AResult | undefined;
    /**
     * A child that was created as a result of execution of a contingent path
     */
    get child(): AResult | undefined;
    protected set child(child: AResult);
    /**
     * @param routineName A descriptive name for the routine, useful for logging or debugging.
     * @param [parent] The parent result that created this result (usually as to execute a contingent routine)
     */
    constructor(routineName: string, parent?: AResult);
}
/**
 * `Result` represents the outcome **and** the flowing state of a pipeline that can
 * short‑circuit on the first error ("railway‑oriented programming").
 *
 * A `Result` starts out *successful* and accumulates {@link AReason | reasons};
 * any {@link AError | error} automatically flips the result into the *failed* state.
 *
 */
export declare class Result<TState = any> extends AResult {
    /**
     * The most recent value produced by the pipeline.
     * @throws {Error}  If no value has been cached yet (typically because the pipeline only ran parameter‑less steps).
     */
    get currentState(): TState;
    /** Immutable copy of informational reasons **and** errors. */
    get reasons(): AReason[];
    /** Convenience subset of {@link reasons} limited to errors. */
    get errors(): AError[];
    /**
   * Executes `action` and wraps its outcome into a new **root** `Result`.
   *
   * • If `action` throws, the exception is captured as an {@link ExceptionalError}.
   * • If it completes successfully, the return value is stored as {@link currentState}.
   *
   * @param action A synchronous delegate that may return a value and/or throw.
   * @param routineName A descriptive name for the routine, useful for logging or debugging.
   */
    static try<T>(action: () => T, routineName: string): Result<T>;
    /**
   * Executes `action` and wraps its awaited outcome into a new **root** `Result`.
   *
   * • If `action` throws, the exception is captured as an {@link ExceptionalError}.
   * • If it completes successfully, the awaited outcome is stored as {@link currentState}.
   *
   * @param action A synchronous delegate that may return a value and/or throw.
   * @param routineName A descriptive name for the routine, useful for logging or debugging.
   */
    static tryAsync<T>(action: () => Promise<T>, routineName: string): Promise<Result<T>>;
    /**
     * Chains another synchronous function into the pipeline.
     *
     * @param func  Delegate to execute.
     *              • If the previous step succeeded, its return value becomes the input when `func` has an arity of **1**.
     *              • If the previous step failed, `func` is **skipped**.
     *
     * @returns **this** so that calls can be fluently chained.
     */
    bind<TRet>(func: (() => TRet) | ((input: TState) => TRet)): Result<TRet>;
    /**
     * Chains another synchronous function into the pipeline and captures its awaited outcome as {@link currentState}.
     *
     * @param func A delegate returning a promise.
     *              • If the previous step succeeded, its return value becomes the input when `func` has an arity of **1**.
     *              • If the previous step failed, `func` is **skipped**.
     *
     * @returns **this** so that calls can be fluently chained.
     */
    bindAsync<TRet>(func: (() => Promise<TRet>) | ((input: TState) => Promise<TRet>)): Promise<Result<TRet>>;
    /**
     * Keeps the pipeline successful **only if** the `predicate` evaluates to `true`.
     *
     * @param predicate  Condition to evaluate (optionally with `currentState` input).
     * @param error      Error instance to push when the predicate fails.
     *
     * @returns **this** for chaining.
     */
    okIf(predicate: (() => boolean) | ((input: TState) => boolean), error: AError): Result<TState>;
    /**
     * Keeps the pipeline successful **only if** the `predicate` evaluates to `true`.
     *
     * @param predicate A function returning promise that returns boolean when awaited (optionally with `currentState` input).
     * @param error      Error instance to push when the predicate fails.
     *
     * @returns **this** for chaining.
     */
    okIfAsync(predicate: (() => Promise<boolean>) | ((input: TState) => Promise<boolean>), error: AError): Promise<Result<TState>>;
    /**
     * Fails the pipeline **only if** the `predicate` evaluates to `true`.
     *
     * @param predicate  Condition to evaluate (optionally with `currentState` input).
     * @param error      Error instance to push when the predicate **passes**.
     * @param [contingency] - Optional object defining a contingent route.
     * @param next.func - A function to be executed if {@link predicate} evaluates to false
     * @param next.routineName - A descriptive name for the routine, useful for logging or debugging.
     *
     * @returns **this** for chaining.
     */
    failIf(predicate: (() => boolean) | ((input: TState) => boolean), error: AError, contingency?: {
        func: (nextResult: Result<TState>) => void;
        routineName: string;
    }): Result<TState>;
    /**
     * Fails the pipeline **only if** the `predicate` evaluates to `true`.
     *
     * @param predicate A function returning promise that returns boolean when awaited (optionally with `currentState` input).
     * @param error      Error instance to push when the predicate **passes**.
     * @param [contingency] - Optional object defining a contingent route.
     * @param next.func - A function to be executed if {@link predicate} evaluates to false
     * @param next.routineName - A descriptive name for the routine, useful for logging or debugging.
     *
     * @returns **this** for chaining.
     */
    failIfAsync(predicate: (() => Promise<boolean>) | ((input: TState) => Promise<boolean>), error: AError, contingency?: {
        func: (nextResult: Result<TState>) => void;
        routineName: string;
    }): Promise<Result<TState>>;
    /**
     * Internal helper—overwrites the single‑slot {@link stateCache}.
     * Not exposed publicly on purpose.
     */
    private cacheState;
}