ts-data-forge 1.0.0 → 1.0.1

package/dist/functional/result.mjs

@@ -0,0 +1,844 @@
+import { isRecord } from '../guard/is-record.mjs';
+import { unknownToString } from '../others/unknown-to-string.mjs';
+import { Optional } from './optional.mjs';
+
+/* eslint-disable @typescript-eslint/no-unsafe-type-assertion */
+/** @internal Symbol to identify the 'Ok' variant of Result. */
+const OkTypeSymbol = Symbol('Result.ok');
+/** @internal Symbol to identify the 'Err' variant of Result. */
+const ErrTypeSymbol = Symbol('Result.err');
+/**
+ * Namespace for the `Result` type and related functions.
+ * Provides utilities to handle operations that can succeed or fail.
+ */
+var Result;
+(function (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`.
+     */
+    Result.isResult = (maybeOptional) => isRecord(maybeOptional) &&
+        Object.hasOwn(maybeOptional, 'type') &&
+        Object.hasOwn(maybeOptional, 'value') &&
+        (maybeOptional['type'] === ErrTypeSymbol ||
+            maybeOptional['type'] === OkTypeSymbol);
+    /**
+     * 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
+     * ```
+     */
+    Result.ok = (value) => ({
+        type: OkTypeSymbol,
+        value,
+    });
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    Result.err = (value) => ({
+        type: ErrTypeSymbol,
+        value,
+    });
+    /**
+     * @internal
+     * Default string conversion function using native String constructor.
+     */
+    const toStr_ = String;
+    /**
+     * 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>[]
+     * ```
+     */
+    Result.isOk = (result) => result.type === OkTypeSymbol;
+    /**
+     * 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[]
+     * ```
+     */
+    Result.isErr = (result) => result.type === ErrTypeSymbol;
+    /**
+     * 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
+     * ```
+     */
+    Result.unwrapThrow = (result, toStr = toStr_) => {
+        if (Result.isErr(result)) {
+            throw new Error(toStr(result.value));
+        }
+        return result.value;
+    };
+    /**
+     * 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;
+     * };
+     * ```
+     */
+    Result.unwrapOk = ((result) => Result.isErr(result)
+        ? undefined
+        : result.value);
+    /**
+     * 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
+     * ```
+     */
+    Result.unwrapOkOr = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                // Direct version: first argument is result
+                const [result, defaultValue] = args;
+                return Result.isErr(result) ? defaultValue : result.value;
+            }
+            case 1: {
+                // Curried version: first argument is default value
+                const [defaultValue] = args;
+                return (result) => Result.unwrapOkOr(result, defaultValue);
+            }
+        }
+    });
+    /**
+     * 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");
+     * };
+     * ```
+     */
+    Result.unwrapErrThrow = (result, toStr = toStr_) => {
+        if (Result.isOk(result)) {
+            throw new Error(`Expected Err but got Ok: ${toStr(result.value)}`);
+        }
+        return result.value;
+    };
+    /**
+     * 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
+     * ```
+     */
+    Result.unwrapErr = (result) => Result.isErr(result) ? result.value : 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"
+     * ```
+     */
+    Result.unwrapErrOr = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                // Direct version: first argument is result
+                const [result, defaultValue] = args;
+                return Result.isErr(result) ? result.value : defaultValue;
+            }
+            case 1: {
+                // Curried version: first argument is default value
+                const [defaultValue] = args;
+                return (result) => Result.unwrapErrOr(result, defaultValue);
+            }
+        }
+    });
+    /**
+     * 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
+     * ```
+     */
+    Result.map = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                const [result, mapFn] = args;
+                return Result.isErr(result)
+                    ? result
+                    : Result.ok(mapFn(result.value));
+            }
+            case 1: {
+                // Curried version: first argument is mapping function
+                const [mapFn] = args;
+                return (result) => Result.map(result, mapFn);
+            }
+        }
+    });
+    /**
+     * 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"
+     * ```
+     */
+    Result.mapErr = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                const [result, mapFn] = args;
+                return Result.isOk(result)
+                    ? result
+                    : Result.err(mapFn(result.value));
+            }
+            case 1: {
+                // Curried version: first argument is mapping function
+                const [mapFn] = args;
+                return (result) => Result.mapErr(result, mapFn);
+            }
+        }
+    });
+    /**
+     * 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
+     * ```
+     */
+    Result.fold = ((...args) => {
+        switch (args.length) {
+            case 3: {
+                const [result, mapFn, mapErrFn] = args;
+                return Result.isOk(result)
+                    ? Result.ok(mapFn(result.value))
+                    : Result.err(mapErrFn(result.value));
+            }
+            case 2: {
+                const [mapFn, mapErrFn] = args;
+                return (result) => Result.isOk(result) ? Result.ok(mapFn(result.value)) : Result.err(mapErrFn(result.value));
+            }
+        }
+    });
+    /**
+     * 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
+     * ```
+     */
+    Result.flatMap = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                const [result, flatMapFn] = args;
+                return Result.isErr(result)
+                    ? result
+                    : flatMapFn(result.value);
+            }
+            case 1: {
+                const [flatMapFn] = args;
+                return (result) => Result.isErr(result) ? result : flatMapFn(result.value);
+            }
+        }
+    });
+    /**
+     * 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
+     * ```
+     */
+    Result.expectToBe = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                // Direct version: first argument is result
+                const [result, message] = args;
+                if (Result.isOk(result)) {
+                    return Result.unwrapOk(result);
+                }
+                throw new Error(message);
+            }
+            case 1: {
+                // Curried version: first argument is message
+                const [message] = args;
+                return (result) => Result.expectToBe(result, message);
+            }
+        }
+    });
+    /**
+     * 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>`.
+     */
+    Result.fromPromise = (promise) => promise.then((v) => Result.ok(v)).catch(Result.err);
+    /**
+     * 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')
+     *   );
+     * ```
+     */
+    Result.fromThrowable = (fn) => {
+        try {
+            return Result.ok(fn());
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                return Result.err(error);
+            }
+            const msg = unknownToString(error);
+            if (Result.isErr(msg)) {
+                return Result.err(new Error(String(error)));
+            }
+            else {
+                return Result.err(new Error(msg.value));
+            }
+        }
+    };
+    /**
+     * 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
+     * ```
+     */
+    Result.swap = (result) => Result.isOk(result) ? Result.err(Result.unwrapOk(result)) : Result.ok(result.value);
+    /**
+     * 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;
+     * ```
+     */
+    Result.toOptional = (result) => Result.isOk(result) ? Optional.some(Result.unwrapOk(result)) : Optional.none;
+    /**
+     * 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"
+     * ```
+     */
+    Result.orElse = ((...args) => {
+        switch (args.length) {
+            case 2: {
+                const [result, alternative] = args;
+                return Result.isOk(result) ? result : alternative;
+            }
+            case 1: {
+                // Curried version: one argument (alternative) provided
+                const [alternative] = args;
+                return (result) => Result.orElse(result, alternative);
+            }
+        }
+    });
+    /**
+     * 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"
+     * ```
+     */
+    Result.zip = (resultA, resultB) => Result.isOk(resultA)
+        ? Result.isOk(resultB)
+            ? Result.ok([resultA.value, resultB.value])
+            : resultB
+        : resultA;
+})(Result || (Result = {}));
+
+export { Result };
+//# sourceMappingURL=result.mjs.map