@consolidados/results/dist/types/globals.d.cts

Result types, ease and simple

import { O as Option, N as None, S as Some } from '../option-DpT8KCGE.cjs';

type OkType<T> = [T] extends [never] ? never : T;
type ErrType<E> = [E] extends [never] ? never : E;
/**
 * Represents the result of an operation that can either succeed (`Ok`) or fail (`Err`).
 */
type Result<T, E extends Error> = Ok<OkType<T>> | Err<ErrType<E>>;
/**
 * Represents the result methods that must be implemented for success (`Ok`) or failure (`Err`).
 */
interface ResultDefinition<T = never, E = never> {
    isOk(): this is Ok<T>;
    isErr(): this is Err<E extends Error ? E : Error>;
    unwrap(): T;
    unwrapErr(): E;
    map<U>(fn: (value: T) => U): ResultDefinition<U, E>;
    flatMap<U>(fn: (value: T) => ResultDefinition<U, E>): ResultDefinition<U, E>;
    mapErr<U extends Error>(fn: (err: E) => U): ResultDefinition<T, U>;
    ok(): Option<T>;
}

/**
 * Represents a successful result (`Ok`) that contains a value.
 * @template T The type of the value contained in this `Ok`.
 */
declare class Ok<T> implements ResultDefinition<T, never> {
    private value;
    /**
     * Creates a new `Ok` instance with the given value.
     * @param value The value to wrap in the `Ok` instance.
     */
    constructor(value: T);
    /**
     * Checks if this result is an `Ok`.
     * @returns `true` because this is an `Ok`.
     */
    isOk(): this is Ok<T>;
    /**
     * Checks if this result is an `Err`.
     * @returns `false` because this is an `Ok`.
     */
    isErr(): this is Err<never>;
    /**
     * Retrieves the value contained in this `Ok`.
     * @returns The value contained in this `Ok`.
     */
    unwrap(): T;
    /**
     * Applies a transformation function to the value contained in this `Ok` and returns a new `Result` with the transformed value.
     * @template U The type of the transformed value.
     * @param fn The transformation function to apply to the value.
     * @returns A new `Ok` containing the transformed value.
     */
    map<U>(fn: (value: T) => U): ResultDefinition<U, never>;
    /**
     * Applies a transformation function that returns a `Result` to the value contained in this `Ok`.
     * @template U The type of the value in the resulting `Result`.
     * @param fn The transformation function to apply to the value.
     * @returns The result of applying the transformation function.
     */
    flatMap<U>(fn: (value: T) => ResultDefinition<U, never>): ResultDefinition<U, never>;
    /**
     * Maps the error value (if any). Since this is an `Ok`, the error mapping function is ignored, and the original `Ok` is returned.
     * @template U The type of the error (ignored for `Ok`).
     * @param _fn The mapping function for errors (not used).
     * @returns The original `Ok` instance.
     */
    mapErr<U extends Error>(_fn: (err: never) => U): ResultDefinition<T, U>;
    /**
     * Retrieves the error contained in this result. Since this is an `Ok`, an error is thrown.
     * @throws An error because `unwrapErr` is called on an `Ok`.
     */
    unwrapErr(): never;
    /**
     * Converts `Result` type to `Option` type.
     * @returns `Some` if the result is `Ok`, `None` if the result is `Err`.
     */
    ok(): Option<T>;
}

/**
 * Represents a failed result (`Err`) that contains an error value.
 * @template E The type of the error contained in this `Err`.
 */
declare class Err<E extends Error> extends Error implements ResultDefinition<never, E> {
    private error;
    /**
     * Creates a new `Err` instance with the given error value.
     * @param error The error to wrap in the `Err` instance.
     */
    constructor(error: E | string);
    /**
     * Checks if this result is an `Ok`.
     * @returns `false` because this is an `Err`.
     */
    isOk(): this is Ok<never>;
    /**
     * Checks if this result is an `Err`.
     * @returns `true` because this is an `Err`.
     */
    isErr(): this is Err<E extends Error ? E : Error>;
    /**
     * Retrieves the value contained in this result. Since this is an `Err`, an error is thrown.
     * @throws An error because `unwrap` is called on an `Err`.
     */
    unwrap(): never;
    /**
     * Maps the value (if any). Since this is an `Err`, the mapping function is ignored, and the original `Err` is returned.
     * @template U The type of the value (ignored for `Err`).
     * @param _fn The mapping function for values (not used).
     * @returns The original `Err` instance.
     */
    map<U>(_fn: (value: never) => U): ResultDefinition<never, E>;
    /**
     * Maps the error value using a transformation function and returns a new `Result` with the transformed error.
     * @template U The type of the transformed error.
     * @param fn The transformation function to apply to the error value.
     * @returns A new `Err` containing the transformed error.
     */
    mapErr<U extends Error>(fn: (err: E) => U): ResultDefinition<never, U>;
    /**
     * Applies a transformation function that returns a `Result` to the value (which does not exist) of this `Err`.
     * @template U The type of the value in the resulting `Result`.
     * @param _fn The transformation function (ignored in this implementation).
     * @returns The original `Err` instance.
     */
    flatMap<U>(_fn: (value: never) => ResultDefinition<U, never>): ResultDefinition<never, E>;
    /**
     * Retrieves the error value contained in this `Err`.
     * @returns The error value contained in this `Err`.
     */
    unwrapErr(): E;
    /**
     * Converts `Result` type to `Option` type.
     * @returns `Some` if the result is `Ok`, `None` if the result is `Err`.
     */
    ok(): None;
}

declare global {
    function match<T, E extends Error, R>(matcher: Result<T, E>, cases: {
        Ok: (value: T) => R;
        Err: (error: E) => R;
    }): R;
    function match<T, R>(matcher: Option<T>, cases: {
        Some: (value: T) => R;
        None: () => R;
    }): R;
    function match<T, E extends Error>(matcher: Result<T, E>, cases: {
        Ok: (value: T) => Option<T>;
        Err: (error: E) => Option<T>;
    }): Option<T>;
    function match<T, E extends Error = Error>(matcher: Option<T>, cases: {
        Some: (value: T) => Result<T, E>;
        None: () => Result<T, E>;
    }): Result<T, E>;
    /**
     * Creates a new `Ok` instance, representing a successful result.
     * @template T The type of the value contained in the `Ok`.
     * @param value The value to wrap in the `Ok` instance.
     * @returns An `Ok` instance containing the given value.
     * @example
     * const result = Ok(42);
     * console.log(result.isOk()); // true
     * console.log(result.unwrap()); // 42
     */
    function Ok<T>(value: T): Ok<T>;
    /**
     * Creates a new `Err` instance, representing a failed result.
     * @template E The type of the error contained in the `Err`.
     * @param error The error to wrap in the `Err` instance.
     * @returns An `Err` instance containing the given error.
     * @example
     * const result = Err("Something went wrong");
     * console.log(result.isErr()); // true
     * console.log(result.unwrapErr()); // "Something went wrong"
     */
    function Err<E extends Error>(error: E | string): Err<E>;
    /**
     * creates a new `Some` instance, representing some value.
     * @template T the type of the value contained in the `Some`.
     * @param value the value to wrap in the `some` instance.
     * @returns an `Some` instance containing the given value.
     * @example
     * const option = Some("some value");
     * console.log(option.isSome()); // true
     * console.log(option.unwrap()); // "some value"
     */
    function Some<T>(value: T): Some<T>;
    /**
     * creates a new `None` instance, representing no value.
     * @param  `` There are no paramaters in the `None` instance.
     * @returns an `None` instance containing no value.
     * @example
     * const option = None();
     * console.log(option.isNone()); // true
     * console.log(option.unwrap()); // throws
     */
    function None(): None;
}

export { Err as E, Ok as O, type Result as R };