@nlozgachev/pipelined 0.31.0 → 0.32.0

package/dist/core.d.ts

@@ -1,7 +1,171 @@
-import { M as Maybe, W as WithValue, a as WithLog, D as Deferred, R as Result, b as WithKind, c as WithError, d as RetryOptions, e as TimeoutOptions, f as WithTimeout, g as WithMinInterval, h as WithCooldown, i as WithConcurrency, j as WithSize, k as WithMs, l as WithN, T as Task, m as WithErrors, n as WithFirst, o as WithSecond } from './Task-CnF22Q2o.js';
-export { E as Error, N as None, O as Ok, S as Some } from './Task-CnF22Q2o.js';
+import { M as Maybe, W as WithValue, c as WithLog, D as Deferred, R as Result, d as WithKind, e as WithError, f as RetryOptions, g as TimeoutOptions, h as WithTimeout, i as WithMinInterval, j as WithCooldown, k as WithConcurrency, l as WithSize, m as WithMs, n as WithN, T as Task, o as WithErrors, p as WithFirst, q as WithSecond } from './Task-CjYKLeTY.js';
+export { E as Equality, a as Error, N as None, O as Ok, b as Ordering, S as Some } from './Task-CjYKLeTY.js';
 import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.js';
 
+/**
+ * A type that can combine two values of type `A` into one, with a neutral starting value.
+ * `empty` is the identity: `combine(empty)(a) === a` and `combine(a)(empty) === a`.
+ * `combine(b)(a)` appends `b` onto `a` — `a` is the accumulated value, `b` is the new element.
+ *
+ * @example
+ * ```ts
+ * pipe(["hello", ", ", "world"], Combinable.fold(Combinable.string)); // "hello, world"
+ * pipe([1, 2, 3, 4, 5], Combinable.fold(Combinable.sum));            // 15
+ * ```
+ */
+type Combinable<A> = {
+    readonly empty: A;
+    readonly combine: (b: A) => (a: A) => A;
+};
+declare namespace Combinable {
+    /**
+     * Combines strings by concatenation. Empty string is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe(["a", "b", "c"], Combinable.fold(Combinable.string)); // "abc"
+     * ```
+     */
+    const string: Combinable<string>;
+    /**
+     * Combines numbers by addition. `0` is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Combinable.fold(Combinable.sum)); // 6
+     * ```
+     */
+    const sum: Combinable<number>;
+    /**
+     * Combines numbers by multiplication. `1` is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe([2, 3, 4], Combinable.fold(Combinable.product)); // 24
+     * ```
+     */
+    const product: Combinable<number>;
+    /**
+     * Combines booleans with logical AND. `true` is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe([true, true, false], Combinable.fold(Combinable.all)); // false
+     * ```
+     */
+    const all: Combinable<boolean>;
+    /**
+     * Combines booleans with logical OR. `false` is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe([false, false, true], Combinable.fold(Combinable.any)); // true
+     * ```
+     */
+    const any: Combinable<boolean>;
+    /**
+     * Combines arrays by concatenation. Empty array is the neutral element.
+     *
+     * @example
+     * ```ts
+     * pipe([[1, 2], [3], [4, 5]], Combinable.fold(Combinable.array<number>())); // [1, 2, 3, 4, 5]
+     * ```
+     */
+    const array: <A>() => Combinable<readonly A[]>;
+    /**
+     * Lifts a `Combinable<A>` to `Combinable<Maybe<A>>`. `None` is the neutral element —
+     * combining with `None` on either side returns the other value unchanged.
+     * Two `Some` values combine their inner values using the inner `Combinable`.
+     *
+     * @example
+     * ```ts
+     * const c = Combinable.maybe(Combinable.sum);
+     * c.combine(Maybe.some(3))(Maybe.some(2)); // Some(5)
+     * c.combine(Maybe.none())(Maybe.some(5));  // Some(5)
+     * ```
+     */
+    const maybe: <A>(inner: Combinable<A>) => Combinable<Maybe<A>>;
+    /**
+     * Folds an array into a single value using the `Combinable`'s `empty` as the starting point.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4, 5], Combinable.fold(Combinable.sum)); // 15
+     * pipe([], Combinable.fold(Combinable.sum));               // 0
+     * ```
+     */
+    const fold: <A>(c: Combinable<A>) => (data: readonly A[]) => A;
+}
+
+/**
+ * A synchronous memoized computation. The factory function runs exactly once —
+ * on the first call to `Lazy.evaluate` — and the result is cached for all subsequent calls.
+ *
+ * @example
+ * ```ts
+ * const config = Lazy.from(() => parseConfig(rawInput));
+ *
+ * pipe(
+ *   config,
+ *   Lazy.map(cfg => cfg.port),
+ *   Lazy.evaluate,
+ * ); // parseConfig ran once; cfg.port returned
+ * ```
+ */
+type Lazy<A> = {
+    readonly get: () => A;
+};
+declare namespace Lazy {
+    /**
+     * Wraps a thunk in a `Lazy`. The thunk runs exactly once, on first `evaluate`.
+     *
+     * @example
+     * ```ts
+     * const expensive = Lazy.from(() => computeExpensiveValue(input));
+     * ```
+     */
+    const from: <A>(f: () => A) => Lazy<A>;
+    /**
+     * Forces evaluation and returns the cached result. Safe to call multiple times.
+     *
+     * @example
+     * ```ts
+     * const value = Lazy.evaluate(Lazy.from(() => 42)); // 42
+     * ```
+     */
+    const evaluate: <A>(lazy: Lazy<A>) => A;
+    /**
+     * Transforms the result of a `Lazy` without triggering evaluation.
+     *
+     * @example
+     * ```ts
+     * pipe(Lazy.from(() => loadConfig()), Lazy.map(cfg => cfg.port));
+     * ```
+     */
+    const map: <A, B>(f: (a: A) => B) => (lazy: Lazy<A>) => Lazy<B>;
+    /**
+     * Chains a `Lazy`-returning transformation without triggering evaluation.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Lazy.from(() => loadConfig()),
+     *   Lazy.chain(cfg => Lazy.from(() => openConnection(cfg.dbUrl))),
+     * );
+     * ```
+     */
+    const chain: <A, B>(f: (a: A) => Lazy<B>) => (lazy: Lazy<A>) => Lazy<B>;
+    /**
+     * Runs a side effect on the value without changing it. Fires once, on first `evaluate`.
+     *
+     * @example
+     * ```ts
+     * pipe(Lazy.from(() => compute()), Lazy.tap(v => console.log("computed:", v)));
+     * ```
+     */
+    const tap: <A>(f: (a: A) => void) => (lazy: Lazy<A>) => Lazy<A>;
+}
+
 /** Keys of T for which undefined is assignable (i.e. optional fields). */
 type OptionalKeys<T> = {
     [K in keyof T]-?: undefined extends T[K] ? K : never;
@@ -1888,6 +2052,11 @@ declare namespace TaskResult {
      * ```
      */
     const tapError: <E, A>(f: (e: E) => void) => (data: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Applies a function wrapped in a TaskResult to a value wrapped in a TaskResult.
+     * Both Tasks run in parallel.
+     */
+    const ap: <E, A>(arg: TaskResult<E, A>) => <B>(data: TaskResult<E, (a: A) => B>) => TaskResult<E, B>;
     /**
      * Executes a `TaskResult` with an optional signal, returning `Promise<Result<E, A>>`.
      * Use as a terminal step in a `pipe` chain.
@@ -2230,15 +2399,16 @@ declare namespace TaskMaybe {
     /**
      * Creates a TaskMaybe from a Promise-returning function.
      * Returns Some if the promise resolves, None if it rejects.
+     * The factory optionally receives an `AbortSignal` forwarded from the call site.
      *
      * @example
      * ```ts
-     * const fetchUser = TaskMaybe.tryCatch(() =>
-     *   fetch("/user/1").then(r => r.json())
+     * const fetchUser = TaskMaybe.tryCatch((signal) =>
+     *   fetch("/user/1", { signal }).then(r => r.json())
      * );
      * ```
      */
-    const tryCatch: <A>(f: () => Promise<A>) => TaskMaybe<A>;
+    const tryCatch: <A>(f: (signal?: AbortSignal) => Promise<A>) => TaskMaybe<A>;
     /**
      * Transforms the value inside a TaskMaybe.
      */
@@ -2627,17 +2797,18 @@ declare namespace TaskValidation {
     /**
      * Creates a TaskValidation from a Promise-returning function.
      * Catches any errors and transforms them using the onError function.
+     * The factory optionally receives an `AbortSignal` forwarded from the call site.
      *
      * @example
      * ```ts
      * const fetchUser = (id: string): TaskValidation<string, User> =>
      *   TaskValidation.tryCatch(
-     *     () => fetch(`/users/${id}`).then(r => r.json()),
+     *     (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
      *     e => `Failed to fetch user: ${e}`
      *   );
      * ```
      */
-    const tryCatch: <E, A>(f: () => Promise<A>, onError: (e: unknown) => E) => TaskValidation<E, A>;
+    const tryCatch: <E, A>(f: (signal?: AbortSignal) => Promise<A>, onError: (e: unknown) => E) => TaskValidation<E, A>;
     /**
      * Transforms the success value inside a TaskValidation.
      */
@@ -3079,4 +3250,4 @@ declare namespace Tuple {
     const tap: <A, B>(f: (a: A, b: B) => void) => (tuple: Tuple<A, B>) => Tuple<A, B>;
 }
 
-export { Deferred, type Failure, type Invalid, Lens, type Loading, Logged, Maybe, type NotAsked, Op, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, TaskMaybe, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };
+export { Combinable, Deferred, type Failure, type Invalid, Lazy, Lens, type Loading, Logged, Maybe, type NotAsked, Op, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, TaskMaybe, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };