@consolidados/results 0.1.4 → 0.2.0

package/dist/option-B_KKIecf.d.cts

@@ -0,0 +1,352 @@
+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 };