rustlike-ts/lib/index.d.cts

A Rust-like functional utility library for safe and expressive error handling in TypeScript.

interface Option<T> {
    /**
     * Returns `true` if the option is `Some`, otherwise `false`.
     */
    isSome(): boolean;
    /**
     * Returns `true` if the option is `None`, otherwise `false`.
     */
    isNone(): boolean;
    /**
     * Returns the contained value if `Some`, otherwise throws an error.
     * @throws {OptionError} If called on `None`.
     */
    unwrap(): T;
    /**
     * Returns the contained value if `Some`, otherwise throws an error with the given message.
     * @throws {OptionError} If called on `None`, with the provided message.
     */
    expect(message: string): T;
    /**
     * Returns the contained value if `Some`, otherwise returns the provided default value.
     */
    unwrapOr(or: T): T;
    /**
     * Returns the contained value if `Some`, otherwise computes a value from the given function.
     */
    unwrapOrElse(fn: () => T): T;
    /**
     * Applies a function to the contained value if `Some`, returning a new `Option<T>`.
     * If `None`, returns `None`.
     */
    map(fn: (data: T) => T): Option<T>;
    /**
     * Applies a function to the contained value if `Some`, returning the result.
     * If `None`, returns the provided fallback value.
     */
    mapOr(fallback: T, fn: (data: T) => T): T;
    /**
     * Applies `someFn` if `Some`, otherwise calls `noneFn` and returns its result.
     */
    mapOrElse(noneFn: () => T, someFn: (data: T) => T): T;
    /**
     * Returns `None` if the option is `None`, otherwise returns the provided `Option<T>`.
     */
    and(option: Option<T>): Option<T>;
    /**
     * Returns the option if it is `Some`, otherwise returns the provided alternative `Option<T>`.
     */
    or(or: Option<T>): Option<T>;
    /**
     * Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(result)`.
     */
    okOr<E>(result: E): Result<T, E>;
    /**
     * Transforms the `Option<T>` into a `Result<T, E>`, mapping `Some(v)` to `Ok(v)` and `None` to `Err(errFn())`.
     * Uses a closure to create the error value only when needed.
     */
    okOrElse<E>(errFn: () => E): Result<T, E>;
    /**
     * Applies a function to the contained value if `Some`, returning the resulting `Option<U>`.
     * If `None`, returns `None`.
     */
    andThen<U>(fn: (data: T) => Option<U>): Option<U>;
    /**
     * Returns `Some` if the option is `Some` and the predicate function returns `true`.
     * Otherwise, returns `None`.
     */
    filter(fn: (data: T) => boolean): Option<T>;
}
declare class OptionError extends Error {
    readonly name = "OptionError";
}
declare function Some<T>(data: T): Option<T>;
declare const None: Option<any>;

interface Result<T, E> {
    /**
     * Returns the contained value if the result is `Ok`, otherwise throws an error.
     * @throws {ResultError} If called on `Err`.
     */
    unwrap(): T;
    /**
     * Returns the contained value if the result is `Err`, otherwise throws an error.
     * @throws {ResultError} If called on `Ok`.
     */
    unwrapErr(): E;
    /**
     * Returns the contained value if the result is `Ok`, otherwise returns the provided default value.
     */
    unwrapOr(or: T): T;
    /**
     * Returns the contained value if the result is `Ok`, otherwise computes a default value using the provided function.
     */
    unwrapOrElse(fn: (error: E) => T): T;
    /**
     * Returns the contained value if the result is `Ok`, otherwise throws an error with the provided message.
     * @throws {ResultError} If called on `Err`, with the given message.
     */
    expect(message: string): T;
    /**
     * Returns the contained error if the result is `Err`, otherwise throws an error with the provided message.
     * @throws {ResultError} If called on `Ok`, with the given message.
     */
    expectErr(message: string): E;
    /**
     * Returns `true` if the result is `Ok`, otherwise `false`.
     */
    isOk(): boolean;
    /**
     * Returns `true` if the result is `Err`, otherwise `false`.
     */
    isErr(): boolean;
    /**
     * Converts the `Result<T, E>` into an `Option<T>`, returning `Some(value)` if `Ok`, otherwise `None`.
     */
    ok(): Option<T>;
    /**
     * Converts the `Result<T, E>` into an `Option<E>`, returning `Some(error)` if `Err`, otherwise `None`.
     */
    err(): Option<E>;
    /**
     * Applies a function to the contained `Ok` value, returning a new `Result<T, E>`.
     * If the result is `Err`, it remains unchanged.
     */
    map(fn: (data: T) => T): Result<T, E>;
    /**
     * Applies a function to the contained `Err` value, returning a new `Result<T, E>`.
     * If the result is `Ok`, it remains unchanged.
     */
    mapErr(fn: (err: E) => E): Result<T, E>;
    /**
     * Returns `Err` if the result is `Err`, otherwise returns the provided `Result<U, E>`.
     */
    and<U>(result: Result<U, E>): Result<U, E>;
    /**
     * Applies a function to the `Ok` value and returns a new `Result<U, E>`.
     * If the result is `Err`, it remains unchanged.
     */
    andThen<U>(fn: (data: T) => Result<U, E>): Result<U, E>;
    /**
     * Returns the result if it is `Ok`, otherwise returns the provided alternative `Result<T, E>`.
     */
    or(result: Result<T, E>): Result<T, E>;
    /**
     * Applies a function to the `Err` value and returns a new `Result<T, F>`.
     * If the result is `Ok`, it remains unchanged.
     */
    orElse<F>(fn: (err: E) => Result<T, F>): Result<T, F>;
}
/**
 * Custom error class used for errors within the Result type.
 */
declare class ResultError extends Error {
    readonly name = "ResultError";
}
declare function Ok<T>(data: T): Result<T, any>;
declare function Err<E>(error: E): Result<any, E>;

/**
 * Matches a `Result<T, E>` and executes the corresponding function based on its state.
 * If the `Result` is `Ok`, it calls `op.Ok` with the contained value.
 * If the `Result` is `Err`, it calls `op.Err` with the contained error.
 *
 * @template T - The type of the success value.
 * @template E - The type of the error value.
 * @template R - The return type of the callback functions.
 * @param {Result<T, E>} result - The `Result` instance to match.
 * @param {(data: T) => R} op.Ok - Function to execute if `result` is `Ok`.
 * @param {(error: E) => R} op.Err - Function to execute if `result` is `Err`.
 * @returns {R} - The return value of the executed function.
 */
declare function matchResult<T, E, R = any>(result: Result<T, E>, op: {
    Ok: (data: T) => R;
    Err: (error: E) => R;
}): R;
/**
 * Matches an `Option<T>` and executes the corresponding function based on its state.
 * If the `Option` is `Some`, it calls `op.Some` with the contained value.
 * If the `Option` is `None`, it calls `op.None`.
 *
 * @template T - The type of the value inside `Some`.
 * @template R - The return type of the callback functions.
 * @param {Option<T>} result - The `Option` instance to match.
 * @param {(data: T) => R} op.Some - Function to execute if `result` is `Some`.
 * @param {() => R} op.None - Function to execute if `result` is `None`.
 * @returns {R} - The return value of the executed function.
 */
declare function matchOption<T, R = any>(result: Option<T>, op: {
    Some: (data: T) => R;
    None: () => R;
}): R;
/**
 * Applies a transformation function to each `Some` value in an array of `Option<T>`.
 * If an element is `Some`, it applies `fn` to the contained value.
 * If an element is `None`, it remains `None`.
 *
 * @template T - The type of the value inside `Some`.
 * @param {Option<T>[]} data - The array of `Option<T>` to map over.
 * @param {(data: T) => T} fn - The function to apply to each `Some` value.
 * @returns {Option<T>[]} - A new array with transformed `Some` values.
 */
declare function mapOption<T>(data: Option<T>[], fn: (data: T) => T): Option<T>[];
/**
 * Applies a transformation function to each `Ok` value in an array of `Result<T, E>`.
 * If an element is `Ok`, it applies `fn` to the contained value.
 * If an element is `Err`, it remains unchanged.
 *
 * @template T - The type of the value inside `Ok`.
 * @template E - The type of the error inside `Err`.
 * @param {Result<T, E>[]} data - The array of `Result<T, E>` to map over.
 * @param {(data: T) => T} fn - The function to apply to each `Ok` value.
 * @returns {Result<T, E>[]} - A new array with transformed `Ok` values.
 */
declare function mapResult<T, E>(data: Result<T, E>[], fn: (data: T) => T): Result<T, E>[];
/**
 * Applies a transformation function to each `Some` value in an array of `Option<T>`,
 * and filters out `None` results.
 *
 * @template T - The type of the value inside `Some`.
 * @param {Option<T>[]} data - The array of `Option<T>` to process.
 * @param {(data: T) => Option<T>} fn - The function to apply to each `Some` value.
 * @returns {Option<T>[]} - A new array containing only `Some` values after transformation.
 */
declare function filterMapOption<T>(data: Option<T>[], fn: (data: T) => Option<T>): Option<T>[];
/**
 * Applies a transformation function to each `Ok` value in an array of `Result<T, E>`,
 * and filters out `Err` results.
 *
 * @template T - The type of the value inside `Ok`.
 * @template E - The type of the error inside `Err`.
 * @param {Result<T, E>[]} data - The array of `Result<T, E>` to process.
 * @param {(data: T) => Result<T, E>} fn - The function to apply to each `Ok` value.
 * @returns {Result<T, E>[]} - A new array containing only `Ok` values after transformation.
 */
declare function filterMapResult<T, E>(data: Result<T, E>[], fn: (data: T) => Result<T, E>): Result<T, E>[];

export { Err, None, Ok, type Option, OptionError, type Result, ResultError, Some, filterMapOption, filterMapResult, mapOption, mapResult, matchOption, matchResult };