@nlozgachev/pipelined 0.20.0 → 0.21.0

package/README.md

@@ -1,6 +1,6 @@
 # pipelined
 
-[![npm](https://img.shields.io/npm/v/@nlozgachev/pipelined?style=for-the-badge&color=000&logo=npm&label&logoColor=fff)](https://www.npmjs.com/package/@nlozgachev/pipelined)[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nlozgachev/pipelined/publish.yml?style=for-the-badge&color=000&logo=githubactions&label&logoColor=fff)](https://github.com/nlozgachev/pipelined/actions/workflows/publish.yml)[![Codecov](https://img.shields.io/codecov/c/github/nlozgachev/pipelined?style=for-the-badge&color=000&logo=codecov&label&logoColor=fff)](https://app.codecov.io/github/nlozgachev/pipelined)[![TypeScript](https://img.shields.io/badge/-0?style=for-the-badge&color=000&logo=typescript&label&logoColor=fff)](https://www.typescriptlang.org)
+[![npm](https://img.shields.io/npm/v/@nlozgachev/pipelined?style=for-the-badge&color=000&logo=npm&label&logoColor=fff)](https://www.npmjs.com/package/@nlozgachev/pipelined) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/nlozgachev/pipelined/publish.yml?style=for-the-badge&color=000&logo=githubactions&label&logoColor=fff)](https://github.com/nlozgachev/pipelined/actions/workflows/publish.yml) [![Codecov](https://img.shields.io/codecov/c/github/nlozgachev/pipelined?style=for-the-badge&color=000&logo=codecov&label&logoColor=fff)](https://app.codecov.io/github/nlozgachev/pipelined) [![TypeScript](https://img.shields.io/badge/-0?style=for-the-badge&color=000&logo=typescript&label&logoColor=fff)](https://www.typescriptlang.org)
 
 Opinionated functional abstractions for TypeScript.
 
@@ -23,45 +23,61 @@ Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.l
 
 ## Example
 
-The standard approach to "fetch with retry and timeout":
+A careful, production-minded attempt at "fetch with retry, timeout, and cancellation":
 
 ```ts
-async function fetchUser(id: string, signal?: AbortSignal): Promise<User> {
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= 3; attempt++) {
-    try {
-      const res = await fetch(`/users/${id}`, { signal });
-      if (!res.ok) throw new Error(`HTTP ${res.status}`);
-      return await res.json();
-    } catch (e) {
-      if (signal?.aborted) throw e;
-      lastError = e;
-      if (attempt < 3) await new Promise(r => setTimeout(r, attempt * 1000));
-    }
-  }
-  throw lastError;
+type UserResult =
+	| { ok: true; user: User; }
+	| { ok: false; error: "Timeout" | "NetworkError"; };
+
+async function fetchUser(
+	id: string,
+	signal?: AbortSignal,
+): Promise<UserResult> {
+	async function attempt(n: number): Promise<UserResult> {
+		const controller = new AbortController();
+		const timerId = setTimeout(() => controller.abort(), 5000);
+		signal?.addEventListener("abort", () => controller.abort(), { once: true });
+
+		try {
+			const res = await fetch(`/users/${id}`, { signal: controller.signal });
+			clearTimeout(timerId);
+			return { ok: true, user: await res.json() };
+		} catch (e) {
+			clearTimeout(timerId);
+			if ((e as Error).name === "AbortError" && !signal?.aborted) {
+				return { ok: false, error: "Timeout" };
+			}
+			if (n < 3) {
+				await new Promise((r) => setTimeout(r, n * 1000));
+				return attempt(n + 1);
+			}
+			return { ok: false, error: "NetworkError" };
+		}
+	}
+	return attempt(1);
 }
 ```
 
-The caller receives a `Promise<User>`. What it rejects with is `unknown`. The signal is checked by
-hand. The timeout is missing. The retry loop is inlined and will need to be rewritten for the next
-endpoint too.
+The signal is forwarded by hand. The timeout needs its own controller. Timed-out aborts are
+distinguished from external cancellation by checking `signal?.aborted`. The retry is recursive
+to thread the attempt count.
 
 With **pipelined**:
 
 ```ts
-import { TaskResult } from "@nlozgachev/pipelined/core";
 import { pipe } from "@nlozgachev/pipelined/composition";
+import { Result, TaskResult } from "@nlozgachev/pipelined/core";
 
 const fetchUser = (id: string): TaskResult<ApiError, User> =>
-  pipe(
-    TaskResult.tryCatch(
-      (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
-      (e) => new ApiError(e),
-    ),
-    TaskResult.timeout(5000, () => new ApiError("request timed out")),
-    TaskResult.retry({ attempts: 3, backoff: (n) => n * 1000 }),
-  );
+	pipe(
+		TaskResult.tryCatch(
+			(signal) => fetch(`/users/${id}`, { signal }).then((r) => r.json()),
+			(e) => new ApiError(e),
+		),
+		TaskResult.timeout(5000, () => new ApiError("request timed out")),
+		TaskResult.retry({ attempts: 3, backoff: (n) => n * 1000 }),
+	);
 ```
 
 `TaskResult<ApiError, User>` is a lazy function — nothing runs until called. The `AbortSignal`
@@ -73,9 +89,9 @@ const controller = new AbortController();
 const result = await fetchUser("42")(controller.signal);
 
 if (Result.isOk(result)) {
-  render(result.value); // User
+	render(result.value); // User
 } else {
-  showError(result.error.message); // ApiError, not unknown
+	showError(result.error); // ApiError, not unknown
 }
 ```
 
@@ -106,7 +122,6 @@ share a common environment. Every type follows the same conventions — `map`, `
 - **`Reader<R, A>`** — a computation that depends on an environment `R`, supplied once at the
   boundary.
 
-
 ### pipelined/utils
 
 Everyday utilities for built-in JS types.
@@ -133,9 +148,6 @@ have custom implementations that in several cases run faster than the native met
 - **`pipe`**, **`flow`**, **`compose`** — function composition.
 - **`curry`** / **`uncurry`**, **`tap`**, **`memoize`**, and other function utilities.
 
-
-
-
 ## License
 
 BSD-3-Clause

package/dist/{Task-JOnNAaPq.d.mts → Task-CT8iwwuB.d.mts}

@@ -22,13 +22,17 @@ declare const _deferred: unique symbol;
  */
 type Deferred<A> = {
     readonly [_deferred]: A;
-    readonly then: (onfulfilled: (value: A) => void) => void;
+    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"));
@@ -69,6 +73,76 @@ type WithSecond<T> = {
 type WithLog<T> = {
     readonly log: ReadonlyArray<T>;
 };
+/** Retry policy for `Op.interpret`. */
+type RetryOptions<E> = {
+    readonly attempts: number;
+    readonly backoff?: number | ((attempt: number) => number);
+    readonly when?: (error: E) => boolean;
+};
+/** Timeout policy for `Op.interpret`. Wraps the entire retry sequence. */
+type TimeoutOptions<E> = {
+    readonly ms: number;
+    readonly onTimeout: () => E;
+};
+type WithRetry<E> = {
+    readonly retry: RetryOptions<E>;
+};
+type WithTimeout<E> = {
+    readonly timeout?: TimeoutOptions<E>;
+};
+type WithMs = {
+    readonly ms: number;
+};
+/** For `throttled`: also fire on the trailing edge after the cooldown. */
+type WithTrailing = {
+    readonly trailing: true;
+};
+/** For `debounced`: also fire on the leading edge (first call). */
+type WithLeading = {
+    readonly leading: true;
+};
+/** For `debounced`: maximum ms before the trailing call fires regardless of continued activity. */
+type WithMaxWait = {
+    readonly maxWait: number;
+};
+type WithN = {
+    readonly n: number;
+};
+/**
+ * `O` is a string literal (or union of literals) representing the overflow value.
+ * The generic lets overload signatures discriminate on the specific value:
+ *   `WithOverflow<"drop">` → `{ overflow: "drop" }`
+ *   `WithOverflow<"replace-last">` → `{ overflow: "replace-last" }`
+ * Used by both `concurrent` (`"drop" | "queue"`) and `queue` (`"drop" | "replace-last"`).
+ * `extends string` prevents `WithOverflow<42>` from being valid.
+ */
+type WithOverflow<O extends string> = {
+    readonly overflow: O;
+};
+type WithMaxSize = {
+    readonly maxSize: number;
+};
+type WithConcurrency = {
+    readonly concurrency?: number;
+};
+type WithDedupe<I> = {
+    readonly dedupe: (a: I, b: I) => boolean;
+};
+type WithSize = {
+    readonly size?: number;
+};
+type WithCooldown = {
+    readonly cooldown?: number;
+};
+type WithMinInterval = {
+    readonly minInterval?: number;
+};
+type WithKey<I, K> = {
+    readonly key: (input: I) => K;
+};
+type WithPerKey<S extends string> = {
+    readonly perKey: S;
+};
 
 type Ok<A> = WithKind<"Ok"> & WithValue<A>;
 type Err<E> = WithKind<"Error"> & WithError<E>;
@@ -703,4 +777,4 @@ declare namespace Task {
     };
 }
 
-export { Deferred as D, type Err 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 WithErrors as d, type WithFirst as e, type WithSecond as f };
+export { Deferred as D, type Err 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 WithMs as f, type WithTrailing as g, type WithRetry as h, type WithTimeout as i, type WithLeading as j, type WithMaxWait as k, type WithN as l, type WithOverflow as m, type WithKey as n, type WithPerKey as o, type WithMinInterval as p, type WithCooldown as q, type WithMaxSize as r, type WithDedupe as s, type WithConcurrency as t, type WithSize as u, type WithErrors as v, type WithFirst as w, type WithSecond as x };

package/dist/{Task-BAT6Z6b9.d.ts → Task-GSGtQO1m.d.ts}

@@ -22,13 +22,17 @@ declare const _deferred: unique symbol;
  */
 type Deferred<A> = {
     readonly [_deferred]: A;
-    readonly then: (onfulfilled: (value: A) => void) => void;
+    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"));
@@ -69,6 +73,76 @@ type WithSecond<T> = {
 type WithLog<T> = {
     readonly log: ReadonlyArray<T>;
 };
+/** Retry policy for `Op.interpret`. */
+type RetryOptions<E> = {
+    readonly attempts: number;
+    readonly backoff?: number | ((attempt: number) => number);
+    readonly when?: (error: E) => boolean;
+};
+/** Timeout policy for `Op.interpret`. Wraps the entire retry sequence. */
+type TimeoutOptions<E> = {
+    readonly ms: number;
+    readonly onTimeout: () => E;
+};
+type WithRetry<E> = {
+    readonly retry: RetryOptions<E>;
+};
+type WithTimeout<E> = {
+    readonly timeout?: TimeoutOptions<E>;
+};
+type WithMs = {
+    readonly ms: number;
+};
+/** For `throttled`: also fire on the trailing edge after the cooldown. */
+type WithTrailing = {
+    readonly trailing: true;
+};
+/** For `debounced`: also fire on the leading edge (first call). */
+type WithLeading = {
+    readonly leading: true;
+};
+/** For `debounced`: maximum ms before the trailing call fires regardless of continued activity. */
+type WithMaxWait = {
+    readonly maxWait: number;
+};
+type WithN = {
+    readonly n: number;
+};
+/**
+ * `O` is a string literal (or union of literals) representing the overflow value.
+ * The generic lets overload signatures discriminate on the specific value:
+ *   `WithOverflow<"drop">` → `{ overflow: "drop" }`
+ *   `WithOverflow<"replace-last">` → `{ overflow: "replace-last" }`
+ * Used by both `concurrent` (`"drop" | "queue"`) and `queue` (`"drop" | "replace-last"`).
+ * `extends string` prevents `WithOverflow<42>` from being valid.
+ */
+type WithOverflow<O extends string> = {
+    readonly overflow: O;
+};
+type WithMaxSize = {
+    readonly maxSize: number;
+};
+type WithConcurrency = {
+    readonly concurrency?: number;
+};
+type WithDedupe<I> = {
+    readonly dedupe: (a: I, b: I) => boolean;
+};
+type WithSize = {
+    readonly size?: number;
+};
+type WithCooldown = {
+    readonly cooldown?: number;
+};
+type WithMinInterval = {
+    readonly minInterval?: number;
+};
+type WithKey<I, K> = {
+    readonly key: (input: I) => K;
+};
+type WithPerKey<S extends string> = {
+    readonly perKey: S;
+};
 
 type Ok<A> = WithKind<"Ok"> & WithValue<A>;
 type Err<E> = WithKind<"Error"> & WithError<E>;
@@ -703,4 +777,4 @@ declare namespace Task {
     };
 }
 
-export { Deferred as D, type Err 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 WithErrors as d, type WithFirst as e, type WithSecond as f };
+export { Deferred as D, type Err 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 WithMs as f, type WithTrailing as g, type WithRetry as h, type WithTimeout as i, type WithLeading as j, type WithMaxWait as k, type WithN as l, type WithOverflow as m, type WithKey as n, type WithPerKey as o, type WithMinInterval as p, type WithCooldown as q, type WithMaxSize as r, type WithDedupe as s, type WithConcurrency as t, type WithSize as u, type WithErrors as v, type WithFirst as w, type WithSecond as x };

package/dist/{chunk-RUDOUVQR.mjs → chunk-2DPG2RDB.mjs}

@@ -1,13 +1,11 @@
 // src/Core/Deferred.ts
-var _store = /* @__PURE__ */ new WeakMap();
 var Deferred;
 ((Deferred2) => {
-  Deferred2.fromPromise = (p) => {
-    const d = { then: ((f) => p.then(f)) };
-    _store.set(d, p);
-    return d;
-  };
-  Deferred2.toPromise = (d) => _store.get(d) ?? new Promise((resolve) => d.then(resolve));
+  Deferred2.fromPromise = (p) => (
+    // eslint-disable-next-line unicorn/no-thenable -- Deferred is intentionally thenable; it is the mechanism that makes Task awaitable
+    { then: ((f) => p.then(f)) }
+  );
+  Deferred2.toPromise = (d) => new Promise((resolve) => d.then(resolve));
 })(Deferred || (Deferred = {}));
 
 // src/Core/Maybe.ts

package/dist/{chunk-AC7RQXWC.mjs → chunk-C3Z56PCR.mjs}

@@ -3,7 +3,7 @@ import {
   Maybe,
   Result,
   Task
-} from "./chunk-RUDOUVQR.mjs";
+} from "./chunk-2DPG2RDB.mjs";
 import {
   isNonEmptyList
 } from "./chunk-DBIC62UV.mjs";
@@ -364,7 +364,7 @@ var Rec;
     const vals = Object.values(data);
     const result = {};
     for (let i = 0; i < keys2.length; i++) {
-      result[keys2[i]] = f(vals[i]);
+      Object.defineProperty(result, keys2[i], { value: f(vals[i]), writable: true, enumerable: true, configurable: true });
     }
     return result;
   };
@@ -373,21 +373,30 @@ var Rec;
     const vals = Object.values(data);
     const result = {};
     for (let i = 0; i < keys2.length; i++) {
-      result[keys2[i]] = f(keys2[i], vals[i]);
+      Object.defineProperty(result, keys2[i], {
+        value: f(keys2[i], vals[i]),
+        writable: true,
+        enumerable: true,
+        configurable: true
+      });
     }
     return result;
   };
   Rec2.filter = (predicate) => (data) => {
     const result = {};
     for (const [k, v] of Object.entries(data)) {
-      if (predicate(v)) result[k] = v;
+      if (predicate(v)) {
+        Object.defineProperty(result, k, { value: v, writable: true, enumerable: true, configurable: true });
+      }
     }
     return result;
   };
   Rec2.filterWithKey = (predicate) => (data) => {
     const result = {};
     for (const [k, v] of Object.entries(data)) {
-      if (predicate(k, v)) result[k] = v;
+      if (predicate(k, v)) {
+        Object.defineProperty(result, k, { value: v, writable: true, enumerable: true, configurable: true });
+      }
     }
     return result;
   };
@@ -400,8 +409,11 @@ var Rec;
     const result = {};
     for (const item of items) {
       const key = keyFn(item);
-      if (key in result) result[key].push(item);
-      else result[key] = [item];
+      if (Object.hasOwn(result, key)) {
+        result[key].push(item);
+      } else {
+        Object.defineProperty(result, key, { value: [item], writable: true, enumerable: true, configurable: true });
+      }
     }
     return result;
   };
@@ -409,7 +421,7 @@ var Rec;
     const result = {};
     for (const key of pickedKeys) {
       if (Object.hasOwn(data, key)) {
-        result[key] = data[key];
+        Object.defineProperty(result, key, { value: data[key], writable: true, enumerable: true, configurable: true });
       }
     }
     return result;
@@ -419,7 +431,12 @@ var Rec;
     const result = {};
     for (const key of Object.keys(data)) {
       if (!omitSet.has(key)) {
-        result[key] = data[key];
+        Object.defineProperty(result, key, {
+          value: data[key],
+          writable: true,
+          enumerable: true,
+          configurable: true
+        });
       }
     }
     return result;
@@ -433,14 +450,16 @@ var Rec;
   Rec2.mapKeys = (f) => (data) => {
     const result = {};
     for (const [k, v] of Object.entries(data)) {
-      result[f(k)] = v;
+      Object.defineProperty(result, f(k), { value: v, writable: true, enumerable: true, configurable: true });
     }
     return result;
   };
   Rec2.compact = (data) => {
     const result = {};
     for (const [k, v] of Object.entries(data)) {
-      if (v.kind === "Some") result[k] = v.value;
+      if (v.kind === "Some") {
+        Object.defineProperty(result, k, { value: v.value, writable: true, enumerable: true, configurable: true });
+      }
     }
     return result;
   };