@satoshibits/functional 1.0.2

package/dist/result.mjs

@@ -0,0 +1,814 @@
+"use strict";
+/**
+ * @module result
+ * @description Type-safe error handling without exceptions using the Result pattern.
+ * Result types represent operations that can either succeed with a value or fail
+ * with an error. This provides a functional alternative to try-catch blocks,
+ * making error handling explicit and composable. Similar to Rust's Result type
+ * or fp-ts's Either, but with a simpler API focused on practical use cases.
+ *
+ * @example
+ * ```typescript
+ * import { Result, unwrap, safe } from './result.mts';
+ *
+ * // basic usage
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return Result.err('Division by zero');
+ *   }
+ *   return Result.ok(a / b);
+ * }
+ *
+ * // composing operations
+ * const result = Result.flatMap((x: number) => divide(x, 2))(
+ *   Result.map((x: number) => x * 10)(
+ *     divide(20, 4)
+ *   )
+ * );
+ * // => { success: true, data: 25 }
+ *
+ * // error handling
+ * const safeOperation = Result.orElse(
+ *   (error: string) => Result.ok(0) // default value on error
+ * )(divide(10, 0));
+ * // => { success: true, data: 0 }
+ * ```
+ *
+ * @category Core
+ * @since 2025-07-03
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+/**
+ * Result utility functions for working with Result types.
+ * @description Provides a functional API for creating, transforming, and composing Results.
+ * All functions are curried to support functional composition and partial application.
+ *
+ * @category Utilities
+ * @since 2025-07-03
+ */
+export var Result = {
+    /**
+     * Creates a successful Result containing the given data.
+     * @description Factory function for creating success cases. The error type
+     * can be inferred from context or explicitly specified.
+     *
+     * @template T - The type of the success value
+     * @template E - The type of the error (defaults to never for success cases)
+     * @param {T} data - The success value to wrap
+     * @returns {Result<T, E>} A successful Result containing the data
+     *
+     * @category Constructors
+     * @example
+     * // Basic usage
+     * const result = Result.ok(42);
+     * // => { success: true, data: 42 }
+     *
+     * @example
+     * // With explicit types
+     * const typed: Result<number, string> = Result.ok(42);
+     *
+     * @example
+     * // In a function
+     * function getUser(id: string): Result<User, string> {
+     *   const user = database.find(id);
+     *   return user ? Result.ok(user) : Result.err('User not found');
+     * }
+     *
+     * @since 2025-07-03
+     */
+    ok: function (data) { return ({ success: true, data: data }); },
+    /**
+     * Creates a failed Result containing the given error.
+     * @description Factory function for creating failure cases. The success type
+     * can be inferred from context or explicitly specified.
+     *
+     * @template T - The type of the success value (defaults to never for error cases)
+     * @template E - The type of the error (defaults to string)
+     * @param {E} error - The error value to wrap
+     * @returns {Result<T, E>} A failed Result containing the error
+     *
+     * @category Constructors
+     * @example
+     * // Basic usage
+     * const result = Result.err('Something went wrong');
+     * // => { success: false, error: 'Something went wrong' }
+     *
+     * @example
+     * // With custom error type
+     * interface ValidationError {
+     *   field: string;
+     *   message: string;
+     * }
+     *
+     * const error: Result<number, ValidationError> = Result.err({
+     *   field: 'age',
+     *   message: 'Must be positive'
+     * });
+     *
+     * @since 2025-07-03
+     */
+    err: function (error) { return ({
+        success: false,
+        error: error,
+    }); },
+    /**
+     * Transforms the data inside a successful Result using the given function.
+     * @description If the Result is a failure, returns the failure unchanged.
+     * This is the functor map operation for Result types.
+     *
+     * @template T - The input success type
+     * @template U - The output success type
+     * @template E - The error type
+     * @param {function(T): U} f - Function to transform the success value
+     * @returns {function(Result<T, E>): Result<U, E>} A function that transforms Results
+     *
+     * @category Transformations
+     * @example
+     * // Basic transformation
+     * const double = Result.map((x: number) => x * 2);
+     * double(Result.ok(21)); // => { success: true, data: 42 }
+     * double(Result.err('error')); // => { success: false, error: 'error' }
+     *
+     * @example
+     * // Chaining transformations
+     * const result = Result.map((s: string) => s.toUpperCase())(
+     *   Result.map((n: number) => n.toString())(
+     *     Result.ok(42)
+     *   )
+     * );
+     * // => { success: true, data: '42' }
+     *
+     * @since 2025-07-03
+     */
+    map: function (f) {
+        return function (result) {
+            return result.success ? Result.ok(f(result.data)) : result;
+        };
+    },
+    /**
+     * Chains Result-returning operations.
+     * @description If the first Result is successful, applies the function to its data.
+     * If it's a failure, returns the failure. This is the monadic bind operation
+     * for Result types, enabling sequential composition of fallible operations.
+     *
+     * @template T - The input success type
+     * @template U - The output success type
+     * @template E - The error type
+     * @param {function(T): Result<U, E>} f - Function that returns a new Result
+     * @returns {function(Result<T, E>): Result<U, E>} A function that chains Results
+     *
+     * @category Combinators
+     * @example
+     * // Chaining fallible operations
+     * function parseNumber(s: string): Result<number, string> {
+     *   const n = Number(s);
+     *   return isNaN(n) ? Result.err('Not a number') : Result.ok(n);
+     * }
+     *
+     * function safeDivide(n: number): Result<number, string> {
+     *   return n === 0 ? Result.err('Division by zero') : Result.ok(100 / n);
+     * }
+     *
+     * const result = Result.flatMap(safeDivide)(
+     *   parseNumber('5')
+     * );
+     * // => { success: true, data: 20 }
+     *
+     * @since 2025-07-03
+     */
+    flatMap: function (f) {
+        return function (result) {
+            return result.success ? f(result.data) : result;
+        };
+    },
+    /**
+     * Transforms the error inside a failed Result using the given function.
+     * @description If the Result is successful, returns the success unchanged.
+     * Useful for normalizing errors or adding context to error messages.
+     *
+     * @template T - The success type
+     * @template E - The input error type
+     * @template F - The output error type
+     * @param {function(E): F} f - Function to transform the error
+     * @returns {function(Result<T, E>): Result<T, F>} A function that transforms error types
+     *
+     * @category Transformations
+     * @example
+     * // Adding context to errors
+     * const withContext = Result.mapError(
+     *   (e: string) => `Database error: ${e}`
+     * );
+     *
+     * @example
+     * // Converting error types
+     * interface AppError {
+     *   code: string;
+     *   message: string;
+     * }
+     *
+     * const toAppError = Result.mapError(
+     *   (e: Error): AppError => ({
+     *     code: 'INTERNAL_ERROR',
+     *     message: e.message
+     *   })
+     * );
+     *
+     * @since 2025-07-03
+     */
+    mapError: function (f) {
+        return function (result) {
+            return result.success ? result : Result.err(f(result.error));
+        };
+    },
+    /**
+     * Returns the data from a successful Result, or the provided default value if failed.
+     * @description Extracts the value from a Result, providing a fallback for the error case.
+     * Useful when you want to handle errors by substituting a default value.
+     *
+     * @template T - The success type
+     * @template E - The error type
+     * @param {T} defaultValue - The value to return if the Result is an error
+     * @returns {function(Result<T, E>): T} A function that extracts values with a default
+     *
+     * @category Extraction
+     * @example
+     * // Providing defaults
+     * const getWithDefault = Result.getOrElse(0);
+     * getWithDefault(Result.ok(42)); // => 42
+     * getWithDefault(Result.err('error')); // => 0
+     *
+     * @example
+     * // Configuration with fallback
+     * const port = Result.getOrElse(3000)(
+     *   parsePort(process.env.PORT)
+     * );
+     *
+     * @since 2025-07-03
+     */
+    getOrElse: function (defaultValue) {
+        return function (result) {
+            return result.success ? result.data : defaultValue;
+        };
+    },
+    /**
+     * Returns the data from a successful Result, or calls the provided function with the error.
+     * @description Pattern matches on the Result, applying one of two functions based on
+     * success or failure. Both functions must return the same type. This is similar
+     * to the fold operation in functional programming.
+     *
+     * @template T - The success type
+     * @template U - The return type
+     * @template E - The error type
+     * @param {function(T): U} onSuccess - Function to apply to success value
+     * @param {function(E): U} onFailure - Function to apply to error value
+     * @returns {function(Result<T, E>): U} A function that folds Results into a value
+     *
+     * @category Extraction
+     * @example
+     * // Converting to a message
+     * const toMessage = Result.fold(
+     *   (user: User) => `Welcome, ${user.name}!`,
+     *   (error: string) => `Error: ${error}`
+     * );
+     *
+     * @example
+     * // Converting to React component
+     * const renderResult = Result.fold(
+     *   (data: Data) => <SuccessView data={data} />,
+     *   (error: Error) => <ErrorView error={error} />
+     * );
+     *
+     * @since 2025-07-03
+     */
+    fold: function (onSuccess, onFailure) {
+        return function (result) {
+            return result.success ? onSuccess(result.data) : onFailure(result.error);
+        };
+    },
+    /**
+     * Combines two Results. If both are successful, applies the function to both data values.
+     * @description If either is a failure, returns the first failure encountered.
+     * This implements applicative-style composition for Result types.
+     *
+     * @template T - The first success type
+     * @template U - The second success type
+     * @template V - The combined success type
+     * @template E - The error type
+     * @param {function(T, U): V} f - Function to combine the success values
+     * @returns {function(Result<T, E>, Result<U, E>): Result<V, E>} A function that combines Results
+     *
+     * @category Combinations
+     * @example
+     * // Combining two results
+     * const add = Result.combine((a: number, b: number) => a + b);
+     * add(Result.ok(2), Result.ok(3)); // => { success: true, data: 5 }
+     * add(Result.ok(2), Result.err('error')); // => { success: false, error: 'error' }
+     *
+     * @example
+     * // Building objects from multiple Results
+     * const createUser = Result.combine(
+     *   (name: string, age: number): User => ({ name, age })
+     * );
+     *
+     * const user = createUser(
+     *   validateName(input.name),
+     *   validateAge(input.age)
+     * );
+     *
+     * @since 2025-07-03
+     */
+    combine: function (f) {
+        return function (resultA, resultB) {
+            if (!resultA.success) {
+                return Result.err(resultA.error);
+            }
+            if (!resultB.success) {
+                return Result.err(resultB.error);
+            }
+            return Result.ok(f(resultA.data, resultB.data));
+        };
+    },
+    /**
+     * Sequences an array of Results.
+     * @description If all are successful, returns an array of all data values.
+     * If any are failures, returns the first failure encountered. This is
+     * useful for validating multiple values where all must succeed.
+     *
+     * @template T - The success type of each Result
+     * @template E - The error type
+     * @param {Result<T, E>[]} results - Array of Results to sequence
+     * @returns {Result<T[], E>} A Result containing an array of values or the first error
+     *
+     * @category Combinations
+     * @example
+     * // Validating multiple inputs
+     * const results = [
+     *   validateEmail('user@example.com'),
+     *   validateEmail('admin@example.com'),
+     *   validateEmail('test@example.com')
+     * ];
+     *
+     * const allEmails = Result.sequence(results);
+     * // If all valid: { success: true, data: ['user@...', 'admin@...', 'test@...'] }
+     * // If any invalid: { success: false, error: 'Invalid email format' }
+     *
+     * @see combineWithAllErrors - Collects all errors instead of short-circuiting
+     * @since 2025-07-03
+     */
+    sequence: function (results) {
+        var data = [];
+        for (var _i = 0, results_1 = results; _i < results_1.length; _i++) {
+            var result = results_1[_i];
+            if (!result.success) {
+                return result;
+            }
+            data.push(result.data);
+        }
+        return Result.ok(data);
+    },
+    /**
+     * Filters a successful Result based on a predicate.
+     * @description If the predicate fails, returns a failure with the provided error.
+     * If the Result is already a failure, returns it unchanged. This allows
+     * adding validation to existing Results.
+     *
+     * @template T - The success type
+     * @template E - The error type
+     * @param {function(T): boolean} predicate - Function to test the success value
+     * @param {E} error - Error to return if the predicate fails
+     * @returns {function(Result<T, E>): Result<T, E>} A function that filters Results
+     *
+     * @category Validations
+     * @example
+     * // Adding validation
+     * const mustBePositive = Result.filter(
+     *   (n: number) => n > 0,
+     *   'Number must be positive'
+     * );
+     *
+     * mustBePositive(Result.ok(42)); // => { success: true, data: 42 }
+     * mustBePositive(Result.ok(-1)); // => { success: false, error: 'Number must be positive' }
+     *
+     * @example
+     * // Chaining validations
+     * const validateAge = (age: number) => Result.ok(age)
+     *   |> Result.filter(n => n >= 0, 'Age cannot be negative')
+     *   |> Result.filter(n => n <= 150, 'Age seems unrealistic');
+     *
+     * @since 2025-07-03
+     */
+    filter: function (predicate, error) {
+        return function (result) {
+            return !result.success ? result : predicate(result.data) ? result : Result.err(error);
+        };
+    },
+    /**
+     * Provides a fallback Result if the original fails.
+     * @description The fallback function receives the error and returns a new Result.
+     * This allows error recovery and chaining of alternative operations.
+     *
+     * @template T - The success type
+     * @template E - The input error type
+     * @template F - The output error type
+     * @param {function(E): Result<T, F>} fallbackFn - Function to create a fallback Result
+     * @returns {function(Result<T, E>): Result<T, F>} A function that adds fallback logic
+     *
+     * @category Error Handling
+     * @example
+     * // Fallback to cache
+     * const getUser = Result.orElse(
+     *   (error: string) => getCachedUser()
+     * )(fetchUserFromAPI());
+     *
+     * @example
+     * // Try multiple sources
+     * const config = Result.orElse(
+     *   () => loadFromFile('./config.json')
+     * )(Result.orElse(
+     *   () => loadFromEnv()
+     * )(loadFromDatabase()));
+     *
+     * @since 2025-07-03
+     */
+    orElse: function (fallbackFn) {
+        return function (result) {
+            return result.success ? result : fallbackFn(result.error);
+        };
+    },
+    /**
+     * Combines an array of Results, collecting ALL errors instead of short-circuiting.
+     * @description If all succeed, returns an array of values. If any fail, returns
+     * an array of all errors. This is useful for validation scenarios where you
+     * want to report all errors at once rather than stopping at the first one.
+     *
+     * @template T - The success type of each Result
+     * @template E - The error type of each Result
+     * @param {Result<T, E>[]} results - Array of Results to combine
+     * @returns {Result<T[], E[]>} Success with all values or failure with all errors
+     *
+     * @category Combinations
+     * @example
+     * // Form validation with all errors
+     * const validations = [
+     *   validateName(form.name),
+     *   validateEmail(form.email),
+     *   validateAge(form.age)
+     * ];
+     *
+     * const result = Result.combineWithAllErrors(validations);
+     * // If any fail: { success: false, error: ['Invalid name', 'Invalid email'] }
+     * // If all succeed: { success: true, data: ['John', 'john@example.com', 25] }
+     *
+     * @see sequence - Short-circuits on first error
+     * @since 2025-07-03
+     */
+    combineWithAllErrors: function (results) {
+        var successes = [];
+        var errors = [];
+        for (var _i = 0, results_2 = results; _i < results_2.length; _i++) {
+            var result = results_2[_i];
+            if (result.success) {
+                successes.push(result.data);
+            }
+            else {
+                errors.push(result.error);
+            }
+        }
+        return errors.length > 0 ? Result.err(errors) : Result.ok(successes);
+    },
+    /**
+     * Checks if a Result is successful.
+     * @description Type guard that narrows a Result to its success case.
+     * Useful in conditional statements and array filtering.
+     *
+     * @template T - The success type
+     * @template E - The error type
+     * @param {Result<T, E>} result - The Result to check
+     * @returns {result is { success: true; data: T }} True if the Result is successful
+     *
+     * @category Type Guards
+     * @example
+     * // Type narrowing
+     * const result = divide(10, 2);
+     * if (Result.isOk(result)) {
+     *   console.log(result.data); // TypeScript knows data exists
+     * }
+     *
+     * @example
+     * // Filtering arrays
+     * const results = [Result.ok(1), Result.err('error'), Result.ok(2)];
+     * const successes = results.filter(Result.isOk);
+     * // => [{ success: true, data: 1 }, { success: true, data: 2 }]
+     *
+     * @see isErr - Check if Result is a failure
+     * @since 2025-07-03
+     */
+    isOk: function (result) {
+        return result.success;
+    },
+    /**
+     * Checks if a Result is a failure.
+     * @description Type guard that narrows a Result to its failure case.
+     * Useful in conditional statements and error handling.
+     *
+     * @template T - The success type
+     * @template E - The error type
+     * @param {Result<T, E>} result - The Result to check
+     * @returns {result is { success: false; error: E }} True if the Result is a failure
+     *
+     * @category Type Guards
+     * @example
+     * // Error handling
+     * const result = parseJSON(input);
+     * if (Result.isErr(result)) {
+     *   logger.error(result.error); // TypeScript knows error exists
+     * }
+     *
+     * @example
+     * // Collecting errors
+     * const results = processItems(items);
+     * const errors = results.filter(Result.isErr).map(r => r.error);
+     *
+     * @see isOk - Check if Result is successful
+     * @since 2025-07-03
+     */
+    isErr: function (result) {
+        return !result.success;
+    },
+    /**
+     * Converts a promise that might throw into a Result.
+     * @description Catches exceptions and converts them to error Results.
+     * This bridges the gap between exception-based and Result-based error handling.
+     *
+     * @template T - The type of the resolved value
+     * @param {Promise<T>} promise - The promise that might reject
+     * @returns {Promise<Result<T, Error>>} A promise of a Result
+     *
+     * @category Interop
+     * @example
+     * // Converting async operations
+     * const result = await Result.fromPromise(
+     *   fetch('/api/user').then(r => r.json())
+     * );
+     *
+     * if (Result.isOk(result)) {
+     *   console.log('User:', result.data);
+     * } else {
+     *   console.error('Failed:', result.error.message);
+     * }
+     *
+     * @example
+     * // With async/await
+     * async function safeReadFile(path: string): Promise<Result<string, Error>> {
+     *   return Result.fromPromise(
+     *     fs.promises.readFile(path, 'utf-8')
+     *   );
+     * }
+     *
+     * @since 2025-07-03
+     */
+    fromPromise: function (promise) { return __awaiter(void 0, void 0, void 0, function () {
+        var data, error_1;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    _a.trys.push([0, 2, , 3]);
+                    return [4 /*yield*/, promise];
+                case 1:
+                    data = _a.sent();
+                    return [2 /*return*/, Result.ok(data)];
+                case 2:
+                    error_1 = _a.sent();
+                    return [2 /*return*/, Result.err(error_1 instanceof Error ? error_1 : new Error(String(error_1)))];
+                case 3: return [2 /*return*/];
+            }
+        });
+    }); },
+    /**
+     * Converts a function that might throw into a Result-returning function.
+     * @description Wraps a function to catch any thrown exceptions and convert
+     * them to Result errors. This allows using exception-based APIs in a
+     * Result-based codebase.
+     *
+     * @template T - The tuple type of function arguments
+     * @template U - The return type of the function
+     * @param {function(...T): U} fn - Function that might throw
+     * @returns {function(...T): Result<U, Error>} A safe version that returns Results
+     *
+     * @category Interop
+     * @example
+     * // Wrapping JSON.parse
+     * const safeParseJSON = Result.fromThrowable(JSON.parse);
+     *
+     * const result = safeParseJSON('{"name": "John"}');
+     * // => { success: true, data: { name: 'John' } }
+     *
+     * const invalid = safeParseJSON('invalid json');
+     * // => { success: false, error: Error(...) }
+     *
+     * @example
+     * // Wrapping custom functions
+     * function riskyOperation(x: number): number {
+     *   if (x < 0) throw new Error('Cannot process negative numbers');
+     *   return Math.sqrt(x);
+     * }
+     *
+     * const safeSqrt = Result.fromThrowable(riskyOperation);
+     *
+     * @since 2025-07-03
+     */
+    fromThrowable: function (fn) {
+        return function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            try {
+                var result = fn.apply(void 0, args);
+                return Result.ok(result);
+            }
+            catch (error) {
+                return Result.err(error instanceof Error ? error : new Error(String(error)));
+            }
+        };
+    },
+};
+/**
+ * Utility type guard for checking if a value is a Result.
+ * @description Runtime type guard that checks if an unknown value conforms to
+ * the Result type structure. Useful for validation and type narrowing at
+ * runtime boundaries.
+ *
+ * @template T - The expected success type
+ * @template E - The expected error type
+ * @param {any} value - The value to check
+ * @returns {value is Result<T, E>} True if the value is a valid Result
+ *
+ * @category Type Guards
+ * @example
+ * // API response validation
+ * function handleResponse(data: unknown): void {
+ *   if (isResult(data)) {
+ *     if (data.success) {
+ *       console.log('Success:', data.data);
+ *     } else {
+ *       console.error('Error:', data.error);
+ *     }
+ *   } else {
+ *     console.error('Invalid response format');
+ *   }
+ * }
+ *
+ * @example
+ * // Type narrowing in mixed arrays
+ * const mixed = [Result.ok(1), 'not a result', Result.err('error')];
+ * const results = mixed.filter(isResult);
+ * // TypeScript knows results contains only Result types
+ *
+ * @since 2025-07-03
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export var isResult = function (value) {
+    if (typeof value !== "object" || value === null || !("success" in value)) {
+        return false;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (value.success === true) {
+        return "data" in value;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    if (value.success === false) {
+        return "error" in value;
+    }
+    return false;
+};
+/**
+ * Helper function to unwrap a Result, throwing if it's an error.
+ * @description Use sparingly, only when you're certain the Result should be successful.
+ * This function bridges Result-based code with exception-based code, but defeats
+ * the purpose of using Results for explicit error handling.
+ *
+ * @template T - The success type
+ * @template E - The error type
+ * @param {Result<T, E>} result - The Result to unwrap
+ * @returns {T} The success value
+ * @throws {Error} If the Result is a failure
+ *
+ * @category Extraction
+ * @example
+ * // In tests where you expect success
+ * test('calculation succeeds', () => {
+ *   const result = calculate(10, 2);
+ *   expect(unwrap(result)).toBe(5);
+ * });
+ *
+ * @example
+ * // At system boundaries where errors are exceptional
+ * const config = unwrap(loadConfig());
+ * // If this fails, the app cannot start anyway
+ *
+ * @warning Avoid using unwrap in normal application flow.
+ * Prefer Result.fold, Result.getOrElse, or pattern matching.
+ *
+ * @since 2025-07-03
+ */
+export var unwrap = function (result) {
+    if (result.success) {
+        return result.data;
+    }
+    var errorMessage = result.error instanceof Error
+        ? result.error.message
+        : String(result.error);
+    throw new Error("Attempted to unwrap failed Result: ".concat(errorMessage));
+};
+/**
+ * Helper function to safely access nested properties that might not exist.
+ * @description Returns a Result instead of throwing or returning undefined.
+ * This provides a safe way to access deeply nested properties without
+ * optional chaining or null checks.
+ *
+ * @template T - The type of the object
+ * @template U - The type of the extracted value
+ * @param {function(T): U} getter - Function that extracts a value from the object
+ * @param {string} errorMessage - Error message if extraction fails
+ * @returns {function(T): Result<U, string>} A function that safely extracts values
+ *
+ * @category Utilities
+ * @example
+ * // Safe property access
+ * interface User {
+ *   profile?: {
+ *     address?: {
+ *       city?: string;
+ *     };
+ *   };
+ * }
+ *
+ * const getCity = safe((user: User) => user.profile!.address!.city!);
+ *
+ * const result = getCity({ profile: { address: { city: 'NYC' } } });
+ * // => { success: true, data: 'NYC' }
+ *
+ * const missing = getCity({});
+ * // => { success: false, error: 'Property access failed' }
+ *
+ * @example
+ * // Custom error messages
+ * const getName = safe(
+ *   (data: any) => data.user.name as string,
+ *   'User name not found'
+ * );
+ *
+ * @since 2025-07-03
+ */
+export var safe = function (getter, errorMessage) {
+    if (errorMessage === void 0) { errorMessage = "Property access failed"; }
+    return function (obj) {
+        try {
+            var value = getter(obj);
+            if (value === undefined || value === null) {
+                return Result.err(errorMessage);
+            }
+            return Result.ok(value);
+        }
+        catch (_a) {
+            return Result.err(errorMessage);
+        }
+    };
+};
+//# sourceMappingURL=result.mjs.map