@pencroff-lab/kore 0.1.0

package/dist/cjs/src/types/outcome.js

@@ -0,0 +1,958 @@
+"use strict";
+/**
+ * @fileoverview
+ * Monadic container for handling success and error states using tuple-first API design.
+ *
+ * This module provides the `Outcome<T>` class and related types for implementing
+ * type-safe error handling without exceptions. All operations favor immutability.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Outcome } from './outcome';
+ *
+ * const [val, err] = Outcome.from(() => [42, null]).toTuple();
+ * ```
+ *
+ * @example Migration from throwing functions
+ * ```typescript
+ * // Before (throwing):
+ * function getUser(id: string): User {
+ *   const user = db.find(id);
+ *   if (!user) throw new Error("Not found");
+ *   return user;
+ * }
+ * try {
+ *   const user = getUser("123");
+ *   console.log(user.name);
+ * } catch (e) {
+ *   console.error(e.message);
+ * }
+ *
+ * // After (Outcome):
+ * function getUser(id: string): Outcome<User> {
+ *   return Outcome.from(() => {
+ *     const user = db.find(id);
+ *     if (!user) return Err.from("Not found", "NOT_FOUND");
+ *     return [user, null];
+ *   });
+ * }
+ * const [user, err] = getUser("123").toTuple();
+ * if (err) {
+ *   console.error(err.message);
+ *   return;
+ * }
+ * console.log(user.name);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Outcome = void 0;
+const err_1 = require("./err");
+/**
+ * A monadic container for handling success and error states.
+ *
+ * `Outcome<T>` provides a type-safe way to handle operations that can fail,
+ * using tuples as the primary interface. All instances are immutable.
+ *
+ * ## Core Patterns
+ *
+ * - **Construction**: Use static methods `ok()`, `err()`, `from()`, `fromAsync()`
+ * - **Inspection**: Use `isOk`, `isErr`, `value`, `error` properties
+ * - **Transformation**: Use `map()`, `mapErr()` for chained operations
+ * - **Extraction**: Use `toTuple()` for final value extraction
+ *
+ * @example Basic usage
+ * ```typescript
+ * const outcome = Outcome.from(() => {
+ *   if (Math.random() > 0.5) return [42, null];
+ *   return Err.from('Bad luck');
+ * });
+ *
+ * const [value, err] = outcome.toTuple();
+ * if (err) {
+ *   console.error('Failed:', err.message);
+ * } else {
+ *   console.log('Success:', value);
+ * }
+ * ```
+ *
+ * @example Chaining transformations
+ * ```typescript
+ * const result = Outcome.ok(5)
+ *   .map(n => [n * 2, null])
+ *   .map(n => [n.toString(), null])
+ *   .toTuple();
+ * // result: ['10', null]
+ * ```
+ *
+ * @typeParam T - The type of the success value
+ */
+class Outcome {
+    /**
+     * Discriminator property for type narrowing.
+     * `true` for success outcomes, `false` for error outcomes.
+     */
+    isOk;
+    /** Internal tuple storage */
+    _tuple;
+    /**
+     * Private constructor - use static factory methods.
+     * @internal
+     */
+    constructor(tuple) {
+        this._tuple = tuple;
+        this.isOk = tuple[1] === null;
+    }
+    /**
+     * Process a CallbackReturn value into an Outcome.
+     * Handles discrimination: Err → null (void) → tuple destructure.
+     * @internal
+     */
+    static _processCallbackReturn(result) {
+        // Case 1: Direct Err return (shorthand)
+        if (err_1.Err.isErr(result)) {
+            return new Outcome([null, result]);
+        }
+        // Case 2: null = void success
+        if (result === null) {
+            return new Outcome([null, null]);
+        }
+        // Case 3: Tuple [T, null] | [null, Err]
+        const [value, error] = result;
+        if (err_1.Err.isErr(error)) {
+            return new Outcome([null, error]);
+        }
+        return new Outcome([value, null]);
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Static Constructors
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Create a success Outcome with the given value.
+     *
+     * @param value - The success value
+     * @returns Outcome containing the success value
+     *
+     * @example
+     * ```typescript
+     * const outcome = Outcome.ok(42);
+     * console.log(outcome.isOk);  // true
+     * console.log(outcome.value); // 42
+     *
+     * const [val, err] = outcome.toTuple();
+     * // val: 42, err: null
+     * ```
+     */
+    static ok(value) {
+        return new Outcome([value, null]);
+    }
+    /**
+     * Implementation signature for err().
+     * @internal
+     */
+    static err(messageOrErr, codeOrOptionsOrErr, options) {
+        // If first arg is already an Err, use it directly
+        if (err_1.Err.isErr(messageOrErr)) {
+            return new Outcome([null, messageOrErr]);
+        }
+        const message = messageOrErr;
+        // If second arg is Err or Error, wrap it
+        if (err_1.Err.isErr(codeOrOptionsOrErr) || codeOrOptionsOrErr instanceof Error) {
+            const wrapped = err_1.Err.wrap(message, codeOrOptionsOrErr, options);
+            return new Outcome([null, wrapped]);
+        }
+        // Otherwise, create new Err with message and options/code
+        // biome-ignore lint/suspicious/noExplicitAny: overloaded argument handling
+        const err = err_1.Err.from(message, codeOrOptionsOrErr);
+        return new Outcome([null, err]);
+    }
+    /**
+     * Create a success Outcome with null value (void success).
+     *
+     * Use for operations that succeed but have no meaningful return value.
+     *
+     * @returns Outcome<null> representing void success
+     *
+     * @remarks
+     * Returns `Outcome<null>` (not `Outcome<undefined>` or `Outcome<void>`).
+     * This is intentional for consistency with the tuple pattern where `null`
+     * indicates absence of error in `[value, null]`.
+     *
+     * @example
+     * ```typescript
+     * function logMessage(msg: string): Outcome<null> {
+     *   console.log(msg);
+     *   return Outcome.unit();
+     * }
+     *
+     * const outcome = logMessage('Hello');
+     * console.log(outcome.isOk); // true
+     * console.log(outcome.value); // null
+     * ```
+     */
+    static unit() {
+        return new Outcome([null, null]);
+    }
+    /**
+     * Create an Outcome from a callback that returns `CallbackReturn<T>`.
+     *
+     * The callback can return:
+     * - `[value, null]` - success with value
+     * - `[null, Err]` - error as tuple
+     * - `null` - void success
+     * - `Err` - error directly
+     *
+     * If the callback throws, the exception is caught and wrapped in an error Outcome.
+     *
+     * @param fn - Callback returning CallbackReturn<T>
+     * @returns Outcome<T>
+     *
+     * @see {@link fromAsync} for the async version
+     *
+     * @example Success with value
+     * ```typescript
+     * const outcome = Outcome.from(() => {
+     *   return [42, null];
+     * });
+     * console.log(outcome.value); // 42
+     * ```
+     *
+     * @example Error shorthand
+     * ```typescript
+     * const outcome = Outcome.from(() => {
+     *   if (invalid) return Err.from('Invalid input');
+     *   return [result, null];
+     * });
+     * ```
+     *
+     * @example Catching throws from external libraries
+     * ```typescript
+     * const outcome = Outcome.from(() => {
+     *   const data = JSON.parse(untrustedInput); // may throw
+     *   return [data, null];
+     * });
+     * // If JSON.parse throws, outcome.isErr === true
+     * ```
+     */
+    static from(fn) {
+        try {
+            const result = fn();
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Create an Outcome from an async callback that returns `Promise<CallbackReturn<T>>`.
+     *
+     * Async version of `from()` with identical semantics.
+     *
+     * @param fn - Async callback returning Promise<CallbackReturn<T>>
+     * @returns Promise<Outcome<T>>
+     *
+     * @see {@link from} for the synchronous version
+     *
+     * @example Async operation
+     * ```typescript
+     * const outcome = await Outcome.fromAsync(async () => {
+     *   const response = await fetch('/api/data');
+     *   if (!response.ok) {
+     *     return Err.from('Request failed', { code: 'HTTP_ERROR' });
+     *   }
+     *   const data = await response.json();
+     *   return [data, null];
+     * });
+     * ```
+     *
+     * @example With error aggregation
+     * ```typescript
+     * const outcome = await Outcome.fromAsync(async () => {
+     *   let errors = Err.aggregate('Batch failed');
+     *
+     *   const [a, errA] = await taskA().toTuple();
+     *   if (errA) errors = errors.add(errA);
+     *
+     *   const [b, errB] = await taskB().toTuple();
+     *   if (errB) errors = errors.add(errB);
+     *
+     *   if (errors.count > 0) return errors;
+     *   return [{ a, b }, null];
+     * });
+     * ```
+     */
+    static async fromAsync(fn) {
+        try {
+            const result = await fn();
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Create an Outcome from an existing ResultTuple.
+     *
+     * Useful for deserializing Outcomes or converting from external tuple sources.
+     *
+     * @param tuple - A ResultTuple<T>
+     * @returns Outcome<T>
+     *
+     * @see {@link toTuple} for extracting the tuple from an Outcome
+     *
+     * @example Deserializing from JSON
+     * ```typescript
+     * const json = '["hello", null]';
+     * const tuple = JSON.parse(json) as ResultTuple<string>;
+     * const outcome = Outcome.fromTuple(tuple);
+     * console.log(outcome.value); // 'hello'
+     * ```
+     *
+     * @example Round-trip serialization
+     * ```typescript
+     * const original = Outcome.ok(42);
+     * const json = JSON.stringify(original.toJSON());
+     * const restored = Outcome.fromTuple(JSON.parse(json));
+     * console.log(restored.value); // 42
+     * ```
+     */
+    static fromTuple(tuple) {
+        return new Outcome(tuple);
+    }
+    static fromJSON(payload) {
+        return Outcome.from(() => {
+            if (!Array.isArray(payload) || payload.length !== 2) {
+                return err_1.Err.from("Invalid Outcome JSON");
+            }
+            const [value, error] = payload;
+            if (error === null) {
+                return [value, null];
+            }
+            return [null, err_1.Err.fromJSON(error)];
+        });
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Combinators
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Combines multiple Outcomes, succeeding if all succeed with an array of values.
+     * If any Outcome fails, returns an Err containing all failures aggregated via Err.aggregate().
+     *
+     * This is useful for validation scenarios where you need to collect all errors.
+     *
+     * For empty arrays, returns `Outcome.ok([])` (vacuous truth).
+     *
+     * @param outcomes - Array of Outcomes to combine
+     * @returns Outcome containing array of all success values, or aggregate error
+     *
+     * @remarks
+     * Time complexity: O(n) where n is the number of outcomes.
+     * All outcomes are evaluated (non-short-circuiting) to collect all errors.
+     *
+     * @example All succeed
+     * ```typescript
+     * const outcomes = [Outcome.ok(1), Outcome.ok(2), Outcome.ok(3)];
+     * const combined = Outcome.all(outcomes);
+     * console.log(combined.value); // [1, 2, 3]
+     * ```
+     *
+     * @example One fails
+     * ```typescript
+     * const outcomes = [
+     *   Outcome.ok(1),
+     *   Outcome.err('Failed'),
+     *   Outcome.ok(3)
+     * ];
+     * const combined = Outcome.all(outcomes);
+     * console.log(combined.isErr); // true
+     * console.log(combined.error?.message); // 'Failed'
+     * ```
+     *
+     * @example Many fails
+     * ```typescript
+     * const mixed = [
+     *   Outcome.ok(1),
+     *   Outcome.err("Error A"),
+     *   Outcome.err("Error B")
+     * ];
+     * const failed = Outcome.all(mixed);
+     * console.log(failed.isErr);  // true
+     * // Error contains both "Error A" and "Error B"
+     * ```
+     *
+     * @example Empty array
+     * ```typescript
+     * const combined = Outcome.all([]);
+     * console.log(combined.value); // []
+     * ```
+     */
+    static all(outcomes) {
+        const values = [];
+        const errors = [];
+        for (const outcome of outcomes) {
+            if (outcome.isErr) {
+                //
+                errors.push(outcome._tuple[1]);
+                continue;
+            }
+            values.push(outcome._tuple[0]);
+        }
+        if (errors.length === 1) {
+            return new Outcome([null, errors[0]]);
+        }
+        if (errors.length > 0) {
+            return Outcome.err(err_1.Err.aggregate("Multiple failed", errors));
+        }
+        return new Outcome([values, null]);
+    }
+    /**
+     * Return the first successful Outcome from an array.
+     *
+     * Returns the first success encountered.
+     * Returns an aggregate error if ALL outcomes fail.
+     *
+     * For empty arrays, returns an error (no value to return).
+     *
+     * @param outcomes - Array of Outcomes to check
+     * @returns First successful Outcome, or aggregate of all errors
+     *
+     * @remarks
+     * Time complexity: O(n) worst case, but short-circuits on first success.
+     * Best case: O(1) if first outcome is successful.
+     *
+     * @example First success wins
+     * ```typescript
+     * const outcomes = [
+     *   Outcome.err('First failed'),
+     *   Outcome.ok(42),
+     *   Outcome.ok(100)
+     * ];
+     * const result = Outcome.any(outcomes);
+     * console.log(result.value); // 42
+     * ```
+     *
+     * @example All fail
+     * ```typescript
+     * const outcomes = [
+     *   Outcome.err('Error 1'),
+     *   Outcome.err('Error 2')
+     * ];
+     * const result = Outcome.any(outcomes);
+     * console.log(result.isErr); // true
+     * console.log(result.error?.isAggregate); // true
+     * ```
+     *
+     * @example Empty array
+     * ```typescript
+     * const result = Outcome.any([]);
+     * console.log(result.isErr); // true
+     * console.log(result.error?.message); // 'No outcomes provided'
+     * ```
+     */
+    static any(outcomes) {
+        if (outcomes.length === 0) {
+            return Outcome.err("No outcomes provided", "EMPTY_INPUT");
+        }
+        const errors = [];
+        for (const outcome of outcomes) {
+            if (outcome.isOk) {
+                return outcome;
+            }
+            errors.push(outcome._tuple[1]);
+        }
+        const aggregate = err_1.Err.aggregate("All failed", errors);
+        return new Outcome([null, aggregate]);
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Instance Accessors
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Whether this Outcome is in error state.
+     *
+     * @example
+     * ```typescript
+     * const success = Outcome.ok(42);
+     * const failure = Outcome.err('Failed');
+     *
+     * console.log(success.isErr); // false
+     * console.log(failure.isErr); // true
+     * ```
+     */
+    get isErr() {
+        return !this.isOk;
+    }
+    /**
+     * The success value, or null if in error state.
+     *
+     * @example
+     * ```typescript
+     * const success = Outcome.ok(42);
+     * const failure = Outcome.err('Failed');
+     *
+     * console.log(success.value); // 42
+     * console.log(failure.value); // null
+     * ```
+     */
+    get value() {
+        return this._tuple[0];
+    }
+    /**
+     * The error, or null if in success state.
+     *
+     * @example
+     * ```typescript
+     * const success = Outcome.ok(42);
+     * const failure = Outcome.err('Failed');
+     *
+     * console.log(success.error); // null
+     * console.log(failure.error?.message); // 'Failed'
+     * ```
+     */
+    get error() {
+        return this._tuple[1];
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Transformation
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Transform the success value using a callback.
+     *
+     * Only called if this Outcome is successful. Errors pass through unchanged.
+     * The callback can return any `CallbackReturn<U>` pattern.
+     * If the callback throws, the exception is caught and wrapped.
+     *
+     * @param fn - Transformation function receiving the success value
+     * @returns New Outcome with transformed value or original/new error
+     *
+     * @see {@link mapAsync} for the async version
+     * @see {@link mapErr} for transforming or recovering from errors
+     *
+     * @example Simple transformation
+     * ```typescript
+     * const outcome = Outcome.ok(5)
+     *   .map(n => [n * 2, null])
+     *   .map(n => [n.toString(), null]);
+     *
+     * console.log(outcome.value); // '10'
+     * ```
+     *
+     * @example Transformation that can fail
+     * ```typescript
+     * const outcome = Outcome.ok('{"name":"John"}')
+     *   .map(json => {
+     *     try {
+     *       return [JSON.parse(json), null];
+     *     } catch {
+     *       return Err.from('Invalid JSON');
+     *     }
+     *   });
+     * ```
+     *
+     * @example Error passes through
+     * ```typescript
+     * const outcome = Outcome.err('Original error')
+     *   .map(v => [v * 2, null]); // Never called
+     *
+     * console.log(outcome.error?.message); // 'Original error'
+     * ```
+     */
+    map(fn) {
+        if (this.isErr) {
+            return new Outcome([null, this._tuple[1]]);
+        }
+        try {
+            const result = fn(this._tuple[0]);
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Async version of `map()`.
+     *
+     * @param fn - Async transformation function
+     * @returns Promise of new Outcome
+     *
+     * @see {@link map} for the synchronous version
+     *
+     * @example
+     * ```typescript
+     * const outcome = await Outcome.ok(userId)
+     *   .mapAsync(async id => {
+     *     const user = await fetchUser(id);
+     *     return [user, null];
+     *   });
+     * ```
+     */
+    async mapAsync(fn) {
+        if (this.isErr) {
+            return new Outcome([null, this._tuple[1]]);
+        }
+        try {
+            const result = await fn(this._tuple[0]);
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Transform or recover from an error using a callback.
+     *
+     * Only called if this Outcome is in error state. Success passes through unchanged.
+     * The callback can return any `CallbackReturn<U>` pattern, allowing:
+     * - Recovery: return `[value, null]` to convert error to success
+     * - Transform: return `Err` or `[null, Err]` to change the error
+     *
+     * @param fn - Function receiving the error
+     * @returns New Outcome with transformed error or recovered value
+     *
+     * @see {@link mapErrAsync} for the async version
+     * @see {@link map} for transforming success values
+     *
+     * @example Recovery
+     * ```typescript
+     * const outcome = Outcome.err('Not found')
+     *   .mapErr(err => {
+     *     if (err.hasCode('NOT_FOUND')) {
+     *       return [defaultValue, null]; // recover with default
+     *     }
+     *     return err; // pass through other errors
+     *   });
+     * ```
+     *
+     * @example Error transformation
+     * ```typescript
+     * const outcome = Outcome.err('Low-level error')
+     *   .mapErr(err => err.wrap('High-level context'));
+     * ```
+     *
+     * @example Logging and pass-through
+     * ```typescript
+     * const outcome = Outcome.err('Something failed')
+     *   .mapErr(err => {
+     *     console.error('Error occurred:', err.message);
+     *     return err; // pass through unchanged
+     *   });
+     * ```
+     */
+    mapErr(fn) {
+        if (this.isOk) {
+            return this;
+        }
+        try {
+            const result = fn(this._tuple[1]);
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Async version of `mapErr()`.
+     *
+     * @param fn - Async function receiving the error
+     * @returns Promise of new Outcome
+     *
+     * @see {@link mapErr} for the synchronous version
+     *
+     * @example Async recovery with fallback fetch
+     * ```typescript
+     * const outcome = await Outcome.err('Primary failed')
+     *   .mapErrAsync(async err => {
+     *     const fallback = await fetchFromBackup();
+     *     if (fallback) return [fallback, null];
+     *     return err.wrap('Backup also failed');
+     *   });
+     * ```
+     */
+    async mapErrAsync(fn) {
+        if (this.isOk) {
+            return this;
+        }
+        try {
+            const result = await fn(this._tuple[1]);
+            return Outcome._processCallbackReturn(result);
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Side Effects
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Execute a side effect with access to the full tuple.
+     *
+     * The callback receives the tuple `[value, error]` regardless of state.
+     * Returns `this` unchanged for chaining.
+     * If the callback throws, the exception is caught and the Outcome becomes an error.
+     *
+     * @param fn - Side effect function receiving the tuple
+     * @returns This Outcome (for chaining), or error Outcome if callback throws
+     *
+     * @see {@link effectAsync} for the async version
+     *
+     * @example Logging
+     * ```typescript
+     * const outcome = Outcome.ok(42)
+     *   .effect(([val, err]) => {
+     *     if (err) console.error('Failed:', err.message);
+     *     else console.log('Success:', val);
+     *   })
+     *   .map(v => [v * 2, null]);
+     * ```
+     *
+     * @example Metrics
+     * ```typescript
+     * outcome.effect(([val, err]) => {
+     *   metrics.record({
+     *     success: !err,
+     *     value: val,
+     *     errorCode: err?.code
+     *   });
+     * });
+     * ```
+     */
+    effect(fn) {
+        try {
+            const t = this.toTuple();
+            fn(t);
+            return this;
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Async version of `effect()`.
+     *
+     * @param fn - Async side effect function
+     * @returns Promise of this Outcome
+     *
+     * @see {@link effect} for the synchronous version
+     *
+     * @example Async logging
+     * ```typescript
+     * const outcome = await Outcome.ok(data)
+     *   .effectAsync(async ([val, err]) => {
+     *     await logger.log({ value: val, error: err?.toJSON() });
+     *   });
+     * ```
+     */
+    async effectAsync(fn) {
+        try {
+            const t = this.toTuple();
+            await fn(t);
+            return this;
+        }
+        catch (e) {
+            return new Outcome([null, err_1.Err.from(e)]);
+        }
+    }
+    /**
+     * Implementation for defaultTo overloads.
+     * @internal
+     */
+    defaultTo(fallbackOrHandler, asValue) {
+        if (this.isOk) {
+            return this._tuple[0];
+        }
+        if (asValue === true) {
+            return fallbackOrHandler;
+        }
+        if (typeof fallbackOrHandler === "function") {
+            return fallbackOrHandler(this._tuple[1]);
+        }
+        return fallbackOrHandler;
+    }
+    /**
+     * Transform the Outcome into a final value by handling both cases.
+     *
+     * This is a terminal operation that exits the Outcome chain, similar to
+     * `toTuple()` but with transformation logic applied.
+     *
+     * Each handler receives only its relevant type with full type safety:
+     * - `onOk` receives `T` (guaranteed non-null value)
+     * - `onErr` receives `Err` (guaranteed error)
+     *
+     * @param onOk - Function to transform success value into final result
+     * @param onErr - Function to transform error into final result
+     * @returns The transformed value (not wrapped in Outcome)
+     * @throws If either callback throws, the exception propagates to the caller
+     *
+     * @see {@link defaultTo} for simple value extraction with fallback
+     * @see {@link toTuple} for raw tuple extraction
+     * @see {@link toJSON} for JSON serialization
+     *
+     * @example Basic transformation
+     * ```typescript
+     * const message = fetchUser(id).either(
+     *   user => `Welcome, ${user.name}!`,
+     *   err => `Error: ${err.message}`
+     * );
+     * // message is string, not Outcome<string>
+     * ```
+     *
+     * @example HTTP response building
+     * ```typescript
+     * const response = processOrder(orderId).either(
+     *   order => ({ status: 200, body: { id: order.id, total: order.total } }),
+     *   err => ({
+     *     status: err.hasCode('NOT_FOUND') ? 404 : 500,
+     *     body: { error: err.message }
+     *   })
+     * );
+     * ```
+     *
+     * @example Default value on error
+     * ```typescript
+     * const count = parseNumber(input).either(n => n, () => 0);
+     * ```
+     *
+     * @example Type transformation
+     * ```typescript
+     * const status: 'success' | 'error' = outcomeEntity.either(
+     *   () => 'success',
+     *   () => 'error'
+     * );
+     * ```
+     */
+    either(onOk, onErr) {
+        if (this.isOk) {
+            return onOk(this._tuple[0]);
+        }
+        return onErr(this._tuple[1]);
+    }
+    /**
+     * Implementation for pipe overloads.
+     * @internal
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+    pipe(...fns) {
+        // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+        let current = this;
+        for (const fn of fns) {
+            try {
+                const result = fn(current.toTuple());
+                current = Outcome._processCallbackReturn(result);
+            }
+            catch (e) {
+                // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+                current = new Outcome([null, err_1.Err.from(e)]);
+            }
+        }
+        return current;
+    }
+    /**
+     * Implementation for pipeAsync overloads.
+     * @internal
+     */
+    // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+    async pipeAsync(...fns) {
+        // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+        let current = this;
+        for (const fn of fns) {
+            try {
+                const result = await fn(current.toTuple());
+                current = Outcome._processCallbackReturn(result);
+            }
+            catch (e) {
+                // biome-ignore lint/suspicious/noExplicitAny: implementation signature needs any
+                current = new Outcome([null, err_1.Err.from(e)]);
+            }
+        }
+        return current;
+    }
+    // ══════════════════════════════════════════════════════════════════════════
+    // Conversion
+    // ══════════════════════════════════════════════════════════════════════════
+    /**
+     * Extract the internal tuple.
+     *
+     * Primary method for extracting values from an Outcome.
+     * Use destructuring for ergonomic access.
+     *
+     * @returns The internal ResultTuple<T>
+     *
+     * @see {@link fromTuple} for creating an Outcome from a tuple
+     *
+     * @example
+     * ```typescript
+     * const outcome = Outcome.ok(42);
+     * const [value, error] = outcome.toTuple();
+     *
+     * if (error) {
+     *   console.error('Failed:', error.message);
+     *   return;
+     * }
+     * console.log('Value:', value); // 42
+     * ```
+     */
+    toTuple() {
+        const [v, e] = this._tuple;
+        return [v, e];
+    }
+    /**
+     * Convert to JSON-serializable tuple.
+     *
+     * For success: returns `[value, null]`
+     * For error: returns `[null, errJSON]` where errJSON is from `Err.toJSON()`
+     *
+     * @returns JSON-serializable representation
+     *
+     * @see {@link fromJSON} for deserializing an Outcome from JSON
+     *
+     * @example
+     * ```typescript
+     * const outcome = Outcome.ok({ name: 'John' });
+     * const json = JSON.stringify(outcome.toJSON());
+     * // '[{"name":"John"},null]'
+     *
+     * // Deserialize
+     * const restored = Outcome.fromJSON(JSON.parse(json));
+     * ```
+     */
+    toJSON() {
+        if (this.isOk) {
+            return [this._tuple[0], null];
+        }
+        return [null, this._tuple[1].toJSON()];
+    }
+    /**
+     * Convert to a human-readable string.
+     *
+     * @returns String representation
+     *
+     * @example
+     * ```typescript
+     * console.log(Outcome.ok(42).toString());
+     * // 'Outcome.ok(42)'
+     *
+     * console.log(Outcome.err('Failed').toString());
+     * // 'Outcome.err([ERROR] Failed)'
+     * ```
+     */
+    toString() {
+        if (this.isOk) {
+            return `Outcome.ok(${fmt(this._tuple[0])})`;
+        }
+        return `Outcome.err(${this._tuple[1].toString()})`;
+    }
+}
+exports.Outcome = Outcome;
+function fmt(v) {
+    if (v === null)
+        return "null";
+    if (v === undefined)
+        return "undefined";
+    if (typeof v === "string")
+        return JSON.stringify(v);
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+//# sourceMappingURL=outcome.js.map