@nlozgachev/pipelined 0.37.0 → 0.38.0

package/dist/{Task-DIgwvoIb.d.ts → Task-uupX7xd9.d.ts}

@@ -1,333 +1,198 @@
 import { NonEmptyList, Duration } from './types.js';
 
-type WithKind<K extends string> = {
-    readonly kind: K;
-};
-type WithValue<T> = {
-    readonly value: T;
-};
-type WithError<T> = {
-    readonly error: T;
-};
-type WithErrors<T> = {
-    readonly errors: NonEmptyList<T>;
-};
-type WithFirst<T> = {
-    readonly first: T;
-};
-type WithSecond<T> = {
-    readonly second: T;
-};
-type WithLog<T> = {
-    readonly log: ReadonlyArray<T>;
-};
-/** Retry policy for `Op.interpret`. */
-type RetryOptions<E> = {
-    readonly attempts: number;
-    readonly backoff?: Duration | ((attempt: number) => Duration);
-    readonly when?: (error: E) => boolean;
-};
-/** Timeout policy for `Op.interpret`. Wraps the entire retry sequence. */
-type TimeoutOptions<E> = {
-    readonly duration: Duration;
-    readonly onTimeout: () => E;
-};
-type WithTimeout<E> = {
-    readonly timeout?: TimeoutOptions<E>;
-};
-type WithDuration = {
-    readonly duration: Duration;
-};
-type WithN = {
-    readonly n: number;
-};
-type WithConcurrency = {
-    readonly concurrency?: number;
-};
-type WithSize = {
-    readonly size?: number;
-};
-type WithCooldown = {
-    readonly cooldown?: Duration;
-};
-type WithMinInterval = {
-    readonly minInterval?: Duration;
-};
-
-type Ok<A> = WithKind<"Ok"> & WithValue<A>;
-type Err<E> = WithKind<"Err"> & WithError<E>;
+declare const _deferred: unique symbol;
 /**
- * Result represents a value that can be one of two types: a success (Ok) or a failure (Err).
- * Use Result when an operation can fail with a meaningful error value.
+ * A nominally typed, one-shot async value that supports `await` but enforces infallibility.
+ *
+ * Two design choices work together to make the guarantee structural rather than documentary:
+ *
+ * - The phantom `[_deferred]` symbol makes the type **nominal**: only values produced by
+ *   `Deferred.fromPromise` satisfy it. A plain object `{ then: ... }` does not.
+ * - The single-parameter `.then()` **excludes rejection handlers** by construction. There is
+ *   no second argument to pass, so chaining and `.catch()` are impossible.
+ *
+ * This makes `Deferred<A>` the natural return type for `Task<A>`, which is guaranteed to
+ * never reject.
  *
  * @example
  * ```ts
- * const divide = (a: number, b: number): Result<string, number> =>
- *   b === 0 ? Result.err("Division by zero") : Result.ok(a / b);
- *
- * pipe(
- *   divide(10, 2),
- *   Result.map(n => n * 2),
- *   Result.getOrElse(() => 0)
- * ); // 10
+ * const value = await Deferred.fromPromise(Promise.resolve(42));
+ * // value === 42
  * ```
  */
-type Result<E, A> = Ok<A> | Err<E>;
-declare namespace Result {
-    /**
-     * Creates a successful Result with the given value.
-     */
-    const ok: <A>(value: A) => Ok<A>;
-    /**
-     * Creates a failed Result with the given error.
-     */
-    const err: <E>(e: E) => Err<E>;
-    /**
-     * Type guard that checks if a Result is Ok.
-     */
-    const isOk: <E, A>(data: Result<E, A>) => data is Ok<A>;
-    /**
-     * Type guard that checks if a Result is Err.
-     */
-    const isErr: <E, A>(data: Result<E, A>) => data is Err<E>;
-    /**
-     * Creates a Result from a function that may throw.
-     * Catches any errors and transforms them using the onError function.
-     *
-     * @example
-     * ```ts
-     * const parseJson = (s: string): Result<string, unknown> =>
-     *   Result.tryCatch(
-     *     () => JSON.parse(s),
-     *     (e) => `Parse error: ${e}`
-     *   );
-     * ```
-     */
-    const tryCatch: <E, A>(f: () => A, onError: (e: unknown) => E) => Result<E, A>;
-    /**
-     * Transforms the success value inside a Result.
-     *
-     * @example
-     * ```ts
-     * pipe(Result.ok(5), Result.map(n => n * 2)); // Ok(10)
-     * pipe(Result.err("error"), Result.map(n => n * 2)); // Err("error")
-     * ```
-     */
-    const map: <E, A, B>(f: (a: A) => B) => (data: Result<E, A>) => Result<E, B>;
-    /**
-     * Transforms the error value inside a Result.
-     *
-     * @example
-     * ```ts
-     * pipe(Result.err("oops"), Result.mapError(e => e.toUpperCase())); // Err("OOPS")
-     * ```
-     */
-    const mapError: <E, F, A>(f: (e: E) => F) => (data: Result<E, A>) => Result<F, A>;
-    /**
-     * Chains Result computations. If the first is Ok, passes the value to f.
-     * If the first is Err, propagates the error.
-     *
-     * @example
-     * ```ts
-     * const validatePositive = (n: number): Result<string, number> =>
-     *   n > 0 ? Result.ok(n) : Result.err("Must be positive");
-     *
-     * pipe(Result.ok(5), Result.chain(validatePositive)); // Ok(5)
-     * pipe(Result.ok(-1), Result.chain(validatePositive)); // Err("Must be positive")
-     * ```
-     */
-    const chain: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, B>;
-    /**
-     * Extracts the value from a Result by providing handlers for both cases.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   Result.ok(5),
-     *   Result.fold(
-     *     e => `Error: ${e}`,
-     *     n => `Value: ${n}`
-     *   )
-     * ); // "Value: 5"
-     * ```
-     */
-    const fold: <E, A, B>(onErr: (e: E) => B, onOk: (a: A) => B) => (data: Result<E, A>) => B;
-    /**
-     * Pattern matches on a Result, returning the result of the matching case.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   result,
-     *   Result.match({
-     *     ok: value => `Got ${value}`,
-     *     err: error => `Failed: ${error}`
-     *   })
-     * );
-     * ```
-     */
-    const match: <E, A, B>(cases: {
-        ok: (a: A) => B;
-        err: (e: E) => B;
-    }) => (data: Result<E, A>) => B;
-    /**
-     * Returns the success value or a default value if the Result is an error.
-     * The default is a thunk `() => B` — evaluated only when the Result is Err.
-     * The default can be a different type, widening the result to `A | B`.
-     *
-     * @example
-     * ```ts
-     * pipe(Result.ok(5), Result.getOrElse(() => 0)); // 5
-     * pipe(Result.err("error"), Result.getOrElse(() => 0)); // 0
-     * pipe(Result.err("error"), Result.getOrElse(() => null)); // null — typed as number | null
-     * ```
-     */
-    const getOrElse: <E, A, B>(defaultValue: () => B) => (data: Result<E, A>) => A | B;
-    /**
-     * Executes a side effect on the success value without changing the Result.
-     * Useful for logging or debugging.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   Result.ok(5),
-     *   Result.tap(n => console.log("Value:", n)),
-     *   Result.map(n => n * 2)
-     * );
-     * ```
-     */
-    const tap: <E, A>(f: (a: A) => void) => (data: Result<E, A>) => Result<E, A>;
+type Deferred<A> = {
+    readonly [_deferred]: A;
+    readonly then: (onfulfilled: (value: A) => unknown) => void;
+};
+declare namespace Deferred {
     /**
-     * Executes a side effect on the error value without changing the Result.
-     * Useful for logging or reporting errors.
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
      *
-     * @example
-     * ```ts
-     * pipe(
-     *   Result.err("not found"),
-     *   Result.tapError(e => console.error("validation failed:", e)),
-     *   Result.chain(save),
-     * )
-     * ```
-     */
-    const tapError: <E, A>(f: (e: E) => void) => (data: Result<E, A>) => Result<E, A>;
-    /**
-     * Creates a Result from a predicate applied to a value.
-     * Returns Ok if the predicate passes, Err from onFalse otherwise.
+     * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
+     * never resolve — `await`-ing it will hang indefinitely. Use `TaskResult.tryCatch` to
+     * handle operations that may fail before converting to a `Deferred`.
      *
      * @example
      * ```ts
-     * pipe(5, Result.fromPredicate(n => n > 0, n => `${n} is not positive`));  // Ok(5)
-     * pipe(-1, Result.fromPredicate(n => n > 0, n => `${n} is not positive`)); // Err("-1 is not positive")
-     * pipe("", Result.fromPredicate(s => s.length > 0, () => "empty string")); // Err("empty string")
+     * const d = Deferred.fromPromise(Promise.resolve("hello"));
+     * const value = await d; // "hello"
      * ```
      */
-    const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
+    const fromPromise: <A>(p: Promise<A>) => Deferred<A>;
     /**
-     * Creates a Result from a nullable value.
-     * Returns Ok if the value is not null or undefined, error from onNull otherwise.
+     * Converts a `Deferred` back into a `Promise`.
      *
      * @example
      * ```ts
-     * pipe(null, Result.fromNullable(() => "is null")); // Err("is null")
-     * pipe(42, Result.fromNullable(() => "is null"));   // Ok(42)
+     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
+     * // p is Promise<42>
      * ```
      */
-    const fromNullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => Result<E, A>;
+    const toPromise: <A>(d: Deferred<A>) => Promise<A>;
+}
+
+/**
+ * A function that checks whether two values of type `A` are equal.
+ * Use built-in instances (`Equality.string`, `Equality.number`, etc.) as starting points,
+ * then adapt them with `Equality.by` and combine them with `Equality.and`.
+ *
+ * @example
+ * ```ts
+ * type User = { id: string; name: string };
+ * const byId = pipe(Equality.string, Equality.by((u: User) => u.id));
+ *
+ * pipe(users, Arr.uniqWith(byId));
+ * ```
+ */
+type Equality<A> = (a: A, b: A) => boolean;
+declare namespace Equality {
     /**
-     * Creates a Result from a Maybe.
-     * Some becomes Ok, None becomes error from onNone.
+     * Equality for strings. Case-sensitive.
      *
      * @example
      * ```ts
-     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Err("is none")
-     * pipe(Maybe.some(42), Result.fromMaybe(() => "is none")); // Ok(42)
+     * Equality.string("hello", "hello"); // true
+     * Equality.string("hello", "Hello"); // false
      * ```
      */
-    const fromMaybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => Result<E, A>;
+    const string: Equality<string>;
     /**
-     * Wraps a throwing function of any arguments, returning a new function
-     * that catches errors and returns a Result.
+     * Equality for numbers. Uses strict equality.
      *
      * @example
      * ```ts
-     * const safeParse = Result.fromThrowable(
-     *   (s: string) => JSON.parse(s),
-     *   (e) => new Error(`Parse error: ${e}`)
-     * );
-     *
-     * safeParse('{"a":1}'); // Ok({ a: 1 })
-     * safeParse('invalid');  // Err(Error)
+     * Equality.number(42, 42); // true
      * ```
      */
-    const fromThrowable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => A, onError: (e: unknown) => E) => (...args: Args) => Result<E, A>;
-    /**
-     * Recovers from an error by providing a fallback Result.
-     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
-     */
-    const recover: <E, A, B>(fallback: (e: E) => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    const number: Equality<number>;
     /**
-     * Recovers from an error unless the predicate `isBlocked` returns true for that error.
-     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
+     * Equality for booleans.
      *
      * @example
      * ```ts
-     * pipe(
-     *   Result.err(new Error("not found")),
-     *   Result.recoverUnless(e => e.message === "fatal", () => Result.ok(0))
-     * ); // Ok(0)
+     * Equality.boolean(true, true); // true
      * ```
      */
-    const recoverUnless: <E, A, B>(isBlocked: (e: E) => boolean, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    const boolean: Equality<boolean>;
     /**
-     * Converts a Result to a Maybe.
-     * Ok becomes Some, Err becomes None (the error is discarded).
+     * Equality for `Date` values. Compares by numeric time value.
      *
      * @example
      * ```ts
-     * Result.toMaybe(Result.ok(42)); // Some(42)
-     * Result.toMaybe(Result.err("oops")); // None
+     * Equality.date(new Date("2024-01-01"), new Date("2024-01-01")); // true
      * ```
      */
-    const toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
+    const date: Equality<Date>;
     /**
-     * Applies a function wrapped in a Result to a value wrapped in a Result.
+     * Lifts an element equality into an array equality. Two arrays are equal if they have the
+     * same length and every element pair is equal under `eq`.
      *
      * @example
      * ```ts
-     * const add = (a: number) => (b: number) => a + b;
-     * pipe(
-     *   Result.ok(add),
-     *   Result.ap(Result.ok(5)),
-     *   Result.ap(Result.ok(3))
-     * ); // Ok(8)
+     * Equality.array(Equality.number)([1, 2, 3], [1, 2, 3]); // true
      * ```
      */
-    const ap: <E, A>(arg: Result<E, A>) => <B>(data: Result<E, (a: A) => B>) => Result<E, B>;
+    const array: <A>(eq: Equality<A>) => Equality<readonly A[]>;
     /**
-     * Converts a Result value into an object containing a single property.
-     * Initiates the pipeline accumulator record.
+     * Adapts an equality for type `A` into an equality for type `B` by extracting a field.
+     * Read as "equality by this field": `pipe(Equality.string, Equality.by(u => u.name))`.
      *
      * @example
      * ```ts
-     * pipe(Result.ok(42), Result.bindTo("value")); // Ok({ value: 42 })
+     * type Product = { id: string; price: number };
+     * const byId = pipe(Equality.string, Equality.by((p: Product) => p.id));
+     * byId({ id: "p1", price: 9 }, { id: "p1", price: 12 }); // true
      * ```
      */
-    const bindTo: <K extends string>(key: K) => <E, A>(data: Result<E, A>) => Result<E, { [P in K]: A; }>;
+    const by: <A, B>(f: (b: B) => A) => (eq: Equality<A>) => Equality<B>;
     /**
-     * Evaluates a new Result using the current accumulator and attaches the output to a new key.
+     * Combines two equalities with logical AND. Both must pass for two values to be considered equal.
+     * Data-last: the first equality is the data being piped.
      *
      * @example
      * ```ts
-     * pipe(
-     *   Result.ok({ a: 1 }),
-     *   Result.bind("b", ({ a }) => Result.ok(a + 1))
-     * ); // Ok({ a: 1, b: 2 })
+     * const exact = pipe(byName, Equality.and(byRole));
+     * exact(userA, userB); // true only if name AND role match
      * ```
      */
-    const bind: <K extends string, E, A, B>(key: K, f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, A & { [P in K]: B; }>;
+    const and: <A>(eq2: Equality<A>) => (eq1: Equality<A>) => Equality<A>;
 }
 
+type WithKind<K extends string> = {
+    readonly kind: K;
+};
+type WithValue<T> = {
+    readonly value: T;
+};
+type WithError<T> = {
+    readonly error: T;
+};
+type WithErrors<T> = {
+    readonly errors: NonEmptyList<T>;
+};
+type WithFirst<T> = {
+    readonly first: T;
+};
+type WithSecond<T> = {
+    readonly second: T;
+};
+type WithLog<T> = {
+    readonly log: ReadonlyArray<T>;
+};
+/** Retry policy for `Op.interpret`. */
+type RetryOptions<E> = {
+    readonly attempts: number;
+    readonly backoff?: Duration | ((attempt: number) => Duration);
+    readonly when?: (error: E) => boolean;
+};
+/** Timeout policy for `Op.interpret`. Wraps the entire retry sequence. */
+type TimeoutOptions<E> = {
+    readonly duration: Duration;
+    readonly onTimeout: () => E;
+};
+type WithTimeout<E> = {
+    readonly timeout?: TimeoutOptions<E>;
+};
+type WithDuration = {
+    readonly duration: Duration;
+};
+type WithN = {
+    readonly n: number;
+};
+type WithConcurrency = {
+    readonly concurrency?: number;
+};
+type WithSize = {
+    readonly size?: number;
+};
+type WithCooldown = {
+    readonly cooldown?: Duration;
+};
+type WithMinInterval = {
+    readonly minInterval?: Duration;
+};
+
 type Some<A> = WithKind<"Some"> & WithValue<A>;
 type None = WithKind<"None">;
 /**
@@ -540,246 +405,407 @@ declare namespace Maybe {
      * ); // Some(8)
      * ```
      */
-    const ap: <A>(arg: Maybe<A>) => <B>(data: Maybe<(a: A) => B>) => Maybe<B>;
+    const ap: <A>(arg: Maybe<A>) => <B>(data: Maybe<(a: A) => B>) => Maybe<B>;
+    /**
+     * Converts a Maybe value into an object containing a single property.
+     * Initiates the pipeline accumulator record.
+     *
+     * @example
+     * ```ts
+     * pipe(Maybe.some(42), Maybe.bindTo("value")); // Some({ value: 42 })
+     * ```
+     */
+    const bindTo: <K extends string>(key: K) => <A>(data: Maybe<A>) => Maybe<{ [P in K]: A; }>;
+    /**
+     * Evaluates a new Maybe using the current accumulator and attaches the output to a new key.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Maybe.some({ a: 1 }),
+     *   Maybe.bind("b", ({ a }) => Maybe.some(a + 1))
+     * ); // Some({ a: 1, b: 2 })
+     * ```
+     */
+    const bind: <K extends string, A, B>(key: K, f: (a: A) => Maybe<B>) => (data: Maybe<A>) => Maybe<A & { [P in K]: B; }>;
+    /**
+     * Combines a record of Maybes into a single Maybe of a record.
+     * Evaluates fields in key order and short-circuits on the first None.
+     *
+     * @example
+     * ```ts
+     * Maybe.struct({
+     *   name: Maybe.some("Alice"),
+     *   age: Maybe.some(30)
+     * }); // Some({ name: "Alice", age: 30 })
+     * ```
+     */
+    const struct: <R extends Record<string, any>>(fields: { [K in keyof R]: Maybe<R[K]>; }) => Maybe<R>;
+}
+
+/**
+ * A function that orders two values of type `A`. Returns a negative number when `a` comes before
+ * `b`, a positive number when `a` comes after `b`, and `0` when they are equal.
+ *
+ * Compatible with `Array.prototype.sort` and `Arr.sortWith`.
+ *
+ * @example
+ * ```ts
+ * type Employee = { name: string; salary: number };
+ *
+ * const byName   = pipe(Ordering.string, Ordering.by((e: Employee) => e.name));
+ * const bySalary = pipe(Ordering.number, Ordering.by((e: Employee) => e.salary));
+ *
+ * pipe(employees, Arr.sortWith(pipe(byName, Ordering.thenBy(bySalary))));
+ * ```
+ */
+type Ordering<A> = (a: A, b: A) => number;
+declare namespace Ordering {
+    /**
+     * Alphabetical ordering for strings.
+     *
+     * @example
+     * ```ts
+     * Ordering.string("apple", "banana"); // negative
+     * ```
+     */
+    const string: Ordering<string>;
+    /**
+     * Numeric ordering. Equivalent to `(a, b) => a - b`.
+     *
+     * @example
+     * ```ts
+     * pipe([3, 1, 2], Arr.sortWith(Ordering.number)); // [1, 2, 3]
+     * ```
+     */
+    const number: Ordering<number>;
+    /**
+     * Ordering for `Date` values by numeric time value.
+     *
+     * @example
+     * ```ts
+     * pipe(dates, Arr.sortWith(Ordering.date)); // earliest first
+     * ```
+     */
+    const date: Ordering<Date>;
+    /**
+     * Flips the direction of an ordering.
+     *
+     * @example
+     * ```ts
+     * pipe([3, 1, 2], Arr.sortWith(Ordering.reverse(Ordering.number))); // [3, 2, 1]
+     * ```
+     */
+    const reverse: <A>(ord: Ordering<A>) => Ordering<A>;
+    /**
+     * Chains two orderings: the second is used only when the first returns `0`.
+     * Data-last: the first ordering is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const byDeptThenSalary = pipe(byDept, Ordering.thenBy(bySalary));
+     * ```
+     */
+    const thenBy: <A>(ord2: Ordering<A>) => (ord1: Ordering<A>) => Ordering<A>;
+    /**
+     * Adapts an ordering for type `A` into an ordering for type `B` by extracting a field.
+     * Read as "ordering by this field": `pipe(Ordering.number, Ordering.by(p => p.price))`.
+     *
+     * @example
+     * ```ts
+     * type Product = { name: string; price: number };
+     * const byPrice = pipe(Ordering.number, Ordering.by((p: Product) => p.price));
+     * pipe(products, Arr.sortWith(byPrice));
+     * ```
+     */
+    const by: <A, B>(f: (b: B) => A) => (ord: Ordering<A>) => Ordering<B>;
+}
+
+type Ok<A> = WithKind<"Ok"> & WithValue<A>;
+type Err<E> = WithKind<"Err"> & WithError<E>;
+/**
+ * Result represents a value that can be one of two types: a success (Ok) or a failure (Err).
+ * Use Result when an operation can fail with a meaningful error value.
+ *
+ * @example
+ * ```ts
+ * const divide = (a: number, b: number): Result<string, number> =>
+ *   b === 0 ? Result.err("Division by zero") : Result.ok(a / b);
+ *
+ * pipe(
+ *   divide(10, 2),
+ *   Result.map(n => n * 2),
+ *   Result.getOrElse(() => 0)
+ * ); // 10
+ * ```
+ */
+type Result<E, A> = Ok<A> | Err<E>;
+declare namespace Result {
+    /**
+     * Creates a successful Result with the given value.
+     */
+    const ok: <A>(value: A) => Ok<A>;
+    /**
+     * Creates a failed Result with the given error.
+     */
+    const err: <E>(e: E) => Err<E>;
+    /**
+     * Type guard that checks if a Result is Ok.
+     */
+    const isOk: <E, A>(data: Result<E, A>) => data is Ok<A>;
+    /**
+     * Type guard that checks if a Result is Err.
+     */
+    const isErr: <E, A>(data: Result<E, A>) => data is Err<E>;
+    /**
+     * Creates a Result from a function that may throw.
+     * Catches any errors and transforms them using the onError function.
+     *
+     * @example
+     * ```ts
+     * const parseJson = (s: string): Result<string, unknown> =>
+     *   Result.tryCatch(
+     *     () => JSON.parse(s),
+     *     (e) => `Parse error: ${e}`
+     *   );
+     * ```
+     */
+    const tryCatch: <E, A>(f: () => A, onError: (e: unknown) => E) => Result<E, A>;
+    /**
+     * Transforms the success value inside a Result.
+     *
+     * @example
+     * ```ts
+     * pipe(Result.ok(5), Result.map(n => n * 2)); // Ok(10)
+     * pipe(Result.err("error"), Result.map(n => n * 2)); // Err("error")
+     * ```
+     */
+    const map: <E, A, B>(f: (a: A) => B) => (data: Result<E, A>) => Result<E, B>;
     /**
-     * Converts a Maybe value into an object containing a single property.
-     * Initiates the pipeline accumulator record.
+     * Transforms the error value inside a Result.
      *
      * @example
      * ```ts
-     * pipe(Maybe.some(42), Maybe.bindTo("value")); // Some({ value: 42 })
+     * pipe(Result.err("oops"), Result.mapError(e => e.toUpperCase())); // Err("OOPS")
      * ```
      */
-    const bindTo: <K extends string>(key: K) => <A>(data: Maybe<A>) => Maybe<{ [P in K]: A; }>;
+    const mapError: <E, F, A>(f: (e: E) => F) => (data: Result<E, A>) => Result<F, A>;
     /**
-     * Evaluates a new Maybe using the current accumulator and attaches the output to a new key.
+     * Chains Result computations. If the first is Ok, passes the value to f.
+     * If the first is Err, propagates the error.
      *
      * @example
      * ```ts
-     * pipe(
-     *   Maybe.some({ a: 1 }),
-     *   Maybe.bind("b", ({ a }) => Maybe.some(a + 1))
-     * ); // Some({ a: 1, b: 2 })
+     * const validatePositive = (n: number): Result<string, number> =>
+     *   n > 0 ? Result.ok(n) : Result.err("Must be positive");
+     *
+     * pipe(Result.ok(5), Result.chain(validatePositive)); // Ok(5)
+     * pipe(Result.ok(-1), Result.chain(validatePositive)); // Err("Must be positive")
      * ```
      */
-    const bind: <K extends string, A, B>(key: K, f: (a: A) => Maybe<B>) => (data: Maybe<A>) => Maybe<A & { [P in K]: B; }>;
-}
-
-declare const _deferred: unique symbol;
-/**
- * A nominally typed, one-shot async value that supports `await` but enforces infallibility.
- *
- * Two design choices work together to make the guarantee structural rather than documentary:
- *
- * - The phantom `[_deferred]` symbol makes the type **nominal**: only values produced by
- *   `Deferred.fromPromise` satisfy it. A plain object `{ then: ... }` does not.
- * - The single-parameter `.then()` **excludes rejection handlers** by construction. There is
- *   no second argument to pass, so chaining and `.catch()` are impossible.
- *
- * This makes `Deferred<A>` the natural return type for `Task<A>`, which is guaranteed to
- * never reject.
- *
- * @example
- * ```ts
- * const value = await Deferred.fromPromise(Promise.resolve(42));
- * // value === 42
- * ```
- */
-type Deferred<A> = {
-    readonly [_deferred]: A;
-    readonly then: (onfulfilled: (value: A) => unknown) => void;
-};
-declare namespace Deferred {
+    const chain: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, B>;
     /**
-     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
-     * `.catch()`, `.finally()`, and chainable `.then()`.
-     *
-     * **Precondition**: `p` must never reject. If `p` rejects, the returned `Deferred` will
-     * never resolve — `await`-ing it will hang indefinitely. Use `TaskResult.tryCatch` to
-     * handle operations that may fail before converting to a `Deferred`.
+     * Extracts the value from a Result by providing handlers for both cases.
      *
      * @example
      * ```ts
-     * const d = Deferred.fromPromise(Promise.resolve("hello"));
-     * const value = await d; // "hello"
+     * pipe(
+     *   Result.ok(5),
+     *   Result.fold(
+     *     e => `Error: ${e}`,
+     *     n => `Value: ${n}`
+     *   )
+     * ); // "Value: 5"
      * ```
      */
-    const fromPromise: <A>(p: Promise<A>) => Deferred<A>;
+    const fold: <E, A, B>(onErr: (e: E) => B, onOk: (a: A) => B) => (data: Result<E, A>) => B;
     /**
-     * Converts a `Deferred` back into a `Promise`.
+     * Pattern matches on a Result, returning the result of the matching case.
      *
      * @example
      * ```ts
-     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
-     * // p is Promise<42>
+     * pipe(
+     *   result,
+     *   Result.match({
+     *     ok: value => `Got ${value}`,
+     *     err: error => `Failed: ${error}`
+     *   })
+     * );
      * ```
      */
-    const toPromise: <A>(d: Deferred<A>) => Promise<A>;
-}
-
-/**
- * A function that checks whether two values of type `A` are equal.
- * Use built-in instances (`Equality.string`, `Equality.number`, etc.) as starting points,
- * then adapt them with `Equality.by` and combine them with `Equality.and`.
- *
- * @example
- * ```ts
- * type User = { id: string; name: string };
- * const byId = pipe(Equality.string, Equality.by((u: User) => u.id));
- *
- * pipe(users, Arr.uniqWith(byId));
- * ```
- */
-type Equality<A> = (a: A, b: A) => boolean;
-declare namespace Equality {
+    const match: <E, A, B>(cases: {
+        ok: (a: A) => B;
+        err: (e: E) => B;
+    }) => (data: Result<E, A>) => B;
     /**
-     * Equality for strings. Case-sensitive.
+     * Returns the success value or a default value if the Result is an error.
+     * The default is a thunk `() => B` — evaluated only when the Result is Err.
+     * The default can be a different type, widening the result to `A | B`.
      *
      * @example
      * ```ts
-     * Equality.string("hello", "hello"); // true
-     * Equality.string("hello", "Hello"); // false
+     * pipe(Result.ok(5), Result.getOrElse(() => 0)); // 5
+     * pipe(Result.err("error"), Result.getOrElse(() => 0)); // 0
+     * pipe(Result.err("error"), Result.getOrElse(() => null)); // null — typed as number | null
      * ```
      */
-    const string: Equality<string>;
+    const getOrElse: <E, A, B>(defaultValue: () => B) => (data: Result<E, A>) => A | B;
     /**
-     * Equality for numbers. Uses strict equality.
+     * Executes a side effect on the success value without changing the Result.
+     * Useful for logging or debugging.
      *
      * @example
      * ```ts
-     * Equality.number(42, 42); // true
+     * pipe(
+     *   Result.ok(5),
+     *   Result.tap(n => console.log("Value:", n)),
+     *   Result.map(n => n * 2)
+     * );
      * ```
      */
-    const number: Equality<number>;
+    const tap: <E, A>(f: (a: A) => void) => (data: Result<E, A>) => Result<E, A>;
     /**
-     * Equality for booleans.
+     * Executes a side effect on the error value without changing the Result.
+     * Useful for logging or reporting errors.
      *
      * @example
      * ```ts
-     * Equality.boolean(true, true); // true
+     * pipe(
+     *   Result.err("not found"),
+     *   Result.tapError(e => console.error("validation failed:", e)),
+     *   Result.chain(save),
+     * )
      * ```
      */
-    const boolean: Equality<boolean>;
+    const tapError: <E, A>(f: (e: E) => void) => (data: Result<E, A>) => Result<E, A>;
     /**
-     * Equality for `Date` values. Compares by numeric time value.
+     * Creates a Result from a predicate applied to a value.
+     * Returns Ok if the predicate passes, Err from onFalse otherwise.
      *
      * @example
      * ```ts
-     * Equality.date(new Date("2024-01-01"), new Date("2024-01-01")); // true
+     * pipe(5, Result.fromPredicate(n => n > 0, n => `${n} is not positive`));  // Ok(5)
+     * pipe(-1, Result.fromPredicate(n => n > 0, n => `${n} is not positive`)); // Err("-1 is not positive")
+     * pipe("", Result.fromPredicate(s => s.length > 0, () => "empty string")); // Err("empty string")
      * ```
      */
-    const date: Equality<Date>;
+    const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
     /**
-     * Lifts an element equality into an array equality. Two arrays are equal if they have the
-     * same length and every element pair is equal under `eq`.
+     * Creates a Result from a nullable value.
+     * Returns Ok if the value is not null or undefined, error from onNull otherwise.
      *
      * @example
      * ```ts
-     * Equality.array(Equality.number)([1, 2, 3], [1, 2, 3]); // true
+     * pipe(null, Result.fromNullable(() => "is null")); // Err("is null")
+     * pipe(42, Result.fromNullable(() => "is null"));   // Ok(42)
      * ```
      */
-    const array: <A>(eq: Equality<A>) => Equality<readonly A[]>;
+    const fromNullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => Result<E, A>;
     /**
-     * Adapts an equality for type `A` into an equality for type `B` by extracting a field.
-     * Read as "equality by this field": `pipe(Equality.string, Equality.by(u => u.name))`.
+     * Creates a Result from a Maybe.
+     * Some becomes Ok, None becomes error from onNone.
      *
      * @example
      * ```ts
-     * type Product = { id: string; price: number };
-     * const byId = pipe(Equality.string, Equality.by((p: Product) => p.id));
-     * byId({ id: "p1", price: 9 }, { id: "p1", price: 12 }); // true
+     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Err("is none")
+     * pipe(Maybe.some(42), Result.fromMaybe(() => "is none")); // Ok(42)
      * ```
      */
-    const by: <A, B>(f: (b: B) => A) => (eq: Equality<A>) => Equality<B>;
+    const fromMaybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => Result<E, A>;
     /**
-     * Combines two equalities with logical AND. Both must pass for two values to be considered equal.
-     * Data-last: the first equality is the data being piped.
+     * Wraps a throwing function of any arguments, returning a new function
+     * that catches errors and returns a Result.
      *
      * @example
      * ```ts
-     * const exact = pipe(byName, Equality.and(byRole));
-     * exact(userA, userB); // true only if name AND role match
+     * const safeParse = Result.fromThrowable(
+     *   (s: string) => JSON.parse(s),
+     *   (e) => new Error(`Parse error: ${e}`)
+     * );
+     *
+     * safeParse('{"a":1}'); // Ok({ a: 1 })
+     * safeParse('invalid');  // Err(Error)
      * ```
      */
-    const and: <A>(eq2: Equality<A>) => (eq1: Equality<A>) => Equality<A>;
-}
-
-/**
- * A function that orders two values of type `A`. Returns a negative number when `a` comes before
- * `b`, a positive number when `a` comes after `b`, and `0` when they are equal.
- *
- * Compatible with `Array.prototype.sort` and `Arr.sortWith`.
- *
- * @example
- * ```ts
- * type Employee = { name: string; salary: number };
- *
- * const byName   = pipe(Ordering.string, Ordering.by((e: Employee) => e.name));
- * const bySalary = pipe(Ordering.number, Ordering.by((e: Employee) => e.salary));
- *
- * pipe(employees, Arr.sortWith(pipe(byName, Ordering.thenBy(bySalary))));
- * ```
- */
-type Ordering<A> = (a: A, b: A) => number;
-declare namespace Ordering {
+    const fromThrowable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => A, onError: (e: unknown) => E) => (...args: Args) => Result<E, A>;
     /**
-     * Alphabetical ordering for strings.
+     * Recovers from an error by providing a fallback Result.
+     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
+     */
+    const recover: <E, A, B>(fallback: (e: E) => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    /**
+     * Recovers from an error unless the predicate `isBlocked` returns true for that error.
+     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
      *
      * @example
      * ```ts
-     * Ordering.string("apple", "banana"); // negative
+     * pipe(
+     *   Result.err(new Error("not found")),
+     *   Result.recoverUnless(e => e.message === "fatal", () => Result.ok(0))
+     * ); // Ok(0)
      * ```
      */
-    const string: Ordering<string>;
+    const recoverUnless: <E, A, B>(isBlocked: (e: E) => boolean, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
     /**
-     * Numeric ordering. Equivalent to `(a, b) => a - b`.
+     * Converts a Result to a Maybe.
+     * Ok becomes Some, Err becomes None (the error is discarded).
      *
      * @example
      * ```ts
-     * pipe([3, 1, 2], Arr.sortWith(Ordering.number)); // [1, 2, 3]
+     * Result.toMaybe(Result.ok(42)); // Some(42)
+     * Result.toMaybe(Result.err("oops")); // None
      * ```
      */
-    const number: Ordering<number>;
+    const toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
     /**
-     * Ordering for `Date` values by numeric time value.
+     * Applies a function wrapped in a Result to a value wrapped in a Result.
      *
      * @example
      * ```ts
-     * pipe(dates, Arr.sortWith(Ordering.date)); // earliest first
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Result.ok(add),
+     *   Result.ap(Result.ok(5)),
+     *   Result.ap(Result.ok(3))
+     * ); // Ok(8)
      * ```
      */
-    const date: Ordering<Date>;
+    const ap: <E, A>(arg: Result<E, A>) => <B>(data: Result<E, (a: A) => B>) => Result<E, B>;
     /**
-     * Flips the direction of an ordering.
+     * Converts a Result value into an object containing a single property.
+     * Initiates the pipeline accumulator record.
      *
      * @example
      * ```ts
-     * pipe([3, 1, 2], Arr.sortWith(Ordering.reverse(Ordering.number))); // [3, 2, 1]
+     * pipe(Result.ok(42), Result.bindTo("value")); // Ok({ value: 42 })
      * ```
      */
-    const reverse: <A>(ord: Ordering<A>) => Ordering<A>;
+    const bindTo: <K extends string>(key: K) => <E, A>(data: Result<E, A>) => Result<E, { [P in K]: A; }>;
     /**
-     * Chains two orderings: the second is used only when the first returns `0`.
-     * Data-last: the first ordering is the data being piped.
+     * Evaluates a new Result using the current accumulator and attaches the output to a new key.
      *
      * @example
      * ```ts
-     * const byDeptThenSalary = pipe(byDept, Ordering.thenBy(bySalary));
+     * pipe(
+     *   Result.ok({ a: 1 }),
+     *   Result.bind("b", ({ a }) => Result.ok(a + 1))
+     * ); // Ok({ a: 1, b: 2 })
      * ```
      */
-    const thenBy: <A>(ord2: Ordering<A>) => (ord1: Ordering<A>) => Ordering<A>;
+    const bind: <K extends string, E, A, B>(key: K, f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, A & { [P in K]: B; }>;
     /**
-     * Adapts an ordering for type `A` into an ordering for type `B` by extracting a field.
-     * Read as "ordering by this field": `pipe(Ordering.number, Ordering.by(p => p.price))`.
+     * Combines a record of Results into a single Result of a record.
+     * Evaluates fields in key order and short-circuits on the first failure.
      *
      * @example
      * ```ts
-     * type Product = { name: string; price: number };
-     * const byPrice = pipe(Ordering.number, Ordering.by((p: Product) => p.price));
-     * pipe(products, Arr.sortWith(byPrice));
+     * Result.struct({
+     *   name: Result.ok("Alice"),
+     *   age: Result.ok(30)
+     * }); // Ok({ name: "Alice", age: 30 })
      * ```
      */
-    const by: <A, B>(f: (b: B) => A) => (ord: Ordering<A>) => Ordering<B>;
+    const struct: <E, R extends Record<string, any>>(fields: { [K in keyof R]: Result<E, R[K]>; }) => Result<E, R>;
 }
 
 /**