ts-data-forge 1.0.0 → 1.0.1

package/dist/functional/result.d.mts

@@ -0,0 +1,796 @@
+import { Optional } from './optional.mjs';
+/** @internal Symbol to identify the 'Ok' variant of Result. */
+declare const OkTypeSymbol: unique symbol;
+/** @internal Symbol to identify the 'Err' variant of Result. */
+declare const ErrTypeSymbol: unique symbol;
+/**
+ * @internal
+ * Represents the 'Ok' variant of a Result, containing a success value.
+ * @template S The type of the success value.
+ */
+type Ok_<S> = Readonly<{
+    /** Discriminant property for the 'Ok' type. */
+    type: typeof OkTypeSymbol;
+    /** The success value. */
+    value: S;
+}>;
+/**
+ * @internal
+ * Represents the 'Err' variant of a Result, containing an error value.
+ * @template E The type of the error value.
+ */
+type Err_<E> = Readonly<{
+    /** Discriminant property for the 'Err' type. */
+    type: typeof ErrTypeSymbol;
+    /** The error value. */
+    value: E;
+}>;
+/**
+ * Represents a value that can either be a success (`Ok`) or an error (`Err`).
+ * @template S The type of the success value.
+ * @template E The type of the error value.
+ */
+export type Result<S, E> = Ok_<S> | Err_<E>;
+/**
+ * Namespace for the `Result` type and related functions.
+ * Provides utilities to handle operations that can succeed or fail.
+ */
+export declare namespace Result {
+    /**
+     * Checks if the given value is a `Result`.
+     * @param maybeOptional The value to check.
+     * @returns `true` if the value is a `Result`, otherwise `false`.
+     */
+    export const isResult: (maybeOptional: unknown) => maybeOptional is Result<unknown, unknown>;
+    /**
+     * Represents a `Result` that is a success, containing a value.
+     * @template S The type of the success value.
+     */
+    export type Ok<S> = Ok_<S>;
+    /**
+     * Represents a `Result` that is an error, containing an error value.
+     * @template E The type of the error value.
+     */
+    export type Err<E> = Err_<E>;
+    /**
+     * Base type for any `Result`, used for generic constraints.
+     * Represents a `Result` with unknown success and error types.
+     */
+    export type Base = Result<unknown, unknown>;
+    /**
+     * Extracts the success value type `S` from a `Result.Ok<S>`.
+     * If the `Result` is `Result.Err<E>`, resolves to `never`.
+     * @template R The `Result.Base` type to unwrap.
+     */
+    export type UnwrapOk<R extends Base> = R extends Ok<infer S> ? S : never;
+    /**
+     * Extracts the error value type `E` from a `Result.Err<E>`.
+     * If the `Result` is `Result.Ok<S>`, resolves to `never`.
+     * @template R The `Result.Base` type to unwrap.
+     */
+    export type UnwrapErr<R extends Base> = R extends Err<infer E> ? E : never;
+    /**
+     * Narrows a `Result.Base` type to `Result.Ok<S>` if it is an `Ok`.
+     * If the `Result` is `Result.Err<E>`, resolves to `never`.
+     * @template R The `Result.Base` type to narrow.
+     */
+    export type NarrowToOk<R extends Base> = R extends Err<unknown> ? never : R;
+    /**
+     * Narrows a `Result.Base` type to `Result.Err<E>` if it is an `Err`.
+     * If the `Result` is `Result.Ok<S>`, resolves to `never`.
+     * @template R The `Result.Base` type to narrow.
+     */
+    export type NarrowToErr<R extends Base> = R extends Ok<unknown> ? never : R;
+    /**
+     * Creates a `Result.Ok` containing the given success value.
+     *
+     * Use this constructor when an operation succeeds and you want to wrap
+     * the successful result in a Result type for consistent error handling.
+     *
+     * @template S The type of the success value.
+     * @param value The success value.
+     * @returns A `Result.Ok<S>` containing the value.
+     * @example
+     * ```typescript
+     * // Basic success case
+     * const success = Result.ok(42);
+     * console.log(Result.isOk(success)); // true
+     * console.log(Result.unwrapOk(success)); // 42
+     *
+     * // Function that returns a Result
+     * function divide(a: number, b: number): Result<number, string> {
+     *   if (b === 0) {
+     *     return Result.err("Division by zero");
+     *   }
+     *   return Result.ok(a / b);
+     * }
+     *
+     * const result = divide(10, 2);
+     * console.log(Result.unwrapOk(result)); // 5
+     * ```
+     */
+    export const ok: <S>(value: S) => Ok<S>;
+    /**
+     * Creates a `Result.Err` containing the given error value.
+     *
+     * Use this constructor when an operation fails and you want to wrap
+     * the error information in a Result type for consistent error handling.
+     *
+     * @template E The type of the error value.
+     * @param value The error value.
+     * @returns A `Result.Err<E>` containing the value.
+     * @example
+     * ```typescript
+     * // Basic error case
+     * const failure = Result.err("Something went wrong");
+     * console.log(Result.isErr(failure)); // true
+     * console.log(Result.unwrapErr(failure)); // "Something went wrong"
+     *
+     * // Function that can fail
+     * function parseInteger(input: string): Result<number, string> {
+     *   const num = parseInt(input, 10);
+     *   if (isNaN(num)) {
+     *     return Result.err(`Invalid number format: ${input}`);
+     *   }
+     *   return Result.ok(num);
+     * }
+     *
+     * const result = parseInteger("abc");
+     * console.log(Result.unwrapErr(result)); // "Invalid number format: abc"
+     *
+     * // Using custom error types
+     * interface ValidationError {
+     *   field: string;
+     *   message: string;
+     * }
+     *
+     * const validationError = Result.err<ValidationError>({
+     *   field: "email",
+     *   message: "Invalid email format"
+     * });
+     * ```
+     */
+    export const err: <E>(value: E) => Err<E>;
+    /**
+     * Checks if a `Result` is `Result.Ok`.
+     * Acts as a type guard, narrowing the type to the success variant.
+     *
+     * This function is essential for type-safe Result handling, allowing
+     * TypeScript to understand that subsequent operations will work with
+     * the success value rather than the error value.
+     *
+     * @template R The `Result.Base` type to check.
+     * @param result The `Result` to check.
+     * @returns `true` if the `Result` is `Result.Ok`, otherwise `false`.
+     * @example
+     * ```typescript
+     * // Basic type guard usage
+     * const result: Result<number, string> = divide(10, 2);
+     *
+     * if (Result.isOk(result)) {
+     *   // TypeScript knows result is Result.Ok<number>
+     *   console.log(result.value); // Safe to access .value
+     *   console.log(Result.unwrapOk(result)); // 5
+     * } else {
+     *   // TypeScript knows result is Result.Err<string>
+     *   console.log(result.value); // Error message
+     * }
+     *
+     * // Using in conditional logic
+     * const processResult = (r: Result<string, Error>) => {
+     *   return Result.isOk(r)
+     *     ? r.value.toUpperCase() // Safe string operations
+     *     : "Error occurred";
+     * };
+     *
+     * // Filtering arrays of Results
+     * const results: Result<number, string>[] = [
+     *   Result.ok(1),
+     *   Result.err("error"),
+     *   Result.ok(2)
+     * ];
+     * const successes = results.filter(Result.isOk);
+     * // successes is Result.Ok<number>[]
+     * ```
+     */
+    export const isOk: <R extends Base>(result: R) => result is NarrowToOk<R>;
+    /**
+     * Checks if a `Result` is `Result.Err`.
+     * Acts as a type guard, narrowing the type to the error variant.
+     *
+     * This function is essential for type-safe Result handling, allowing
+     * TypeScript to understand that subsequent operations will work with
+     * the error value rather than the success value.
+     *
+     * @template R The `Result.Base` type to check.
+     * @param result The `Result` to check.
+     * @returns `true` if the `Result` is `Result.Err`, otherwise `false`.
+     * @example
+     * ```typescript
+     * // Basic type guard usage
+     * const result: Result<number, string> = divide(10, 0);
+     *
+     * if (Result.isErr(result)) {
+     *   // TypeScript knows result is Result.Err<string>
+     *   console.log(result.value); // Safe to access error .value
+     *   console.log(Result.unwrapErr(result)); // "Division by zero"
+     * } else {
+     *   // TypeScript knows result is Result.Ok<number>
+     *   console.log(result.value); // Success value
+     * }
+     *
+     * // Error handling patterns
+     * const handleResult = (r: Result<Data, ApiError>) => {
+     *   if (Result.isErr(r)) {
+     *     logError(r.value); // Safe error operations
+     *     return null;
+     *   }
+     *   return processData(r.value);
+     * };
+     *
+     * // Collecting errors from multiple Results
+     * const results: Result<string, ValidationError>[] = validateForm();
+     * const errors = results
+     *   .filter(Result.isErr)
+     *   .map(err => err.value); // ValidationError[]
+     * ```
+     */
+    export const isErr: <R extends Base>(result: R) => result is NarrowToErr<R>;
+    /**
+     * Unwraps a `Result`, returning the success value.
+     * Throws an error if the `Result` is `Result.Err`.
+     *
+     * This is useful when you're confident that a Result should contain a success value
+     * and want to treat errors as exceptional conditions. The error message will be
+     * constructed from the error value using the provided string conversion function.
+     *
+     * @template R The `Result.Base` type to unwrap.
+     * @param result The `Result` to unwrap.
+     * @param toStr An optional function to convert the error value to a string for the error message. Defaults to `String`.
+     * @returns The success value if `Result.Ok`.
+     * @throws {Error} Error with the stringified error value if the `Result` is `Result.Err`.
+     * @example
+     * ```typescript
+     * // Basic usage with default string conversion
+     * const success = Result.ok(42);
+     * console.log(Result.unwrapThrow(success)); // 42
+     *
+     * const failure = Result.err("Network error");
+     * try {
+     *   Result.unwrapThrow(failure); // throws Error: "Network error"
+     * } catch (error) {
+     *   console.log(error.message); // "Network error"
+     * }
+     *
+     * // Custom error string conversion
+     * interface ApiError {
+     *   code: number;
+     *   message: string;
+     * }
+     *
+     * const apiResult = Result.err<ApiError>({ code: 404, message: "Not found" });
+     * try {
+     *   Result.unwrapThrow(apiResult, err => `API Error ${err.code}: ${err.message}`);
+     * } catch (error) {
+     *   console.log(error.message); // "API Error 404: Not found"
+     * }
+     *
+     * // In contexts where failure is unexpected
+     * const configResult = loadConfiguration();
+     * const config = Result.unwrapThrow(configResult, err =>
+     *   `Failed to load configuration: ${err}`
+     * ); // Will throw if config loading fails
+     * ```
+     */
+    export const unwrapThrow: <R extends Base>(result: R, toStr?: (e: UnwrapErr<R>) => string) => UnwrapOk<R>;
+    /**
+     * Unwraps a `Result`, returning the success value or `undefined` if it's an error.
+     *
+     * This function provides a safe way to extract success values from Results without
+     * throwing exceptions. It has overloaded behavior based on the type:
+     * - For `Result.Ok<T>`: Always returns `T` (guaranteed by type system)
+     * - For general `Result<T, E>`: Returns `T | undefined`
+     *
+     * @template R The `Result.Base` type to unwrap.
+     * @param result The `Result` to unwrap.
+     * @returns The success value if `Result.Ok`, otherwise `undefined`.
+     * @example
+     * ```typescript
+     * // With guaranteed Ok - returns the value
+     * const success = Result.ok(42);
+     * const value = Result.unwrapOk(success); // Type: number, Value: 42
+     *
+     * // With general Result - may return undefined
+     * const maybeResult: Result<string, Error> = fetchData();
+     * const data = Result.unwrapOk(maybeResult); // Type: string | undefined
+     *
+     * // Safe pattern for handling both cases
+     * const result = Result.ok("hello");
+     * const unwrapped = Result.unwrapOk(result);
+     * if (unwrapped !== undefined) {
+     *   console.log(unwrapped.toUpperCase()); // "HELLO"
+     * }
+     *
+     * // Useful in conditional chains
+     * const processResult = (r: Result<number, string>) => {
+     *   const value = Result.unwrapOk(r);
+     *   return value !== undefined ? value * 2 : 0;
+     * };
+     * ```
+     */
+    export const unwrapOk: UnwrapOkFnOverload;
+    type UnwrapOkFnOverload = {
+        <R extends Ok<unknown>>(result: R): UnwrapOk<R>;
+        <R extends Base>(result: R): UnwrapOk<R> | undefined;
+    };
+    /**
+     * Unwraps a `Result`, returning the success value or a default value if it is `Result.Err`.
+     * @template R The `Result.Base` type to unwrap.
+     * @template D The type of the default value.
+     * @param result The `Result` to unwrap.
+     * @param defaultValue The value to return if `result` is `Result.Err`.
+     * @returns The success value if `Result.Ok`, otherwise `defaultValue`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.ok(42);
+     * const value = Result.unwrapOkOr(result, 0);
+     * console.log(value); // 42
+     *
+     * // Curried usage for pipe composition
+     * const unwrapWithDefault = Result.unwrapOkOr(0);
+     * const value2 = pipe(Result.err("error")).map(unwrapWithDefault).value;
+     * console.log(value2); // 0
+     * ```
+     */
+    export const unwrapOkOr: UnwrapOkOrFnOverload;
+    type UnwrapOkOrFnOverload = {
+        <R extends Base, D>(result: R, defaultValue: D): D | UnwrapOk<R>;
+        <S, D>(defaultValue: D): <E>(result: Result<S, E>) => D | S;
+    };
+    /**
+     * Unwraps a `Result`, returning the error value.
+     * Throws an error if the `Result` is `Result.Ok`.
+     *
+     * This function is used when you expect a Result to be an error and want to
+     * extract the error value. If the Result is unexpectedly Ok, it will throw
+     * an error with information about the unexpected success value.
+     *
+     * @template R The `Result.Base` type to unwrap.
+     * @param result The `Result` to unwrap.
+     * @param toStr An optional function to convert the success value to a string for the error message when the Result is unexpectedly Ok. Defaults to `String`.
+     * @returns The error value if `Result.Err`.
+     * @throws {Error} Error with message "Expected Err but got Ok: {value}" if the `Result` is `Result.Ok`.
+     * @example
+     * ```typescript
+     * // Basic usage - extracting error from known failure
+     * const failure = Result.err("Network timeout");
+     * console.log(Result.unwrapErrThrow(failure)); // "Network timeout"
+     *
+     * // Throws when Result is unexpectedly Ok
+     * const success = Result.ok(42);
+     * try {
+     *   Result.unwrapErrThrow(success); // throws Error: "Expected Err but got Ok: 42"
+     * } catch (error) {
+     *   console.log(error.message); // "Expected Err but got Ok: 42"
+     * }
+     *
+     * // Custom success value string conversion
+     * interface User { name: string; id: number; }
+     * const userResult = Result.ok<User>({ name: "John", id: 123 });
+     * try {
+     *   Result.unwrapErrThrow(userResult, user => `User(${user.name}:${user.id})`);
+     * } catch (error) {
+     *   console.log(error.message); // "Expected Err but got Ok: User(John:123)"
+     * }
+     *
+     * // In error handling contexts
+     * const validateAndGetError = (result: Result<any, ValidationError>) => {
+     *   if (Result.isErr(result)) {
+     *     return Result.unwrapErrThrow(result); // Safe to unwrap error
+     *   }
+     *   throw new Error("Validation unexpectedly succeeded");
+     * };
+     * ```
+     */
+    export const unwrapErrThrow: <R extends Base>(result: R, toStr?: (v: UnwrapOk<R>) => string) => UnwrapErr<R>;
+    /**
+     * Unwraps a `Result`, returning the error value or `undefined` if it is `Result.Ok`.
+     *
+     * This provides a safe way to extract error values from Results without throwing
+     * exceptions. Useful for error handling patterns where you want to check for
+     * specific error conditions.
+     *
+     * @template R The `Result.Base` type to unwrap.
+     * @param result The `Result` to unwrap.
+     * @returns The error value if `Result.Err`, otherwise `undefined`.
+     * @example
+     * ```typescript
+     * // Basic error extraction
+     * const failure = Result.err("Connection failed");
+     * console.log(Result.unwrapErr(failure)); // "Connection failed"
+     *
+     * const success = Result.ok(42);
+     * console.log(Result.unwrapErr(success)); // undefined
+     *
+     * // Error handling patterns
+     * const handleApiCall = (result: Result<Data, ApiError>) => {
+     *   const error = Result.unwrapErr(result);
+     *   if (error !== undefined) {
+     *     switch (error.type) {
+     *       case "NETWORK_ERROR":
+     *         return retry(result);
+     *       case "AUTH_ERROR":
+     *         return redirectToLogin();
+     *       default:
+     *         return showGenericError(error);
+     *     }
+     *   }
+     *   // Handle success case...
+     * };
+     *
+     * // Collecting errors from multiple operations
+     * const results = await Promise.all([
+     *   operation1(),
+     *   operation2(),
+     *   operation3()
+     * ]);
+     *
+     * const errors = results
+     *   .map(Result.unwrapErr)
+     *   .filter(err => err !== undefined); // Only actual errors
+     * ```
+     */
+    export const unwrapErr: <R extends Base>(result: R) => UnwrapErr<R> | undefined;
+    /**
+     * Unwraps a `Result`, returning the error value or a default value if it is `Result.Ok`.
+     * @template R The `Result.Base` type to unwrap.
+     * @template D The type of the default value.
+     * @param result The `Result` to unwrap.
+     * @param defaultValue The value to return if `result` is `Result.Ok`.
+     * @returns The error value if `Result.Err`, otherwise `defaultValue`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.err("failed");
+     * const error = Result.unwrapErrOr(result, "default");
+     * console.log(error); // "failed"
+     *
+     * // Curried usage for pipe composition
+     * const unwrapErrorWithDefault = Result.unwrapErrOr("unknown error");
+     * const error2 = pipe(Result.ok(42)).map(unwrapErrorWithDefault).value;
+     * console.log(error2); // "unknown error"
+     * ```
+     */
+    export const unwrapErrOr: UnwrapErrOrFnOverload;
+    type UnwrapErrOrFnOverload = {
+        <R extends Base, D>(result: R, defaultValue: D): D | UnwrapErr<R>;
+        <E, D>(defaultValue: D): <S>(result: Result<S, E>) => D | E;
+    };
+    /**
+     * Maps a `Result<S, E>` to `Result<S2, E>` by applying a function to the success value.
+     * If the `Result` is `Result.Err`, returns the original `Err`.
+     * @template R The input `Result.Base` type.
+     * @template S2 The type of the success value returned by the mapping function.
+     * @param result The `Result` to map.
+     * @param mapFn The function to apply to the success value if present.
+     * @returns A new `Result<S2, UnwrapErr<R>>`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.ok(5);
+     * const mapped = Result.map(result, x => x * 2);
+     * console.log(Result.unwrap(mapped)); // 10
+     *
+     * // Curried version for use with pipe
+     * const doubler = Result.map((x: number) => x * 2);
+     * const result2 = pipe(Result.ok(5)).map(doubler).value;
+     * console.log(Result.unwrap(result2)); // 10
+     * ```
+     */
+    export const map: MapFnOverload;
+    type MapFnOverload = {
+        <R extends Base, S2>(result: R, mapFn: (value: UnwrapOk<R>) => S2): Result<S2, UnwrapErr<R>>;
+        <S, S2>(mapFn: (value: S) => S2): <E>(result: Result<S, E>) => Result<S2, E>;
+    };
+    /**
+     * Maps a `Result<S, E>` to `Result<S, E2>` by applying a function to the error value.
+     * If the `Result` is `Result.Ok`, returns the original `Ok`.
+     * @template R The input `Result.Base` type.
+     * @template E2 The type of the error value returned by the mapping function.
+     * @param result The `Result` to map.
+     * @param mapFn The function to apply to the error value if present.
+     * @returns A new `Result<UnwrapOk<R>, E2>`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.err("error");
+     * const mapped = Result.mapErr(result, e => e.toUpperCase());
+     * console.log(Result.unwrapErr(mapped)); // "ERROR"
+     *
+     * // Curried usage for pipe composition
+     * const errorUppercase = Result.mapErr((e: string) => e.toUpperCase());
+     * const result2 = pipe(Result.err("error")).map(errorUppercase).value;
+     * console.log(Result.unwrapErr(result2)); // "ERROR"
+     * ```
+     */
+    export const mapErr: MapErrFnOverload;
+    type MapErrFnOverload = {
+        <R extends Base, E2>(result: R, mapFn: (error: UnwrapErr<R>) => E2): Result<UnwrapOk<R>, E2>;
+        <E, E2>(mapFn: (error: E) => E2): <S>(result: Result<S, E>) => Result<S, E2>;
+    };
+    /**
+     * Applies one of two functions depending on whether the `Result` is `Ok` or `Err`.
+     * @template R The input `Result.Base` type.
+     * @template S2 The type of the success value returned by `mapFn`.
+     * @template E2 The type of the error value returned by `mapErrFn`.
+     * @param result The `Result` to fold.
+     * @param mapFn The function to apply if `result` is `Ok`.
+     * @param mapErrFn The function to apply if `result` is `Err`.
+     * @returns A new `Result<S2, E2>` based on the applied function.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.ok(42);
+     * const folded = Result.fold(result, x => x * 2, () => 0);
+     * console.log(Result.unwrapOk(folded)); // 84
+     *
+     * // Curried usage for pipe composition
+     * const folder = Result.fold((x: number) => x * 2, () => 0);
+     * const result2 = pipe(Result.ok(42)).map(folder).value;
+     * console.log(Result.unwrapOk(result2)); // 84
+     * ```
+     */
+    export const fold: FoldFnOverload;
+    type FoldFnOverload = {
+        <R extends Base, S2, E2>(result: R, mapFn: (value: UnwrapOk<R>) => S2, mapErrFn: (error: UnwrapErr<R>) => E2): Result<S2, E2>;
+        <S, E, S2, E2>(mapFn: (value: S) => S2, mapErrFn: (error: E) => E2): (result: Result<S, E>) => Result<S2, E2>;
+    };
+    /**
+     * Applies a function that returns a `Result` to the success value of a `Result`.
+     * If the input is `Err`, returns the original `Err`.
+     * This is the monadic bind operation for `Result`.
+     * @template R The input `Result.Base` type.
+     * @template S2 The success type of the `Result` returned by the function.
+     * @template E2 The error type of the `Result` returned by the function.
+     * @param result The `Result` to flat map.
+     * @param flatMapFn The function to apply that returns a `Result`.
+     * @returns The result of applying the function, or the original `Err`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const divide = (a: number, b: number): Result<number, string> =>
+     *   b === 0 ? Result.err("Division by zero") : Result.ok(a / b);
+     *
+     * const result = Result.flatMap(Result.ok(10), x => divide(x, 2));
+     * console.log(Result.unwrapOk(result)); // 5
+     *
+     * // Curried usage for pipe composition
+     * const divideBy2 = Result.flatMap((x: number) => divide(x, 2));
+     * const result2 = pipe(Result.ok(10)).map(divideBy2).value;
+     * console.log(Result.unwrapOk(result2)); // 5
+     * ```
+     */
+    export const flatMap: FlatMapFnOverload;
+    type FlatMapFnOverload = {
+        <R extends Base, S2, E2>(result: R, flatMapFn: (value: UnwrapOk<R>) => Result<S2, E2>): Result<S2, E2 | UnwrapErr<R>>;
+        <S, S2, E2>(flatMapFn: (value: S) => Result<S2, E2>): <E>(result: Result<S, E>) => Result<S2, E | E2>;
+    };
+    /**
+     * Unwraps a `Result`, returning the success value or throwing an error with the provided message.
+     * @template R The `Result.Base` type to unwrap.
+     * @param result The `Result` to unwrap.
+     * @param message The error message to throw if the `Result` is `Result.Err`.
+     * @returns The success value if `Result.Ok`.
+     * @throws Error with the provided message if the `Result` is `Result.Err`.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const result = Result.ok(42);
+     * const value = Result.expectToBe(result, "Operation must succeed");
+     * console.log(value); // 42
+     *
+     * // Curried usage for pipe composition
+     * const mustBeOk = Result.expectToBe("Operation must succeed");
+     * const value2 = pipe(Result.ok(42)).map(mustBeOk).value;
+     * console.log(value2); // 42
+     * ```
+     */
+    export const expectToBe: ExpectToBeFnOverload;
+    type ExpectToBeFnOverload = {
+        <R extends Base>(result: R, message: string): UnwrapOk<R>;
+        <S>(message: string): <E>(result: Result<S, E>) => S;
+    };
+    /**
+     * @internal
+     * Utility type to extract the resolved value type from a Promise.
+     * @template P The Promise type.
+     * @example
+     * UnwrapPromise<Promise<string>> // string
+     * UnwrapPromise<Promise<number>> // number
+     */
+    type UnwrapPromise<P extends Promise<unknown>> = P extends Promise<infer V> ? V : never;
+    /**
+     * Converts a Promise into a Promise that resolves to a `Result`.
+     * If the input Promise resolves, the `Result` will be `Ok` with the resolved value.
+     * If the input Promise rejects, the `Result` will be `Err` with the rejection reason.
+     * @template P The type of the input Promise.
+     * @param promise The Promise to convert.
+     * @returns A Promise that resolves to `Result<UnwrapPromise<P>, unknown>`.
+     */
+    export const fromPromise: <P extends Promise<unknown>>(promise: P) => Promise<Result<UnwrapPromise<P>, unknown>>;
+    /**
+     * Wraps a function that may throw an exception in a `Result`.
+     *
+     * This is a fundamental utility for converting traditional exception-based error
+     * handling into Result-based error handling. Any thrown value is converted to an
+     * Error object for consistent error handling.
+     *
+     * If the function executes successfully, returns `Result.Ok` with the result.
+     * If the function throws, returns `Result.Err` with the caught error.
+     *
+     * @template T The return type of the function.
+     * @param fn The function to execute that may throw.
+     * @returns A `Result<T, Error>` containing either the successful result or the caught error.
+     * @example
+     * ```typescript
+     * // Wrapping JSON.parse which can throw
+     * const parseJson = <T>(text: string): Result<T, Error> =>
+     *   Result.fromThrowable(() => JSON.parse(text) as T);
+     *
+     * const validJson = parseJson<{valid: boolean}>('{"valid": true}');
+     * if (Result.isOk(validJson)) {
+     *   console.log(validJson.value.valid); // true
+     * }
+     *
+     * const invalidJson = parseJson('{invalid json}');
+     * if (Result.isErr(invalidJson)) {
+     *   console.log(invalidJson.value.message); // SyntaxError message
+     * }
+     *
+     * // Using with custom validation
+     * const parsePositiveNumber = (str: string): Result<number, Error> =>
+     *   Result.fromThrowable(() => {
+     *     const num = Number(str);
+     *     if (Number.isNaN(num)) throw new Error(`Not a number: ${str}`);
+     *     if (num <= 0) throw new Error(`Must be positive: ${num}`);
+     *     return num;
+     *   });
+     *
+     * const success = parsePositiveNumber('42');
+     * console.log(Result.unwrapOkOr(success, 0)); // 42
+     *
+     * const failure = parsePositiveNumber('abc');
+     * console.log(Result.unwrapOkOr(failure, 0)); // 0
+     *
+     * // Wrapping DOM operations that might fail
+     * const getElementText = (id: string): Result<string, Error> =>
+     *   Result.fromThrowable(() => {
+     *     const element = document.getElementById(id);
+     *     if (!element) throw new Error(`Element not found: ${id}`);
+     *     return element.textContent || "";
+     *   });
+     *
+     * // Wrapping file operations
+     * const readFileSync = (path: string): Result<string, Error> =>
+     *   Result.fromThrowable(() =>
+     *     require('fs').readFileSync(path, 'utf8')
+     *   );
+     * ```
+     */
+    export const fromThrowable: <T>(fn: () => T) => Result<T, Error>;
+    /**
+     * Swaps the success and error values of a `Result`.
+     * @template R The input `Result.Base` type.
+     * @param result The `Result` to swap.
+     * @returns A new `Result` with success and error swapped.
+     * @example
+     * ```typescript
+     * const okResult = Result.ok(42);
+     * const swapped = Result.swap(okResult);
+     * console.log(Result.isErr(swapped)); // true
+     * console.log(Result.unwrapErr(swapped)); // 42
+     * ```
+     */
+    export const swap: <R extends Base>(result: R) => Result<UnwrapErr<R>, UnwrapOk<R>>;
+    /**
+     * Converts a `Result` to an `Optional`.
+     *
+     * This conversion is useful when you want to discard error information and only
+     * care about whether an operation succeeded. The error information is lost in
+     * this conversion, so use it when error details are not needed.
+     *
+     * If the `Result` is `Ok`, returns `Some` with the value.
+     * If the `Result` is `Err`, returns `None`.
+     *
+     * @template R The input `Result.Base` type.
+     * @param result The `Result` to convert.
+     * @returns An `Optional<UnwrapOk<R>>` containing the success value or representing `None`.
+     * @example
+     * ```typescript
+     * // Basic conversion
+     * const okResult = Result.ok(42);
+     * const optional = Result.toOptional(okResult);
+     * console.log(Optional.isSome(optional)); // true
+     * console.log(Optional.unwrap(optional)); // 42
+     *
+     * const errResult = Result.err("Network error");
+     * const none = Result.toOptional(errResult);
+     * console.log(Optional.isNone(none)); // true
+     *
+     * // Use case: when you only care about success, not error details
+     * const fetchUserName = (id: number): Result<string, ApiError> => {
+     *   // ... implementation
+     * };
+     *
+     * const maybeUserName = Result.toOptional(fetchUserName(123));
+     * const displayName = Optional.unwrapOr(maybeUserName, "Unknown User");
+     *
+     * // Converting multiple Results and filtering successes
+     * const userIds = [1, 2, 3, 4];
+     * const userNames = userIds
+     *   .map(fetchUserName)
+     *   .map(Result.toOptional)
+     *   .filter(Optional.isSome)
+     *   .map(Optional.unwrap); // string[]
+     *
+     * // Chaining with Optional operations
+     * const processResult = (r: Result<string, Error>) =>
+     *   pipe(Result.toOptional(r))
+     *     .map(Optional.map(s => s.toUpperCase()))
+     *     .map(Optional.filter(s => s.length > 0))
+     *     .value;
+     * ```
+     */
+    export const toOptional: <R extends Base>(result: R) => Optional<UnwrapOk<R>>;
+    /**
+     * Returns the `Result` if it is `Ok`, otherwise returns the alternative.
+     * @template R The input `Result.Base` type.
+     * @param result The `Result` to check.
+     * @param alternative The alternative `Result` to return if the first is `Err`.
+     * @returns The first `Result` if `Ok`, otherwise the alternative.
+     * @example
+     * ```typescript
+     * // Regular usage
+     * const primary = Result.err("error");
+     * const fallback = Result.ok("default");
+     * const result = Result.orElse(primary, fallback);
+     * console.log(Result.unwrapOk(result)); // "default"
+     *
+     * // Curried usage for pipe composition
+     * const fallbackTo = Result.orElse(Result.ok("fallback"));
+     * const result2 = pipe(Result.err("error")).map(fallbackTo).value;
+     * console.log(Result.unwrapOk(result2)); // "fallback"
+     * ```
+     */
+    export const orElse: OrElseFnOverload;
+    type OrElseFnOverload = {
+        <R extends Base, R2 extends Base>(result: R, alternative: R2): NarrowToOk<R> | R2;
+        <S, E, S2, E2>(alternative: Result<S2, E2>): (result: Result<S, E>) => Result<S, E> | Result<S2, E2>;
+    };
+    /**
+     * Combines two `Result` values into a single `Result` containing a tuple.
+     * If either `Result` is `Err`, returns the first `Err` encountered.
+     * @template S1 The success type of the first `Result`.
+     * @template E1 The error type of the first `Result`.
+     * @template S2 The success type of the second `Result`.
+     * @template E2 The error type of the second `Result`.
+     * @param resultA The first `Result`.
+     * @param resultB The second `Result`.
+     * @returns A `Result` containing a tuple of both values, or the first `Err`.
+     * @example
+     * ```typescript
+     * const a = Result.ok(1);
+     * const b = Result.ok("hello");
+     * const zipped = Result.zip(a, b);
+     * console.log(Result.unwrapOk(zipped)); // [1, "hello"]
+     *
+     * const withErr = Result.zip(a, Result.err("error"));
+     * console.log(Result.unwrapErr(withErr)); // "error"
+     * ```
+     */
+    export const zip: <S1, E1, S2, E2>(resultA: Result<S1, E1>, resultB: Result<S2, E2>) => Result<readonly [S1, S2], E1 | E2>;
+    export {};
+}
+export {};
+//# sourceMappingURL=result.d.mts.map