@ts-rust/std/dist/result/error.d.ts

Rust-inspired utilities for TypeScript: Option, Result, and error handling for safer, more predictable code.

import { AnyError } from "../error";
import { Clone } from "../types";
import type { CheckedError } from "./interface";
/**
 * Enumerates error codes specific to {@link Result} operations.
 *
 * These codes categorize failures in {@link ResultError} instances thrown by methods
 * such as {@link Resultant.unwrap | unwrap} or {@link Resultant.expect | expect}
 * when the result’s state (e.g., {@link Ok} or {@link Err}) doesn’t match the
 * operation’s expectations.
 */
export declare enum ResultErrorKind {
    ErrorAccessedOnOk = "ErrorAccessedOnOk",
    ValueAccessedOnErr = "ValueAccessedOnErr",
    ExpectCalledOnErr = "ExpectCalledOnErr",
    ExpectErrCalledOnOk = "ExpectErrCalledOnOk",
    UnwrapCalledOnErr = "UnwrapCalledOnErr",
    UnwrapErrCalledOnOk = "UnwrapErrCalledOnOk",
    FlattenCalledOnFlatResult = "FlattenCalledOnFlatResult",
    ResultRejection = "ResultRejection",
    PredicateException = "PredicateException",
    FromOptionException = "FromOptionException",
    Unexpected = "Unexpected"
}
/**
 * An error class for {@link Result} operations, extending {@link AnyError} with
 * specific {@link ResultErrorKind} codes.
 *
 * This class represents failures tied to {@link Result} methods, such as accessing
 * a value from an {@link Err} or an error from an {@link Ok}. It provides a structured
 * way to handle such failures by embedding a {@link ResultErrorKind} and an optional
 * `reason` for additional context.
 *
 * @example
 * ```ts
 * const res = err<number, string>("failure");
 * try {
 *   res.unwrap();
 * } catch (e) {
 *   if (isResultError(e)) {
 *     console.log(e.kind); // "UnwrapCalledOnErr"
 *     console.log(e.message); // "[UnwrapCalledOnErr] `unwrap`: called on `Err`."
 *   }
 * }
 * ```
 */
export declare class ResultError extends AnyError<ResultErrorKind> implements Clone<ResultError> {
    /**
     * Creates a deep clone of this {@link ResultError}, duplicating all properties
     * and ensuring no shared references.
     *
     * This method constructs a new {@link ResultError} instance with the same `kind`
     * and a cloned `reason`. Since `kind` is a {@link Primitive}, it is copied as-is,
     * while `reason` (an `Error`) is recreated with its `message` and, if available,
     * its `stack` or `cause`. The `message` and `name` are regenerated to match the
     * original formatting, and the `stack` trace is set to the new instance’s call
     * context (though it may be copied if supported).
     *
     * @returns A new deeply cloned {@link ResultError} instance.
     */
    clone(this: ResultError): ResultError;
}
/**
 * Checks if a value is a {@link ResultError}, narrowing its type if true.
 *
 * @param e - The value to check.
 * @returns `true` if the value is a {@link ResultError}, narrowing to `ResultError`.
 */
export declare function isResultError(e: unknown): e is ResultError;
/**
 * Creates a {@link CheckedError} representing an expected error of type `E`.
 *
 * Use this function to construct an error for anticipated failures, such as
 * validation errors or known conditions.
 *
 * @template E - The type of the expected error.
 * @param error - The expected error value to encapsulate.
 * @returns A {@link CheckedError} containing the expected error.
 */
export declare function expectedError<E>(error: E): CheckedError<E>;
/**
 * Creates a {@link CheckedError} representing an unexpected error.
 *
 * Use this function to construct an error for unforeseen failures, such as runtime
 * exceptions or unhandled conditions, using an existing {@link ResultError}.
 *
 * @template E - The type of a potential expected error (not used here).
 * @param error - The {@link ResultError} representing the unexpected failure.
 * @returns A {@link CheckedError} containing the unexpected error.
 */
export declare function unexpectedError<E>(error: ResultError): CheckedError<E>;
/**
 * Creates a {@link CheckedError} representing an unexpected {@link ResultError}
 * from arguments.
 *
 * Use this overload to construct an error for unforeseen failures by specifying a
 * message, {@link ResultErrorKind}, and optional reason.
 *
 * @template E - The type of a potential expected error (not used here).
 * @param message - A description of the unexpected failure.
 * @param kind - The {@link ResultErrorKind} categorizing the failure.
 * @param reason - An optional underlying cause of the failure.
 * @returns A {@link CheckedError} containing the unexpected error.
 */
export declare function unexpectedError<E>(message: string, kind: ResultErrorKind, reason?: unknown): CheckedError<E>;
/**
 * Checks if a value is a {@link CheckedError}, narrowing its type if true.
 *
 * @param e - The value to check.
 * @returns `true` if the value is a {@link CheckedError}, narrowing to
 *          `CheckedError<unknown>`.
 */
export declare function isCheckedError(e: unknown): e is CheckedError<unknown>;
//# sourceMappingURL=error.d.ts.map