@nlozgachev/pipelined 0.27.0 → 0.29.0

package/README.md

@@ -2,7 +2,6 @@
 
 [![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.
@@ -14,15 +13,132 @@ npm add @nlozgachev/pipelined
 ## Possibly maybe
 
 **pipelined** names every possible state and gives you operations that compose. `Maybe<A>` for values
-that may or may not be there. `Result<E, A>` for operations that succeed or fail
-with a typed error. `TaskResult<E, A>` for async operations that do both — lazily, with retry,
-timeout, and cancellation built in. And, of course, there is more than that.
+that may or may not be there. `Result<E, A>` for operations that succeed or fail with a typed error.
+`TaskResult<E, A>` for async operations that keep failures as typed values and propagate cancellation
+automatically. `Op<I, E, A>` for managing repeated async interactions — retry, timeout, and
+concurrency strategy in one place. And, of course, there is more than that.
 
 ## Documentation
 
 Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
 
-## Example: a single async call
+## Example: composing optional values
+
+`null` checks accumulate fast. Each one is a conditional branch that the type system can't help you
+forget. `Maybe<A>` turns absence into a value that composes — the same operations apply whether or
+not anything is there:
+
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Maybe } from "@nlozgachev/pipelined/core";
+import { Num, Str } from "@nlozgachev/pipelined/utils";
+
+const parseDiscount = (raw: string): string =>
+  pipe(
+    raw,
+    Str.trim,
+    Num.parse, // "10" → Some(10), "abc" → None
+    Maybe.filter((n) => n >= 0 && n <= 100), // out of range → None
+    Maybe.map((n) => `${n}% off`),
+    Maybe.getOrElse(() => "No discount"),
+  );
+
+parseDiscount("  15  "); // "15% off"
+parseDiscount("150"); // "No discount"
+parseDiscount("abc"); // "No discount"
+```
+
+Every step that sees `None` is skipped. The fallback runs once, at the end.
+
+## Example: typed async errors
+
+Unhandled rejections are invisible until they crash. `TaskResult<E, A>` keeps failures as typed
+values — the error type is part of the signature, not a runtime surprise.
+
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Result, TaskResult } from "@nlozgachev/pipelined/core";
+
+type ApiError = { status: number; message: string; };
+
+const fetchUser = (id: string): TaskResult<ApiError, User> =>
+  TaskResult.tryCatch(
+    (signal) =>
+      fetch(`/users/${id}`, { signal }).then((r) => {
+        if (!r.ok) throw { status: r.status, message: r.statusText };
+        return r.json() as Promise<User>;
+      }),
+    (e) => e as ApiError,
+  );
+
+const fetchPosts = (userId: string): TaskResult<ApiError, Post[]> =>
+  TaskResult.tryCatch(
+    (signal) => fetch(`/users/${userId}/posts`, { signal }).then((r) => r.json()),
+    (e) => e as ApiError,
+  );
+
+// Chain two requests — the AbortSignal propagates to both automatically
+const userWithPosts = (id: string) =>
+  pipe(
+    fetchUser(id),
+    TaskResult.chain((user) =>
+      pipe(
+        fetchPosts(user.id),
+        TaskResult.map((posts) => ({ ...user, posts })),
+      )
+    ),
+  );
+```
+
+`userWithPosts` is a lazy function — nothing runs until called. The `AbortSignal` threads through
+both requests: abort at any point and whichever request is in flight is cancelled immediately.
+
+```ts
+const controller = new AbortController();
+const fetchUserWithPosts = userWithPosts("42"); // build the lazy task
+const result = await fetchUserWithPosts(controller.signal); // run it — signal controls cancellation
+
+if (Result.isOk(result)) {
+  render(result.value); // { ...User, posts: Post[] }
+} else {
+  showError(result.error); // ApiError — typed, not unknown
+}
+```
+
+## Example: transforming data
+
+The utils modules wrap JavaScript's built-in types with data-last, curried operations that return
+`Maybe` wherever a value might be absent. They compose naturally with the core types:
+
+```ts
+import { pipe } from "@nlozgachev/pipelined/composition";
+import { Maybe } from "@nlozgachev/pipelined/core";
+import { Arr, Num, Rec, Str } from "@nlozgachev/pipelined/utils";
+
+type RawItem = { name: string; price: string; category: string; };
+type Item = { name: string; price: number; category: string; };
+
+const normalise = (raw: RawItem): Maybe<Item> =>
+  pipe(
+    Num.parse(raw.price), // "9.99" → Some(9.99), "n/a" → None
+    Maybe.map((price) => ({ name: Str.trim(raw.name), price, category: raw.category })),
+  );
+
+const cheapestByCategory = (items: RawItem[]) =>
+  pipe(
+    items,
+    Arr.filterMap(normalise), // parse + drop unparseable prices in one pass
+    Arr.sortBy((a, b) => a.price - b.price), // ascending price
+    Arr.groupBy((item) => item.category), // Record<string, NonEmptyList<Item>>
+    Rec.map((group) => Arr.head(group)), // cheapest per category — Maybe<Item>
+  );
+```
+
+`filterMap` applies a function that returns `Maybe` and collects only the `Some` results — one step
+replaces a `map` followed by a `filter`. `Arr.head` returns `Maybe<Item>` rather than `Item | undefined`,
+so the absence is explicit in the type and the rest of the pipeline handles it the same way.
+
+## Example: retry, timeout, and cancellation
 
 A careful, production-minded attempt at "fetch with retry, timeout, and cancellation":
 
@@ -67,38 +183,44 @@ to thread the attempt count.
 With **pipelined**:
 
 ```ts
-import { pipe } from "@nlozgachev/pipelined/composition";
-import { Result, TaskResult } from "@nlozgachev/pipelined/core";
+import { Op } 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 }),
-  );
+const fetchUser = Op.interpret(
+  Op.create(
+    (signal) => (id: string) =>
+      fetch(`/users/${id}`, { signal }).then((r) => r.json() as Promise<User>),
+    (e) => new ApiError(e),
+  ),
+  {
+    strategy: "restartable",
+    retry: { attempts: 3, backoff: (n) => n * 1000 },
+    timeout: { ms: 5000, onTimeout: () => new ApiError("request timed out") },
+  },
+);
 ```
 
-`TaskResult<ApiError, User>` is a lazy function — nothing runs until called. The `AbortSignal`
-threads through every retry and the timeout automatically. The return type is the contract:
-`ApiError` on the left, `User` on the right, nothing escapes as an exception.
+`fetchUser` is a managed operator — nothing runs until you call `run`. Retry logic, signal
+propagation, and timeout wiring are handled automatically. The outcome type is the contract:
+`ApiError` on the left, `User` on the right, nothing escapes as an unhandled exception.
 
 ```ts
-const controller = new AbortController();
-const result = await fetchUser("42")(controller.signal);
+const outcome = await fetchUser.run("42");
 
-if (Result.isOk(result)) {
-  render(result.value); // User
-} else {
-  showError(result.error); // ApiError, not unknown
+if (Op.isOk(outcome)) {
+  render(outcome.value); // User
+} else if (Op.isErr(outcome)) {
+  showError(outcome.error); // ApiError, not unknown
 }
+
+// explicit cancellation — in-flight request is aborted immediately
+fetchUser.abort();
 ```
 
 ## 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?*
+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.
 
@@ -119,10 +241,10 @@ const search = Op.interpret(searchOp, {
 });
 
 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);
+  if (Op.isPending(state)) showSpinner();
+  if (Op.isRetrying(state)) showSpinner(`retrying… attempt ${state.attempt}`);
+  if (Op.isOk(state)) showResults(state.value);
+  if (Op.isError(state)) showError(state.error);
 });
 
 input.addEventListener("input", (e) => search.run(e.currentTarget.value));
@@ -142,9 +264,9 @@ const submit = Op.interpret(submitOp, {
 });
 
 submit.subscribe((state) => {
-  submitButton.disabled = state.kind === "Pending";
-  if (state.kind === "Ok")  showConfirmation(state.value);
-  if (state.kind === "Err") showError(state.error);
+  submitButton.disabled = Op.isPending(state);
+  if (Op.isOk(state)) showConfirmation(state.value);
+  if (Op.isError(state)) showError(state.error);
 });
 
 form.addEventListener("submit", (e) => {
@@ -153,7 +275,7 @@ form.addEventListener("submit", (e) => {
 });
 ```
 
-`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.
+`restartable`, `exclusive`, `debounced`, `throttled`, `queue`, `buffered`, `concurrent`, `keyed`, `once` — each strategy is a complete, tested answer to one concurrency scenario. Swap the word, keep the rest of the code.
 
 ## What's included?
 
@@ -168,7 +290,7 @@ The library covers the states you encounter in real applications: values that ma
 - **`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.
-- **`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.
+- **`Op<I, E, A>`** — a managed async operation with a named concurrency strategy: `restartable`, `exclusive`, `debounced`, `throttled`, `queue`, `buffered`, `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.

package/dist/{Task-vQb3-puQ.d.mts → Task-BDcKwFAj.d.mts}

@@ -107,15 +107,15 @@ type WithMinInterval = {
 };
 
 type Ok<A> = WithKind<"Ok"> & WithValue<A>;
-type Err<E> = WithKind<"Error"> & WithError<E>;
+type Error<E> = WithKind<"Error"> & WithError<E>;
 /**
- * Result represents a value that can be one of two types: a success (Ok) or a failure (Err).
+ * Result represents a value that can be one of two types: a success (Ok) or a failure (Error).
  * 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);
+ *   b === 0 ? Result.error("Division by zero") : Result.ok(a / b);
  *
  * pipe(
  *   divide(10, 2),
@@ -124,7 +124,7 @@ type Err<E> = WithKind<"Error"> & WithError<E>;
  * ); // 10
  * ```
  */
-type Result<E, A> = Ok<A> | Err<E>;
+type Result<E, A> = Ok<A> | Error<E>;
 declare namespace Result {
     /**
      * Creates a successful Result with the given value.
@@ -133,15 +133,15 @@ declare namespace Result {
     /**
      * Creates a failed Result with the given error.
      */
-    const err: <E>(error: E) => Err<E>;
+    const error: <E>(e: E) => Error<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.
+     * Type guard that checks if an Result is Error.
      */
-    const isErr: <E, A>(data: Result<E, A>) => data is Err<E>;
+    const isError: <E, A>(data: Result<E, A>) => data is Error<E>;
     /**
      * Creates an Result from a function that may throw.
      * Catches any errors and transforms them using the onError function.
@@ -162,7 +162,7 @@ declare namespace 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")
+     * pipe(Result.error("error"), Result.map(n => n * 2)); // Error("error")
      * ```
      */
     const map: <E, A, B>(f: (a: A) => B) => (data: Result<E, A>) => Result<E, B>;
@@ -171,7 +171,7 @@ declare namespace Result {
      *
      * @example
      * ```ts
-     * pipe(Result.err("oops"), Result.mapError(e => e.toUpperCase())); // Err("OOPS")
+     * pipe(Result.error("oops"), Result.mapError(e => e.toUpperCase())); // Error("OOPS")
      * ```
      */
     const mapError: <E, F, A>(f: (e: E) => F) => (data: Result<E, A>) => Result<F, A>;
@@ -182,10 +182,10 @@ declare namespace Result {
      * @example
      * ```ts
      * const validatePositive = (n: number): Result<string, number> =>
-     *   n > 0 ? Result.ok(n) : Result.err("Must be positive");
+     *   n > 0 ? Result.ok(n) : Result.error("Must be positive");
      *
      * pipe(Result.ok(5), Result.chain(validatePositive)); // Ok(5)
-     * pipe(Result.ok(-1), Result.chain(validatePositive)); // Err("Must be positive")
+     * pipe(Result.ok(-1), Result.chain(validatePositive)); // Error("Must be positive")
      * ```
      */
     const chain: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Result<E, A>) => Result<E, B>;
@@ -230,8 +230,8 @@ declare namespace Result {
      * @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
+     * pipe(Result.error("error"), Result.getOrElse(() => 0)); // 0
+     * pipe(Result.error("error"), Result.getOrElse(() => null)); // null — typed as number | null
      * ```
      */
     const getOrElse: <E, A, B>(defaultValue: () => B) => (data: Result<E, A>) => A | B;
@@ -256,7 +256,7 @@ declare namespace Result {
      * @example
      * ```ts
      * pipe(
-     *   Result.err("not found"),
+     *   Result.error("not found"),
      *   Result.tapError(e => console.error("validation failed:", e)),
      *   Result.chain(save),
      * )
@@ -270,8 +270,8 @@ declare namespace Result {
      * @example
      * ```ts
      * pipe(5, Result.fromPredicate(n => n > 0, n => `${n} is not positive`));  // Ok(5)
-     * pipe(-1, Result.fromPredicate(n => n > 0, n => `${n} is not positive`)); // Err("-1 is not positive")
-     * pipe("", Result.fromPredicate(s => s.length > 0, () => "empty string")); // Err("empty string")
+     * pipe(-1, Result.fromPredicate(n => n > 0, n => `${n} is not positive`)); // Error("-1 is not positive")
+     * pipe("", Result.fromPredicate(s => s.length > 0, () => "empty string")); // Error("empty string")
      * ```
      */
     const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
@@ -281,10 +281,18 @@ declare namespace Result {
      */
     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.
+     * Recovers from an error unless the predicate `isBlocked` returns true for that error.
      * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Result.error(new Error("not found")),
+     *   Result.recoverUnless(e => e.message === "fatal", () => Result.ok(0))
+     * ); // Ok(0)
+     * ```
      */
-    const recoverUnless: <E, A, B>(blockedErr: E, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
+    const recoverUnless: <E, A, B>(isBlocked: (e: E) => boolean, fallback: () => Result<E, B>) => (data: Result<E, A>) => Result<E, A | B>;
     /**
      * Converts a Result to an Maybe.
      * Ok becomes Some, Err becomes None (the error is discarded).
@@ -292,7 +300,7 @@ declare namespace Result {
      * @example
      * ```ts
      * Result.toMaybe(Result.ok(42)); // Some(42)
-     * Result.toMaybe(Result.err("oops")); // None
+     * Result.toMaybe(Result.error("oops")); // None
      * ```
      */
     const toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
@@ -367,11 +375,6 @@ declare namespace Maybe {
      * Extracts the value from a Maybe, returning undefined if None.
      */
     const toUndefined: <A>(data: Maybe<A>) => A | undefined;
-    /**
-     * Creates a Maybe from a possibly undefined value.
-     * Returns None if undefined, Some otherwise.
-     */
-    const fromUndefined: <A>(value: A | undefined) => Maybe<A>;
     /**
      * Creates a Maybe from a predicate applied to a value.
      * Returns Some if the predicate passes, None otherwise.
@@ -411,7 +414,7 @@ declare namespace Maybe {
      * @example
      * ```ts
      * Maybe.fromResult(Result.ok(42)); // Some(42)
-     * Maybe.fromResult(Result.err("oops")); // None
+     * Maybe.fromResult(Result.error("oops")); // None
      * ```
      */
     const fromResult: <E, A>(data: Result<E, A>) => Maybe<A>;
@@ -703,10 +706,12 @@ declare namespace Task {
     const repeat: (options: {
         times: number;
         delay?: number;
-    }) => <A>(task: Task<A>) => Task<A[]>;
+    }) => <A>(task: Task<A>) => Task<readonly A[]>;
     /**
      * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
      * An optional delay (ms) can be inserted between runs.
+     * An optional `maxAttempts` cap stops the loop after N calls — the last value is returned
+     * regardless of whether the predicate was satisfied.
      *
      * @example
      * ```ts
@@ -719,6 +724,7 @@ declare namespace Task {
     const repeatUntil: <A>(options: {
         when: (a: A) => boolean;
         delay?: number;
+        maxAttempts?: number;
     }) => (task: Task<A>) => Task<A>;
     /**
      * Resolves with the value of the first Task to complete. All Tasks start
@@ -767,9 +773,12 @@ declare namespace Task {
      */
     const timeout: <E>(ms: number, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
     /**
-     * Creates a Task paired with an `abort` handle. When `abort()` is called the
-     * `AbortSignal` passed to the factory is fired, cancelling any in-flight
-     * operation (e.g. a `fetch`) immediately.
+     * Creates a Task paired with an `abort` handle. Calling `abort()` cancels the
+     * current in-flight call immediately. Unlike a one-shot abort, calling `task()`
+     * again after `abort()` starts a fresh call with a new signal.
+     *
+     * Each invocation of `task()` automatically cancels the previous in-flight call,
+     * making it safe to call repeatedly (e.g. on user input) without leaking promises.
      *
      * If an outer signal is also present (passed at the call site), aborting it
      * propagates into the internal controller.
@@ -788,6 +797,19 @@ declare namespace Task {
         task: Task<A>;
         abort: () => void;
     };
+    /**
+     * Executes a task with an optional signal. Use as a terminal step in a `pipe` chain.
+     *
+     * @example
+     * ```ts
+     * const name = await pipe(
+     *     fetchConfig,
+     *     Task.map(config => config.name),
+     *     Task.run(),
+     * );
+     * ```
+     */
+    const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
 }
 
-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 WithTimeout as f, type WithMinInterval as g, type WithCooldown as h, type WithConcurrency as i, type WithSize as j, type WithMs as k, type WithN as l, type WithErrors as m, type WithFirst as n, type WithSecond as o };
+export { Deferred as D, type Error 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 WithTimeout as f, type WithMinInterval as g, type WithCooldown as h, type WithConcurrency as i, type WithSize as j, type WithMs as k, type WithN as l, type WithErrors as m, type WithFirst as n, type WithSecond as o };