@nlozgachev/pipelined 0.12.0 → 0.14.0

package/dist/Task-BjAkkD6t.d.ts

@@ -0,0 +1,677 @@
+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) => void) => void;
+};
+declare namespace Deferred {
+    /**
+     * Wraps a `Promise` into a `Deferred`, structurally excluding rejection handlers,
+     * `.catch()`, `.finally()`, and chainable `.then()`.
+     *
+     * @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>;
+}
+
+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>;
+};
+
+type Ok<A> = WithKind<"Ok"> & WithValue<A>;
+type Err<E> = WithKind<"Error"> & 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>(error: E) => Err<E>;
+    /**
+     * Type guard that checks if an Result is Ok.
+     */
+    const isOk: <E, A>(data: Result<E, A>) => data is Ok<A>;
+    /**
+     * Type guard that checks if an Result is Err.
+     */
+    const isErr: <E, A>(data: Result<E, A>) => data is Err<E>;
+    /**
+     * Creates an 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 an 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 an 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 an 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>;
+    /**
+     * 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 it matches the blocked error.
+     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
+     */
+    const recoverUnless: <E, A, B>(blockedErr: E, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    /**
+     * Converts a Result to an Option.
+     * Ok becomes Some, Err becomes None (the error is discarded).
+     *
+     * @example
+     * ```ts
+     * Result.toOption(Result.ok(42)); // Some(42)
+     * Result.toOption(Result.err("oops")); // None
+     * ```
+     */
+    const toOption: <E, A>(data: Result<E, A>) => Option<A>;
+    /**
+     * Applies a function wrapped in an Result to a value wrapped in an Result.
+     *
+     * @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 ap: <E, A>(arg: Result<E, A>) => <B>(data: Result<E, (a: A) => B>) => Result<E, B>;
+}
+
+type Some<A> = WithKind<"Some"> & WithValue<A>;
+type None = WithKind<"None">;
+/**
+ * Option represents an optional value: every Option is either Some (contains a value) or None (empty).
+ * Use Option instead of null/undefined to make optionality explicit and composable.
+ *
+ * @example
+ * ```ts
+ * const findUser = (id: string): Option<User> =>
+ *   users.has(id) ? Option.some(users.get(id)!) : Option.none();
+ *
+ * pipe(
+ *   findUser("123"),
+ *   Option.map(user => user.name),
+ *   Option.getOrElse(() => "Unknown")
+ * );
+ * ```
+ */
+type Option<T> = Some<T> | None;
+declare namespace Option {
+    /**
+     * Creates a Some containing the given value.
+     */
+    const some: <A>(value: A) => Some<A>;
+    /**
+     * Type guard that checks if a Option is Some.
+     */
+    const isSome: <A>(data: Option<A>) => data is Some<A>;
+    /**
+     * Creates a None (empty Option).
+     */
+    const none: () => None;
+    /**
+     * Type guard that checks if a Option is None.
+     */
+    const isNone: <A>(data: Option<A>) => data is None;
+    /**
+     * Creates a Option from a nullable value.
+     * Returns None if the value is null or undefined, Some otherwise.
+     *
+     * @example
+     * ```ts
+     * Option.fromNullable(null); // None
+     * Option.fromNullable(42); // Some(42)
+     * ```
+     */
+    const fromNullable: <A>(value: A | null | undefined) => Option<A>;
+    /**
+     * Extracts the value from a Option, returning null if None.
+     */
+    const toNullable: <A>(data: Option<A>) => A | null;
+    /**
+     * Extracts the value from a Option, returning undefined if None.
+     */
+    const toUndefined: <A>(data: Option<A>) => A | undefined;
+    /**
+     * Creates a Option from a possibly undefined value.
+     * Returns None if undefined, Some otherwise.
+     */
+    const fromUndefined: <A>(value: A | undefined) => Option<A>;
+    /**
+     * Converts an Option to a Result.
+     * Some becomes Ok, None becomes Err with the provided error.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(42),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Ok(42)
+     *
+     * pipe(
+     *   Option.none(),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Err("Value was missing")
+     * ```
+     */
+    const toResult: <E>(onNone: () => E) => <A>(data: Option<A>) => Result<E, A>;
+    /**
+     * Creates an Option from a Result.
+     * Ok becomes Some, Err becomes None (the error is discarded).
+     *
+     * @example
+     * ```ts
+     * Option.fromResult(Result.ok(42)); // Some(42)
+     * Option.fromResult(Result.err("oops")); // None
+     * ```
+     */
+    const fromResult: <E, A>(data: Result<E, A>) => Option<A>;
+    /**
+     * Transforms the value inside a Option if it exists.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.map(n => n * 2)); // Some(10)
+     * pipe(Option.none(), Option.map(n => n * 2)); // None
+     * ```
+     */
+    const map: <A, B>(f: (a: A) => B) => (data: Option<A>) => Option<B>;
+    /**
+     * Chains Option computations. If the first is Some, passes the value to f.
+     * If the first is None, propagates None.
+     *
+     * @example
+     * ```ts
+     * const parseNumber = (s: string): Option<number> => {
+     *   const n = parseInt(s, 10);
+     *   return isNaN(n) ? Option.none() : Option.some(n);
+     * };
+     *
+     * pipe(Option.some("42"), Option.chain(parseNumber)); // Some(42)
+     * pipe(Option.some("abc"), Option.chain(parseNumber)); // None
+     * ```
+     */
+    const chain: <A, B>(f: (a: A) => Option<B>) => (data: Option<A>) => Option<B>;
+    /**
+     * Extracts the value from a Option by providing handlers for both cases.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(5),
+     *   Option.fold(
+     *     () => "No value",
+     *     n => `Value: ${n}`
+     *   )
+     * ); // "Value: 5"
+     * ```
+     */
+    const fold: <A, B>(onNone: () => B, onSome: (a: A) => B) => (data: Option<A>) => B;
+    /**
+     * Pattern matches on a Option, returning the result of the matching case.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   optionUser,
+     *   Option.match({
+     *     some: user => `Hello, ${user.name}`,
+     *     none: () => "Hello, stranger"
+     *   })
+     * );
+     * ```
+     */
+    const match: <A, B>(cases: {
+        none: () => B;
+        some: (a: A) => B;
+    }) => (data: Option<A>) => B;
+    /**
+     * Returns the value inside an Option, or a default value if None.
+     * The default is a thunk `() => B` — evaluated only when the Option is None.
+     * The default can be a different type, widening the result to `A | B`.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.getOrElse(() => 0)); // 5
+     * pipe(Option.none(), Option.getOrElse(() => 0)); // 0
+     * pipe(Option.none<string>(), Option.getOrElse(() => null)); // null — typed as string | null
+     * ```
+     */
+    const getOrElse: <A, B>(defaultValue: () => B) => (data: Option<A>) => A | B;
+    /**
+     * Executes a side effect on the value without changing the Option.
+     * Useful for logging or debugging.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(5),
+     *   Option.tap(n => console.log("Value:", n)),
+     *   Option.map(n => n * 2)
+     * );
+     * ```
+     */
+    const tap: <A>(f: (a: A) => void) => (data: Option<A>) => Option<A>;
+    /**
+     * Filters a Option based on a predicate.
+     * Returns None if the predicate returns false or if the Option is already None.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.filter(n => n > 3)); // Some(5)
+     * pipe(Option.some(2), Option.filter(n => n > 3)); // None
+     * ```
+     */
+    const filter: <A>(predicate: (a: A) => boolean) => (data: Option<A>) => Option<A>;
+    /**
+     * Recovers from a None by providing a fallback Option.
+     * The fallback can produce a different type, widening the result to `Option<A | B>`.
+     */
+    const recover: <A, B>(fallback: () => Option<B>) => (data: Option<A>) => Option<A | B>;
+    /**
+     * Applies a function wrapped in a Option to a value wrapped in a Option.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Option.some(add),
+     *   Option.ap(Option.some(5)),
+     *   Option.ap(Option.some(3))
+     * ); // Some(8)
+     * ```
+     */
+    const ap: <A>(arg: Option<A>) => <B>(data: Option<(a: A) => B>) => Option<B>;
+}
+
+/**
+ * A lazy async computation that always resolves.
+ *
+ * Two guarantees:
+ * - **Lazy** — nothing starts until you call it.
+ * - **Infallible** — it never rejects. If failure is possible, encode it in the
+ *   return type using `TaskResult<E, A>` instead.
+ *
+ * Calling a Task returns a `Deferred<A>` — a one-shot async value that supports
+ * `await` but has no `.catch()`, `.finally()`, or chainable `.then()`.
+ *
+ * **Consuming a Task:**
+ *
+ * Use `await task()` to run it and get the value directly:
+ * ```ts
+ * const value: number = await task();
+ * ```
+ *
+ * When you need an explicit `Promise<A>` (e.g. for a third-party API), convert
+ * the `Deferred` with `Deferred.toPromise`:
+ * ```ts
+ * const p: Promise<number> = Deferred.toPromise(task());
+ * ```
+ *
+ * @example
+ * ```ts
+ * const getTimestamp: Task<number> = Task.resolve(Date.now());
+ *
+ * // Nothing runs yet — getTimestamp is just a description
+ * const formatted = pipe(
+ *   getTimestamp,
+ *   Task.map(ts => new Date(ts).toISOString())
+ * );
+ *
+ * // Execute when ready
+ * const result = await formatted();
+ * ```
+ */
+type Task<A> = () => Deferred<A>;
+declare namespace Task {
+    /**
+     * Creates a Task that immediately resolves to the given value.
+     *
+     * @example
+     * ```ts
+     * const task = Task.resolve(42);
+     * const value = await task(); // 42
+     * ```
+     */
+    const resolve: <A>(value: A) => Task<A>;
+    /**
+     * Creates a Task from a function that returns a Promise.
+     *
+     * @example
+     * ```ts
+     * const getTimestamp = Task.from(() => Promise.resolve(Date.now()));
+     * ```
+     */
+    const from: <A>(f: () => Promise<A>) => Task<A>;
+    /**
+     * Transforms the value inside a Task.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Task.resolve(5),
+     *   Task.map(n => n * 2)
+     * )(); // Deferred<10>
+     * ```
+     */
+    const map: <A, B>(f: (a: A) => B) => (data: Task<A>) => Task<B>;
+    /**
+     * Chains Task computations. Passes the resolved value of the first Task to f.
+     *
+     * @example
+     * ```ts
+     * const readUserId: Task<string> = Task.resolve(session.userId);
+     * const loadPrefs = (id: string): Task<Preferences> =>
+     *   Task.resolve(prefsCache.get(id));
+     *
+     * pipe(
+     *   readUserId,
+     *   Task.chain(loadPrefs)
+     * )(); // Deferred<Preferences>
+     * ```
+     */
+    const chain: <A, B>(f: (a: A) => Task<B>) => (data: Task<A>) => Task<B>;
+    /**
+     * Applies a function wrapped in a Task to a value wrapped in a Task.
+     * Both Tasks run in parallel.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Task.resolve(add),
+     *   Task.ap(Task.resolve(5)),
+     *   Task.ap(Task.resolve(3))
+     * )(); // Deferred<8>
+     * ```
+     */
+    const ap: <A>(arg: Task<A>) => <B>(data: Task<(a: A) => B>) => Task<B>;
+    /**
+     * Executes a side effect on the value without changing the Task.
+     * Useful for logging or debugging.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   loadConfig,
+     *   Task.tap(cfg => console.log("Config:", cfg)),
+     *   Task.map(buildReport)
+     * );
+     * ```
+     */
+    const tap: <A>(f: (a: A) => void) => (data: Task<A>) => Task<A>;
+    /**
+     * Runs multiple Tasks in parallel and collects their results.
+     *
+     * @example
+     * ```ts
+     * Task.all([loadConfig, detectLocale, loadTheme])();
+     * // Deferred<[Config, string, Theme]>
+     * ```
+     */
+    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.
+     * Useful for debouncing or rate limiting.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Task.resolve(42),
+     *   Task.delay(1000)
+     * )(); // Resolves after 1 second
+     * ```
+     */
+    const delay: (ms: number) => <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.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   pollSensor,
+     *   Task.repeat({ times: 5, delay: 1000 })
+     * )(); // Task<Reading[]> — 5 readings, one per second
+     * ```
+     */
+    const repeat: (options: {
+        times: number;
+        delay?: number;
+    }) => <A>(task: Task<A>) => Task<A[]>;
+    /**
+     * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
+     * An optional delay (ms) can be inserted between runs.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   checkStatus,
+     *   Task.repeatUntil({ when: (s) => s === "ready", delay: 500 })
+     * )(); // polls every 500ms until status is "ready"
+     * ```
+     */
+    const repeatUntil: <A>(options: {
+        when: (a: A) => boolean;
+        delay?: 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.
+     *
+     * @example
+     * ```ts
+     * const fast = Task.from(() => new Promise<string>(r => setTimeout(() => r("fast"), 10)));
+     * const slow = Task.from(() => new Promise<string>(r => setTimeout(() => r("slow"), 200)));
+     *
+     * await Task.race([fast, slow])(); // "fast"
+     * ```
+     */
+    const race: <A>(tasks: ReadonlyArray<Task<A>>) => Task<A>;
+    /**
+     * Runs an array of Tasks one at a time in order, collecting all results.
+     * Each Task starts only after the previous one resolves.
+     *
+     * @example
+     * ```ts
+     * let log: number[] = [];
+     * const makeTask = (n: number) => Task.from(() => {
+     *   log.push(n);
+     *   return Promise.resolve(n);
+     * });
+     *
+     * await Task.sequential([makeTask(1), makeTask(2), makeTask(3)])();
+     * // log = [1, 2, 3] — tasks ran in order
+     * ```
+     */
+    const sequential: <A>(tasks: ReadonlyArray<Task<A>>) => Task<ReadonlyArray<A>>;
+    /**
+     * Converts a `Task<A>` into a `Task<Result<E, A>>`, resolving to `Err` if the
+     * Task does not complete within the given time.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   heavyComputation,
+     *   Task.timeout(5000, () => "timed out"),
+     *   TaskResult.chain(processResult)
+     * );
+     * ```
+     */
+    const timeout: <E>(ms: number, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
+}
+
+export { Deferred as D, type Err as E, type None as N, type Ok as O, Result as R, type Some as S, Task as T, type WithValue as W, Option as a, type WithLog as b, type WithKind as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithSecond as g };