@nlozgachev/pipelined 0.36.0 → 0.37.1

package/dist/{Task-DXsuurnc.d.mts → Task-DcXhCZYg.d.mts}

@@ -1,311 +1,198 @@
 import { NonEmptyList, Duration } from './types.mjs';
 
-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;
+type Deferred<A> = {
+    readonly [_deferred]: A;
+    readonly then: (onfulfilled: (value: A) => unknown) => void;
+};
+declare namespace Deferred {
     /**
-     * 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`.
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
      *
-     * @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.
+     * **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(
-     *   Result.ok(5),
-     *   Result.tap(n => console.log("Value:", n)),
-     *   Result.map(n => n * 2)
-     * );
+     * const d = Deferred.fromPromise(Promise.resolve("hello"));
+     * const value = await d; // "hello"
      * ```
      */
-    const tap: <E, A>(f: (a: A) => void) => (data: Result<E, A>) => Result<E, A>;
+    const fromPromise: <A>(p: Promise<A>) => Deferred<A>;
     /**
-     * Executes a side effect on the error value without changing the Result.
-     * Useful for logging or reporting errors.
+     * Converts a `Deferred` back into a `Promise`.
      *
      * @example
      * ```ts
-     * pipe(
-     *   Result.err("not found"),
-     *   Result.tapError(e => console.error("validation failed:", e)),
-     *   Result.chain(save),
-     * )
+     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
+     * // p is Promise<42>
      * ```
      */
-    const tapError: <E, A>(f: (e: E) => void) => (data: Result<E, A>) => 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 predicate applied to a value.
-     * Returns Ok if the predicate passes, Err from onFalse otherwise.
+     * Equality for strings. Case-sensitive.
      *
      * @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")
+     * Equality.string("hello", "hello"); // true
+     * Equality.string("hello", "Hello"); // false
      * ```
      */
-    const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
+    const string: Equality<string>;
     /**
-     * Creates a Result from a nullable value.
-     * Returns Ok if the value is not null or undefined, error from onNull otherwise.
+     * Equality for numbers. Uses strict equality.
      *
      * @example
      * ```ts
-     * pipe(null, Result.fromNullable(() => "is null")); // Err("is null")
-     * pipe(42, Result.fromNullable(() => "is null"));   // Ok(42)
+     * Equality.number(42, 42); // true
      * ```
      */
-    const fromNullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => Result<E, A>;
+    const number: Equality<number>;
     /**
-     * Creates a Result from a Maybe.
-     * Some becomes Ok, None becomes error from onNone.
+     * Equality for booleans.
      *
      * @example
      * ```ts
-     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Err("is none")
-     * pipe(Maybe.some(42), Result.fromMaybe(() => "is none")); // Ok(42)
+     * Equality.boolean(true, true); // true
      * ```
      */
-    const fromMaybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => Result<E, A>;
+    const boolean: Equality<boolean>;
     /**
-     * Wraps a throwing function of any arguments, returning a new function
-     * that catches errors and returns a Result.
+     * Equality for `Date` values. Compares by numeric time value.
      *
      * @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.date(new Date("2024-01-01"), new Date("2024-01-01")); // 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 date: Equality<Date>;
     /**
-     * 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>`.
+     * 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
-     * pipe(
-     *   Result.err(new Error("not found")),
-     *   Result.recoverUnless(e => e.message === "fatal", () => Result.ok(0))
-     * ); // Ok(0)
+     * Equality.array(Equality.number)([1, 2, 3], [1, 2, 3]); // true
      * ```
      */
-    const recoverUnless: <E, A, B>(isBlocked: (e: E) => boolean, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    const array: <A>(eq: Equality<A>) => Equality<readonly A[]>;
     /**
-     * Converts a Result to a Maybe.
-     * Ok becomes Some, Err becomes None (the error is discarded).
+     * 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
-     * Result.toMaybe(Result.ok(42)); // Some(42)
-     * Result.toMaybe(Result.err("oops")); // None
+     * 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 toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
+    const by: <A, B>(f: (b: B) => A) => (eq: Equality<A>) => Equality<B>;
     /**
-     * Applies a function wrapped in a Result to a value wrapped in a Result.
+     * 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
-     * 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 exact = pipe(byName, Equality.and(byRole));
+     * exact(userA, userB); // true only if name AND role match
      * ```
      */
-    const ap: <E, A>(arg: Result<E, A>) => <B>(data: Result<E, (a: A) => B>) => Result<E, 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">;
 /**
@@ -504,238 +391,421 @@ declare namespace Maybe {
      * Recovers from a None by providing a fallback Maybe.
      * The fallback can produce a different type, widening the result to `Maybe<A | B>`.
      */
-    const recover: <A, B>(fallback: () => Maybe<B>) => (data: Maybe<A>) => Maybe<A | B>;
+    const recover: <A, B>(fallback: () => Maybe<B>) => (data: Maybe<A>) => Maybe<A | B>;
+    /**
+     * Applies a function wrapped in a Maybe to a value wrapped in a Maybe.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Maybe.some(add),
+     *   Maybe.ap(Maybe.some(5)),
+     *   Maybe.ap(Maybe.some(3))
+     * ); // Some(8)
+     * ```
+     */
+    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>;
+    /**
+     * 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>;
     /**
-     * Applies a function wrapped in a Maybe to a value wrapped in a Maybe.
+     * Chains Result computations. If the first is Ok, passes the value to f.
+     * If the first is Err, propagates the error.
      *
      * @example
      * ```ts
-     * const add = (a: number) => (b: number) => a + b;
-     * pipe(
-     *   Maybe.some(add),
-     *   Maybe.ap(Maybe.some(5)),
-     *   Maybe.ap(Maybe.some(3))
-     * ); // Some(8)
+     * 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 ap: <A>(arg: Maybe<A>) => <B>(data: Maybe<(a: A) => B>) => Maybe<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>;
 }
 
 /**
@@ -1024,6 +1094,28 @@ declare namespace Task {
      * ```
      */
     const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
+    /**
+     * Converts a Task value into an object containing a single property.
+     * Initiates the pipeline accumulator record.
+     *
+     * @example
+     * ```ts
+     * pipe(Task.resolve(42), Task.bindTo("value")); // Task({ value: 42 })
+     * ```
+     */
+    const bindTo: <K extends string>(key: K) => <A>(data: Task<A>) => Task<{ [P in K]: A; }>;
+    /**
+     * Evaluates a new Task using the current accumulator and attaches the output to a new key.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Task.resolve({ a: 1 }),
+     *   Task.bind("b", ({ a }) => Task.resolve(a + 1))
+     * ); // Task({ a: 1, b: 2 })
+     * ```
+     */
+    const bind: <K extends string, A, B>(key: K, f: (a: A) => Task<B>) => (data: Task<A>) => Task<A & { [P in K]: B; }>;
 }
 
-export { Deferred as D, Equality as E, Maybe as M, type None as N, type Ok as O, Result as R, type Some as S, Task as T, type WithValue as W, type Err as a, Ordering as b, type WithLog as c, type WithKind as d, type WithError as e, type RetryOptions as f, type TimeoutOptions as g, type WithTimeout as h, type WithMinInterval as i, type WithCooldown as j, type WithConcurrency as k, type WithSize as l, type WithDuration as m, type WithN as n, type WithErrors as o, type WithFirst as p, type WithSecond as q };
+export { Deferred as D, Equality as E, Maybe as M, type None as N, type Ok as O, Result as R, type Some as S, Task as T, type WithConcurrency as W, type Err as a, Ordering as b, type RetryOptions as c, type TimeoutOptions as d, type WithCooldown as e, type WithDuration as f, type WithError as g, type WithErrors as h, type WithFirst as i, type WithKind as j, type WithLog as k, type WithMinInterval as l, type WithN as m, type WithSecond as n, type WithSize as o, type WithTimeout as p, type WithValue as q };