@nlozgachev/pipelined 0.42.0 → 0.44.0

package/README.md

@@ -17,7 +17,7 @@ npm add @nlozgachev/pipelined
 In mainstream TypeScript, code is often burdened by implicit control flow: unchecked exceptions,
 manual null propagation, and unhandled asynchronous failures. `pipelined` turns these complex
 runtime states into simple, transparent data structures that compose. By representing optionality as
-`Maybe`, failures as `Result`, lazy asynchronous pipelines as `TaskResult`, and repeated stateful
+`Maybe`, failures as `Result`, lazy asynchronous pipelines as `Task.Result`, and repeated stateful
 interactions as `Op`, the library helps disentangle business logic from control mechanics.
 
 ## Documentation
@@ -55,18 +55,18 @@ Every step that sees `None` is skipped. The fallback runs once, at the end.
 ## Example: typed async errors
 
 In JavaScript, asynchronous exceptions bypass the static type system, leaving unhandled rejections
-as invisible runtime risks. `TaskResult<E, A>` represents fallible asynchronous computations as
+as invisible runtime risks. `Task.Result<E, A>` represents fallible asynchronous computations as
 lazy, infallible tasks that resolve to a typed `Result`. The error type is explicitly tracked in the
 function signature, ensuring that failures are handled before compile time:
 
 ```ts
 import { pipe } from "@nlozgachev/pipelined/composition";
-import { Result, TaskResult } from "@nlozgachev/pipelined/core";
+import { Result, Task } from "@nlozgachev/pipelined/core";
 
 type ApiError = { status: number; message: string };
 
-const fetchUser = (id: string): TaskResult<ApiError, User> =>
-  TaskResult.tryCatch(
+const fetchUser = (id: string): Task.Result<ApiError, User> =>
+  Task.Result.tryCatch(
     (signal) =>
       fetch(`/users/${id}`, { signal }).then((r) => {
         if (!r.ok) throw { status: r.status, message: r.statusText };
@@ -75,8 +75,8 @@ const fetchUser = (id: string): TaskResult<ApiError, User> =>
     (e) => e as ApiError,
   );
 
-const fetchPosts = (userId: string): TaskResult<ApiError, Post[]> =>
-  TaskResult.tryCatch(
+const fetchPosts = (userId: string): Task.Result<ApiError, Post[]> =>
+  Task.Result.tryCatch(
     (signal) =>
       fetch(`/users/${userId}/posts`, { signal }).then((r) => r.json()),
     (e) => e as ApiError,
@@ -86,10 +86,10 @@ const fetchPosts = (userId: string): TaskResult<ApiError, Post[]> =>
 const userWithPosts = (id: string) =>
   pipe(
     fetchUser(id),
-    TaskResult.chain((user) =>
+    Task.Result.chain((user) =>
       pipe(
         fetchPosts(user.id),
-        TaskResult.map((posts) => ({ ...user, posts })),
+        Task.Result.map((posts) => ({ ...user, posts })),
       )
     ),
   );
@@ -314,7 +314,7 @@ provides a strongly-typed, immutable two-element pair.
 ### Asynchronous operations
 
 `Task` represents a lazy, infallible asynchronous computation. Fallible asynchronous workflows are
-handled by `TaskResult`, `TaskMaybe`, and `TaskValidation`. For managing stateful, recurring
+handled by `Task.Result`, `Task.Maybe`, and `Task.Validation`. For managing stateful, recurring
 asynchronous operations with complex scheduling, `Op` implements named concurrency strategies such
 as `restartable`, `exclusive`, `debounced`, `throttled`, and `queue`, handling retries, timeouts,
 and signal propagation automatically. `Deferred` represents a lightweight, infallible asynchronous

package/dist/InternalTypes-7o9-yrHq.d.ts

@@ -0,0 +1,118 @@
+import { Duration } from './types.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` or `Deferred` 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 `Task.Result.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: Thenable<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>;
+}
+
+/**
+ * Represents a promise-like object or a deferred value that can be resolved with `.then()`.
+ */
+type Thenable<A> = PromiseLike<A> | Deferred<A>;
+/**
+ * Represents a value that can be either a synchronous value or a Thenable.
+ */
+type Awaitable<A> = A | Thenable<A>;
+type NonEmptyArr<A> = readonly [A, ...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: NonEmptyArr<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;
+};
+
+export { type Awaitable as A, Deferred as D, type NonEmptyArr as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type TimeoutOptions as a, type WithCooldown as b, type WithDuration as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithKind as g, type WithLog as h, type WithMinInterval as i, type WithN as j, type WithSecond as k, type WithSize as l, type WithTimeout as m, type WithValue as n };

package/dist/InternalTypes-BL23H8Qr.d.mts

@@ -0,0 +1,118 @@
+import { Duration } from './types.mjs';
+
+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` or `Deferred` 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 `Task.Result.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: Thenable<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>;
+}
+
+/**
+ * Represents a promise-like object or a deferred value that can be resolved with `.then()`.
+ */
+type Thenable<A> = PromiseLike<A> | Deferred<A>;
+/**
+ * Represents a value that can be either a synchronous value or a Thenable.
+ */
+type Awaitable<A> = A | Thenable<A>;
+type NonEmptyArr<A> = readonly [A, ...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: NonEmptyArr<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;
+};
+
+export { type Awaitable as A, Deferred as D, type NonEmptyArr as N, type RetryOptions as R, type Thenable as T, type WithConcurrency as W, type TimeoutOptions as a, type WithCooldown as b, type WithDuration as c, type WithError as d, type WithErrors as e, type WithFirst as f, type WithKind as g, type WithLog as h, type WithMinInterval as i, type WithN as j, type WithSecond as k, type WithSize as l, type WithTimeout as m, type WithValue as n };