@nlozgachev/pipelined 0.31.0 → 0.33.0

package/dist/{Task-CnF22Q2o.d.ts → Task-5na0QzS4.d.mts}

@@ -1,56 +1,4 @@
-import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.js';
-
-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 {
-    /**
-     * 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`.
-     *
-     * @example
-     * ```ts
-     * const d = Deferred.fromPromise(Promise.resolve("hello"));
-     * const value = await d; // "hello"
-     * ```
-     */
-    const fromPromise: <A>(p: Promise<A>) => Deferred<A>;
-    /**
-     * Converts a `Deferred` back into a `Promise`.
-     *
-     * @example
-     * ```ts
-     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
-     * // p is Promise<42>
-     * ```
-     */
-    const toPromise: <A>(d: Deferred<A>) => Promise<A>;
-}
+import { NonEmptyList, Duration } from './types.mjs';
 
 type WithKind<K extends string> = {
     readonly kind: K;
@@ -275,6 +223,44 @@ declare namespace Result {
      * ```
      */
     const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
+    /**
+     * Creates a Result from a nullable value.
+     * Returns Ok if the value is not null or undefined, error from onNull otherwise.
+     *
+     * @example
+     * ```ts
+     * pipe(null, Result.fromNullable(() => "is null")); // Error("is null")
+     * pipe(42, Result.fromNullable(() => "is null"));   // Ok(42)
+     * ```
+     */
+    const fromNullable: <E>(onNull: () => E) => <A>(value: A | null | undefined) => Result<E, A>;
+    /**
+     * Creates a Result from a Maybe.
+     * Some becomes Ok, None becomes error from onNone.
+     *
+     * @example
+     * ```ts
+     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Error("is none")
+     * pipe(Maybe.some(42), Result.fromMaybe(() => "is none")); // Ok(42)
+     * ```
+     */
+    const fromMaybe: <E>(onNone: () => E) => <A>(maybe: Maybe<A>) => Result<E, A>;
+    /**
+     * Wraps a throwing function of any arguments, returning a new function
+     * that catches errors and returns a Result.
+     *
+     * @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');  // Error(Error)
+     * ```
+     */
+    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>`.
@@ -536,6 +522,223 @@ declare namespace Maybe {
     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 {
+    /**
+     * 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`.
+     *
+     * @example
+     * ```ts
+     * const d = Deferred.fromPromise(Promise.resolve("hello"));
+     * const value = await d; // "hello"
+     * ```
+     */
+    const fromPromise: <A>(p: Promise<A>) => Deferred<A>;
+    /**
+     * Converts a `Deferred` back into a `Promise`.
+     *
+     * @example
+     * ```ts
+     * const p = Deferred.toPromise(Deferred.fromPromise(Promise.resolve(42)));
+     * // p is Promise<42>
+     * ```
+     */
+    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 {
+    /**
+     * Equality for strings. Case-sensitive.
+     *
+     * @example
+     * ```ts
+     * Equality.string("hello", "hello"); // true
+     * Equality.string("hello", "Hello"); // false
+     * ```
+     */
+    const string: Equality<string>;
+    /**
+     * Equality for numbers. Uses strict equality.
+     *
+     * @example
+     * ```ts
+     * Equality.number(42, 42); // true
+     * ```
+     */
+    const number: Equality<number>;
+    /**
+     * Equality for booleans.
+     *
+     * @example
+     * ```ts
+     * Equality.boolean(true, true); // true
+     * ```
+     */
+    const boolean: Equality<boolean>;
+    /**
+     * Equality for `Date` values. Compares by numeric time value.
+     *
+     * @example
+     * ```ts
+     * Equality.date(new Date("2024-01-01"), new Date("2024-01-01")); // true
+     * ```
+     */
+    const date: Equality<Date>;
+    /**
+     * 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
+     * Equality.array(Equality.number)([1, 2, 3], [1, 2, 3]); // true
+     * ```
+     */
+    const array: <A>(eq: Equality<A>) => Equality<readonly 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))`.
+     *
+     * @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
+     * ```
+     */
+    const by: <A, B>(f: (b: B) => A) => (eq: Equality<A>) => Equality<B>;
+    /**
+     * 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 exact = pipe(byName, Equality.and(byRole));
+     * exact(userA, userB); // true only if name AND role match
+     * ```
+     */
+    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 {
+    /**
+     * 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>;
+}
+
 /**
  * A lazy async computation that always resolves.
  *
@@ -679,37 +882,37 @@ declare namespace Task {
      */
     const all: <T extends readonly Task<unknown>[]>(tasks: T) => Task<{ [K in keyof T]: T[K] extends Task<infer A> ? A : never; }>;
     /**
-     * Delays the execution of a Task by the specified milliseconds.
+     * Delays the execution of a Task by the specified milliseconds or duration.
      * Useful for debouncing or rate limiting.
      *
      * @example
      * ```ts
      * pipe(
      *   Task.resolve(42),
-     *   Task.delay(1000)
+     *   Task.delay(Duration.seconds(1))
      * )(); // Resolves after 1 second
      * ```
      */
-    const delay: (ms: number) => <A>(data: Task<A>) => Task<A>;
+    const delay: (ms: number | Duration) => <A>(data: Task<A>) => Task<A>;
     /**
      * Runs a Task a fixed number of times sequentially, collecting all results into an array.
-     * An optional delay (ms) can be inserted between runs.
+     * An optional delay (ms or Duration) can be inserted between runs.
      *
      * @example
      * ```ts
      * pipe(
      *   pollSensor,
-     *   Task.repeat({ times: 5, delay: 1000 })
+     *   Task.repeat({ times: 5, delay: Duration.seconds(1) })
      * )(); // Task<Reading[]> — 5 readings, one per second
      * ```
      */
     const repeat: (options: {
         times: number;
-        delay?: number;
+        delay?: number | Duration;
     }) => <A>(task: Task<A>) => Task<readonly A[]>;
     /**
      * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
-     * An optional delay (ms) can be inserted between runs.
+     * An optional delay (ms or Duration) can be inserted between runs.
      * An optional `maxAttempts` cap stops the loop after N calls — the last value is returned
      * regardless of whether the predicate was satisfied.
      *
@@ -717,18 +920,19 @@ declare namespace Task {
      * ```ts
      * pipe(
      *   checkStatus,
-     *   Task.repeatUntil({ when: (s) => s === "ready", delay: 500 })
+     *   Task.repeatUntil({ when: (s) => s === "ready", delay: Duration.milliseconds(500) })
      * )(); // polls every 500ms until status is "ready"
      * ```
      */
     const repeatUntil: <A>(options: {
         when: (a: A) => boolean;
-        delay?: number;
+        delay?: number | Duration;
         maxAttempts?: number;
     }) => (task: Task<A>) => Task<A>;
     /**
      * Resolves with the value of the first Task to complete. All Tasks start
-     * immediately; the rest are abandoned once one resolves.
+     * immediately. When one resolves, the other tasks are cancelled (aborted)
+     * downstream.
      *
      * @example
      * ```ts
@@ -739,6 +943,17 @@ declare namespace Task {
      * ```
      */
     const race: <A>(tasks: ReadonlyArray<Task<A>>) => Task<A>;
+    /**
+     * Runs an array of Tasks concurrently and collects their results in an array.
+     * Forward-propagates the call site's AbortSignal to all subtasks concurrently.
+     *
+     * @example
+     * ```ts
+     * Task.sequence([loadConfig, detectLocale, loadTheme])();
+     * // Deferred<[Config, string, Theme]>
+     * ```
+     */
+    const sequence: <A>(tasks: ReadonlyArray<Task<A>>) => Task<ReadonlyArray<A>>;
     /**
      * Runs an array of Tasks one at a time in order, collecting all results.
      * Each Task starts only after the previous one resolves.
@@ -766,12 +981,12 @@ declare namespace Task {
      * ```ts
      * pipe(
      *   heavyComputation,
-     *   Task.timeout(5000, () => "timed out"),
+     *   Task.timeout(Duration.seconds(5), () => "timed out"),
      *   TaskResult.chain(processResult)
      * );
      * ```
      */
-    const timeout: <E>(ms: number, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
+    const timeout: <E>(ms: number | Duration, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
     /**
      * Creates a Task paired with an `abort` handle. Calling `abort()` cancels the
      * current in-flight call immediately. Unlike a one-shot abort, calling `task()`
@@ -812,4 +1027,4 @@ declare namespace Task {
     const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
 }
 
-export { Deferred as D, type Error 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 WithLog as a, type WithKind as b, type WithError as c, type RetryOptions as d, type TimeoutOptions as e, type WithTimeout as f, type WithMinInterval as g, type WithCooldown as h, type WithConcurrency as i, type WithSize as j, type WithMs as k, type WithN as l, type WithErrors as m, type WithFirst as n, type WithSecond as o };
+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 Error 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 WithMs as m, type WithN as n, type WithErrors as o, type WithFirst as p, type WithSecond as q };