@nlozgachev/pipelined 0.21.0 → 0.23.0

package/README.md

@@ -1,7 +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)
 Opinionated functional abstractions for TypeScript.
 
 > **Note:** pipelined is pre-1.0. The API may change between minor versions until the 1.0 release.
@@ -21,41 +20,41 @@ timeout, and cancellation built in. And, of course, there is more than that.
 
 Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
 
-## Example
+## Example: a single async call
 
 A careful, production-minded attempt at "fetch with retry, timeout, and cancellation":
 
 ```ts
 type UserResult =
-	| { ok: true; user: User; }
-	| { ok: false; error: "Timeout" | "NetworkError"; };
+  | { ok: true; user: User; }
+  | { ok: false; error: "Timeout" | "NetworkError"; };
 
 async function fetchUser(
-	id: string,
-	signal?: AbortSignal,
+  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);
+  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);
 }
 ```
 
@@ -70,14 +69,14 @@ 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`
@@ -89,38 +88,97 @@ 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); // ApiError, not unknown
+  showError(result.error); // ApiError, not unknown
 }
 ```
 
+## Example: repeated interactions
+
+`TaskResult` handles one call well. Real UIs make the same call many times — a search input fires on every keystroke, a submit button gets clicked twice, a polling loop needs to stop when something newer starts. Each scenario has a different answer to the same question: *what happens to the previous call when a new one arrives?*
+
+`Op` makes that question a one-word configuration choice.
+
+**Search — cancel the previous call when the user types:**
+
+```ts
+import { Op } from "@nlozgachev/pipelined/core";
+
+const searchOp = Op.create(
+  (signal) => (query: string) =>
+    fetch(`/search?q=${query}`, { signal }).then((r) => r.json() as Promise<SearchResult[]>),
+  (e) => new SearchError(e),
+);
+
+const search = Op.interpret(searchOp, {
+  strategy: "restartable", // new call cancels the previous one
+  retry: { attempts: 2, backoff: 300 },
+});
+
+search.subscribe((state) => {
+  if (state.kind === "Pending")  showSpinner();
+  if (state.kind === "Retrying") showSpinner(`retrying… attempt ${state.attempt}`);
+  if (state.kind === "Ok")       showResults(state.value);
+  if (state.kind === "Err")      showError(state.error);
+});
+
+input.addEventListener("input", (e) => search.run(e.currentTarget.value));
+```
+
+**Form submit — drop concurrent submissions:**
+
+```ts
+const submitOp = Op.create(
+  (signal) => (data: FormData) =>
+    fetch("/orders", { method: "POST", body: data, signal }).then((r) => r.json()),
+  (e) => new ApiError(e),
+);
+
+const submit = Op.interpret(submitOp, {
+  strategy: "exclusive", // in-flight? new calls are dropped immediately
+});
+
+submit.subscribe((state) => {
+  submitButton.disabled = state.kind === "Pending";
+  if (state.kind === "Ok")  showConfirmation(state.value);
+  if (state.kind === "Err") showError(state.error);
+});
+
+form.addEventListener("submit", (e) => {
+  e.preventDefault();
+  submit.run(new FormData(form)); // double-clicks and rage-clicks are ignored
+});
+```
+
+`restartable`, `exclusive`, `debounced`, `throttled`, `queue`, `concurrent`, `keyed` — each strategy is a complete, tested answer to one concurrency scenario. Swap the word, keep the rest of the code.
+
 ## What's included?
 
-`TaskResult` is one type. The library also covers the rest of the states you encounter in real
-applications: values that may be absent, operations that accumulate multiple errors, data that moves
-through `NotAsked >> Loading >> ( Success | Failure )`, nested immutable updates, and computations that
-share a common environment. Every type follows the same conventions — `map`, `chain`, `match`,
-`getOrElse` — so moving between them feels familiar.
+The library covers the states you encounter in real applications: values that may be absent, operations that accumulate multiple errors, data that moves through `NotAsked >> Loading >> ( Success | Failure )`, async interactions with concurrency policies, nested immutable updates, and computations that share a common environment. Every type follows the same conventions — `map`, `chain`, `match`, `getOrElse` — so moving between them feels familiar.
 
 ### pipelined/core
 
 - **`Maybe<A>`** — a value that may not exist; propagates absence without null checks.
 - **`Result<E, A>`** — an operation that succeeds or fails with a typed error.
-- **`Validation<E, A>`** — like `Result`, but accumulates every failure instead of stopping at the
-  first.
+- **`Validation<E, A>`** — like `Result`, but accumulates every failure instead of stopping at the first.
 - **`Task<A>`** — a lazy, infallible async operation; nothing runs until called.
 - **`TaskResult<E, A>`** — a lazy async operation that can fail with a typed error.
 - **`TaskMaybe<A>`** — a lazy async operation that may produce nothing.
 - **`TaskValidation<E, A>`** — a lazy async operation that accumulates validation errors.
-- **`These<E, A>`** — an inclusive OR: holds an error, a value, or both at once.
-- **`RemoteData<E, A>`** — the four states of a data fetch: `NotAsked`, `Loading`, `Failure`,
-  `Success`.
-- **`Lens<S, A>`** — focus on a required field in a nested structure. Read, set, and modify
-  immutably.
+- **`Op<I, E, A>`** — a managed async operation with a named concurrency strategy: `restartable`, `exclusive`, `debounced`, `throttled`, `queue`, `concurrent`, `keyed`, or `once`. Handles retry, timeout, cancellation, and state in one place.
+- **`RemoteData<E, A>`** — the four states of a data fetch: `NotAsked`, `Loading`, `Failure`, `Success`.
+- **`These<A, B>`** — an inclusive OR: holds a first value, a second, or both at once.
+- **`Lens<S, A>`** — focus on a required field in a nested structure. Read, set, and modify immutably.
 - **`Optional<S, A>`** — like `Lens`, but the target may be absent (nullable fields, array indices).
-- **`Reader<R, A>`** — a computation that depends on an environment `R`, supplied once at the
-  boundary.
+- **`Reader<R, A>`** — a computation that depends on an environment `R`, supplied once at the boundary.
+- **`State<S, A>`** — a computation that reads and updates a state value, threaded explicitly through the chain.
+- **`Logged<W, A>`** — a computation that accumulates a log alongside its value; no console output, just data.
+- **`Predicate<A>`** — a typed boolean function, composable with `and`, `or`, `not`, and `using`.
+- **`Refinement<A, B>`** — a type predicate that narrows `A` to `B` at runtime; composes with `Predicate`.
+- **`Resource<E, A>`** — an acquire/release pair for safe resource management in `TaskResult` pipelines.
+- **`Deferred<A>`** — an infallible async value: a thenable that always resolves, never rejects.
+- **`Tuple<A, B>`** — a typed pair with `first`, `second`, `map`, `swap`, and `fold`.
 
 ### pipelined/utils
 

package/dist/{chunk-SSZXZTIX.mjs → chunk-UFQE2J63.mjs}

@@ -853,7 +853,7 @@ var Op;
   Op2.nil = (reason) => ({ kind: "Nil", reason });
   Op2.create = (factory, onError) => ({
     _factory: (input, signal) => Deferred.fromPromise(
-      factory(input, signal).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
+      factory(signal)(input).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
     )
   });
   Op2.ok = (value) => ({ kind: "Ok", value });

package/dist/core.d.mts

@@ -412,7 +412,7 @@ declare namespace Logged {
  * @example
  * ```ts
  * const fetchUser = Op.create(
- *   (id: string, signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
+ *   (signal) => (id: string) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
  *   (e) => new ApiError(e),
  * );
  *
@@ -655,21 +655,22 @@ declare namespace Op {
     /**
      * Creates an `Op` from an async factory and an error mapper.
      *
-     * The factory receives the input and an `AbortSignal`. Operations that support
-     * cancellation (like `fetch`) should thread the signal through. The error mapper
-     * converts any thrown value into a typed error; it is never called for aborts.
+     * The factory receives an `AbortSignal` and returns a function that takes the input.
+     * Operations that support cancellation (like `fetch`) should capture the signal in the
+     * outer closure. The error mapper converts any thrown value into a typed error; it is
+     * never called for aborts.
      *
      * @example
      * ```ts
      * const saveProfile = Op.create(
-     *   (data: ProfileData, signal) =>
+     *   (signal) => (data: ProfileData) =>
      *     fetch("/profile", { method: "POST", body: JSON.stringify(data), signal })
      *       .then(r => r.json()),
      *   (e) => new ApiError(e),
      * );
      * ```
      */
-    const create: <I, E, A>(factory: (input: I, signal: AbortSignal) => Promise<A>, onError: (e: unknown) => E) => Op<I, E, A>;
+    const create: <I, E, A>(factory: (signal: AbortSignal) => (input: I) => Promise<A>, onError: (e: unknown) => E) => Op<I, E, A>;
     /**
      * Creates a successful Outcome.
      *

package/dist/core.d.ts

@@ -412,7 +412,7 @@ declare namespace Logged {
  * @example
  * ```ts
  * const fetchUser = Op.create(
- *   (id: string, signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
+ *   (signal) => (id: string) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
  *   (e) => new ApiError(e),
  * );
  *
@@ -655,21 +655,22 @@ declare namespace Op {
     /**
      * Creates an `Op` from an async factory and an error mapper.
      *
-     * The factory receives the input and an `AbortSignal`. Operations that support
-     * cancellation (like `fetch`) should thread the signal through. The error mapper
-     * converts any thrown value into a typed error; it is never called for aborts.
+     * The factory receives an `AbortSignal` and returns a function that takes the input.
+     * Operations that support cancellation (like `fetch`) should capture the signal in the
+     * outer closure. The error mapper converts any thrown value into a typed error; it is
+     * never called for aborts.
      *
      * @example
      * ```ts
      * const saveProfile = Op.create(
-     *   (data: ProfileData, signal) =>
+     *   (signal) => (data: ProfileData) =>
      *     fetch("/profile", { method: "POST", body: JSON.stringify(data), signal })
      *       .then(r => r.json()),
      *   (e) => new ApiError(e),
      * );
      * ```
      */
-    const create: <I, E, A>(factory: (input: I, signal: AbortSignal) => Promise<A>, onError: (e: unknown) => E) => Op<I, E, A>;
+    const create: <I, E, A>(factory: (signal: AbortSignal) => (input: I) => Promise<A>, onError: (e: unknown) => E) => Op<I, E, A>;
     /**
      * Creates a successful Outcome.
      *

package/dist/core.js

@@ -959,7 +959,7 @@ var Op;
   Op2.nil = (reason) => ({ kind: "Nil", reason });
   Op2.create = (factory, onError) => ({
     _factory: (input, signal) => Deferred.fromPromise(
-      factory(input, signal).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
+      factory(signal)(input).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
     )
   });
   Op2.ok = (value) => ({ kind: "Ok", value });

package/dist/core.mjs

@@ -15,7 +15,7 @@ import {
   These,
   Tuple,
   Validation
-} from "./chunk-SSZXZTIX.mjs";
+} from "./chunk-UFQE2J63.mjs";
 import {
   Deferred,
   Maybe,

package/dist/index.js

@@ -1204,7 +1204,7 @@ var Op;
   Op2.nil = (reason) => ({ kind: "Nil", reason });
   Op2.create = (factory, onError) => ({
     _factory: (input, signal) => Deferred.fromPromise(
-      factory(input, signal).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
+      factory(signal)(input).then((value) => Result.ok(value)).catch((e) => signal.aborted ? null : Result.err(onError(e)))
     )
   });
   Op2.ok = (value) => ({ kind: "Ok", value });

package/dist/index.mjs

@@ -44,7 +44,7 @@ import {
   These,
   Tuple,
   Validation
-} from "./chunk-SSZXZTIX.mjs";
+} from "./chunk-UFQE2J63.mjs";
 import {
   Arr,
   Dict,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nlozgachev/pipelined",
-	"version": "0.21.0",
+	"version": "0.23.0",
 	"description": "Opinionated functional abstractions for TypeScript",
 	"license": "BSD-3-Clause",
 	"homepage": "https://pipelined.lozgachev.dev",