@consolidados/results
Version:
Result types, ease and simple
353 lines (346 loc) • 14.8 kB
TypeScript
type OkType<T> = [T] extends [never] ? never : T;
type ErrType<E> = [E] extends [never] ? never : E;
/**
* Helper type that converts string errors to Error type,
* but preserves all other types as-is.
*/
/**
* Represents the result of an operation that can either succeed (`Ok`) or fail (`Err`).
*/
type Result<T, E> = 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>;
unwrap(): T;
unwrapErr(): E;
value(): T | E;
map<U>(fn: (value: T) => U): ResultDefinition<U, E>;
flatMap<U>(fn: (value: T) => ResultDefinition<U, E>): ResultDefinition<U, E>;
mapErr<U>(fn: (err: E) => U): ResultDefinition<T, U>;
unwrapOr<U>(defaultValue: U): T | U;
unwrapOrElse<U>(fn: (error: E) => U): T | U;
orElse<F>(fn: (error: E) => ResultDefinition<T, F>): ResultDefinition<T, E | F>;
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;
/**
* Returns the inner value. After an `isOk()` type guard, TypeScript narrows the return type to `T`.
* Without a type guard, returns `T | E` (use `isOk()` or `isErr()` for type narrowing).
* @returns The value contained in this `Ok`.
*/
value(): 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`.
* @template E The type of the error in the resulting `Result`.
* @param fn The transformation function to apply to the value.
* @returns The result of applying the transformation function.
*/
flatMap<U, E = never>(fn: (value: T) => ResultDefinition<U, E>): ResultDefinition<U, E>;
/**
* 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`). Can be any type.
* @param _fn The mapping function for errors (not used).
* @returns The original `Ok` instance.
*/
mapErr<U>(_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;
/**
* Returns the contained value if `Ok`, otherwise returns the provided default value.
* @template U The type of the default value.
* @param defaultValue The value to return if this is an `Err`.
* @returns The value contained in this `Ok`.
*/
unwrapOr<U>(defaultValue: U): T;
/**
* Returns the contained value if `Ok`, otherwise computes and returns the result of the provided function.
* @template U The type of the default value.
* @param fn The function to compute the default value.
* @returns The value contained in this `Ok`.
*/
unwrapOrElse<U>(fn: (error: never) => U): T;
/**
* Returns this `Ok` if it is `Ok`, otherwise returns the result of the provided function.
* @template F The type of the alternative error.
* @param fn The function to compute the alternative result.
* @returns The original `Ok` instance.
*/
orElse<F>(fn: (error: never) => ResultDefinition<T, F>): ResultDefinition<T, F>;
/**
* Converts `Result` type to `Option` type.
* @returns `Some` if the result is `Ok`, `None` if the result is `Err`.
*/
ok(): Some<T>;
}
/**
* Represents a failed result (`Err`) that contains an error value.
* @template E The type of the error contained in this `Err`. Can be any type (Error, string, enum, etc).
*/
declare class Err<E> 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. Can be any type.
*/
constructor(error: E);
/**
* 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>;
/**
* 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. Can be any type.
* @param fn The transformation function to apply to the error value.
* @returns A new `Err` containing the transformed error.
*/
mapErr<U>(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`.
* @template F The type of the error in the resulting `Result`.
* @param _fn The transformation function (ignored in this implementation).
* @returns The original `Err` instance cast to the new error type.
*/
flatMap<U, F = E>(_fn: (value: never) => ResultDefinition<U, F>): ResultDefinition<U, E>;
/**
* Retrieves the error value contained in this `Err`.
* @returns The error value contained in this `Err`.
*/
unwrapErr(): E;
/**
* Returns the inner error. After an `isErr()` type guard, TypeScript narrows the return type to `E`.
* Without a type guard, returns `T | E` (use `isOk()` or `isErr()` for type narrowing).
* @returns The error value contained in this `Err`.
*/
value(): E;
/**
* Returns the contained value if `Ok`, otherwise returns the provided default value.
* @template U The type of the default value.
* @param defaultValue The value to return since this is an `Err`.
* @returns The provided default value.
*/
unwrapOr<U>(defaultValue: U): U;
/**
* Returns the contained value if `Ok`, otherwise computes and returns the result of the provided function.
* @template U The type of the default value.
* @param fn The function to compute the default value.
* @returns The result of calling the provided function with the error.
*/
unwrapOrElse<U>(fn: (error: E) => U): U;
/**
* Returns this `Err` if it is `Err`, otherwise returns the result of the provided function.
* @template T The type of the alternative success value.
* @template F The type of the alternative error.
* @param fn The function to compute the alternative result.
* @returns The result of calling the provided function with the error.
*/
orElse<T, F>(fn: (error: E) => ResultDefinition<T, F>): ResultDefinition<T, F>;
/**
* Converts `Result` type to `Option` type.
* @returns `Some` if the result is `Ok`, `None` if the result is `Err`.
*/
ok(): None;
}
/**
* Represents a `Some` option, which holds a value.
* @template T The type of the value held by this `Some` instance.
*/
declare class Some<T> {
private _value;
/**
* Creates a new `Some` option with the given value.
* @param _value The value to be wrapped in the `Some` option.
*/
constructor(_value: T);
/**
* Checks if this option is a `Some`.
* @returns `true` if this option is a `Some`, otherwise `false`.
*/
isSome(): this is Some<T>;
/**
* Checks if this option is a `None`.
* @returns `false` because this is a `Some`.
*/
isNone(): this is None;
/**
* Unwraps the value held by this `Some` option.
* @returns The value held by this `Some` option.
*/
unwrap(): T;
/**
* Returns the inner value. After an `isSome()` type guard, TypeScript narrows the return type to `T`.
* Without a type guard, returns `T | undefined` (use `isSome()` or `isNone()` for type narrowing).
* @returns The value held by this `Some` option.
*/
value(): T;
/**
* Applies a transformation function to the value held by this `Some` option and returns a new `Option` 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 `Some` option containing the transformed value.
*/
map<U>(fn: (value: T) => U): Option<U>;
/**
* Applies a transformation function that returns an `Option` to the value held by this `Some` option.
* @template U The type of the value in the resulting `Option`.
* @param fn The transformation function to apply to the value.
* @returns The result of applying the transformation function.
*/
flatMap<U>(fn: (value: T) => Option<U>): Option<U>;
/**
* Returns the value held by this `Some` option, ignoring the default value provided.
* @param _ A default value (ignored in this implementation).
* @returns The value held by this `Some` option.
*/
unwrapOr(_: T): T;
/**
* Returns the value held by this `Some` option, ignoring the function provided.
* @template U The type of the default value.
* @param _fn A function to compute the default value (ignored in this implementation).
* @returns The value held by this `Some` option.
*/
unwrapOrElse<U>(_fn: () => U): T;
/**
* Converts this `Option` to a `Result`, using the provided error value if this is `None`.
* @template E The type of the error.
* @param _error The error value to use if this is `None` (ignored since this is `Some`).
* @returns An `Ok` result containing the value from this `Some`.
*/
okOr<E>(_error: E): Ok<T>;
/**
* Filters this `Option` based on a predicate function.
* @param predicate The function to test the value.
* @returns This `Some` if the predicate returns true, otherwise `None`.
*/
filter(predicate: (value: T) => boolean): Option<T>;
}
/**
* Represents a `None` option, which holds no value.
*/
declare class None {
/**
* Checks if this option is a `Some`.
* @returns `false` because this is a `None`.
*/
isSome(): this is Some<never>;
/**
* Checks if this option is a `None`.
* @returns `true` because this is a `None`.
*/
isNone(): this is None;
/**
* Attempts to unwrap the value from this `None` option.
* @throws An error because `None` has no value.
*/
unwrap(): never;
/**
* Returns `undefined` for a `None` option. After an `isNone()` type guard, TypeScript narrows the return type to `undefined`.
* Without a type guard, returns `T | undefined` (use `isSome()` or `isNone()` for type narrowing).
* Unlike `unwrap()`, this method does not throw an error.
* @returns `undefined` because this is a `None`.
*/
value(): undefined;
/**
* Applies a transformation function to the value (which does not exist) of this `None` option.
* @template U The type of the value that would have been returned.
* @param _fn The transformation function (ignored in this implementation).
* @returns The singleton `None` instance.
*/
map<U>(_fn: (value: never) => U): Option<U>;
/**
* Applies a transformation function that returns an `Option` to the value (which does not exist) of this `None` option.
* @template U The type of the value in the resulting `Option`.
* @param _fn The transformation function (ignored in this implementation).
* @returns The singleton `None` instance.
*/
flatMap<U>(_fn: (value: never) => Option<U>): Option<U>;
/**
* Returns the default value provided, since `None` has no value.
* @template T The type of the default value.
* @param defaultValue The value to return.
* @returns The default value provided.
*/
unwrapOr<T>(defaultValue: T): T;
/**
* Computes and returns the default value using the provided function, since `None` has no value.
* @template T The type of the default value.
* @param fn The function to compute the default value.
* @returns The result of calling the provided function.
*/
unwrapOrElse<T>(fn: () => T): T;
/**
* Converts this `Option` to a `Result`, using the provided error value since this is `None`.
* @template E The type of the error.
* @param error The error value to use.
* @returns An `Err` result containing the provided error.
*/
okOr<E>(error: E): Err<E>;
/**
* Filters this `Option` based on a predicate function.
* @param _predicate The function to test the value (ignored since this is `None`).
* @returns `None` since there is no value to filter.
*/
filter<T>(_predicate: (value: never) => boolean): Option<T>;
}
/**
* Represents an optional value that can either be `Some` (with a value) or `None` (no value).
*/
type Option<T> = Some<T> | None;
export { Err as E, None as N, type Option as O, type Result as R, Some as S, Ok as a };