@nlozgachev/pipelined 0.33.0 → 0.35.0

package/README.md

@@ -1,6 +1,8 @@
 # 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)
+[![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.
 
@@ -12,11 +14,11 @@ 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 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.
+**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 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
 
@@ -59,7 +61,7 @@ values — the error type is part of the signature, not a runtime surprise.
 import { pipe } from "@nlozgachev/pipelined/composition";
 import { Result, TaskResult } from "@nlozgachev/pipelined/core";
 
-type ApiError = { status: number; message: string; };
+type ApiError = { status: number; message: string };
 
 const fetchUser = (id: string): TaskResult<ApiError, User> =>
   TaskResult.tryCatch(
@@ -73,7 +75,8 @@ const fetchUser = (id: string): TaskResult<ApiError, User> =>
 
 const fetchPosts = (userId: string): TaskResult<ApiError, Post[]> =>
   TaskResult.tryCatch(
-    (signal) => fetch(`/users/${userId}/posts`, { signal }).then((r) => r.json()),
+    (signal) =>
+      fetch(`/users/${userId}/posts`, { signal }).then((r) => r.json()),
     (e) => e as ApiError,
   );
 
@@ -115,13 +118,17 @@ 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; };
+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 })),
+    Maybe.map((price) => ({
+      name: Str.trim(raw.name),
+      price,
+      category: raw.category,
+    })),
   );
 
 const cheapestByCategory = (items: RawItem[]) =>
@@ -135,8 +142,9 @@ const cheapestByCategory = (items: RawItem[]) =>
 ```
 
 `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.
+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
 
@@ -144,8 +152,8 @@ A careful, production-minded attempt at "fetch with retry, timeout, and cancella
 
 ```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,
@@ -177,13 +185,14 @@ async function fetchUser(
 ```
 
 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.
+distinguished from external cancellation by checking `signal?.aborted`. The retry is recursive to
+thread the attempt count.
 
 With **pipelined**:
 
 ```ts
 import { Op } from "@nlozgachev/pipelined/core";
+import { Duration } from "@nlozgachev/pipelined/types";
 
 const fetchUser = Op.interpret(
   Op.create(
@@ -193,8 +202,11 @@ const fetchUser = Op.interpret(
   ),
   {
     strategy: "restartable",
-    retry: { attempts: 3, backoff: (n) => n * 1000 },
-    timeout: { ms: 5000, onTimeout: () => new ApiError("request timed out") },
+    retry: { attempts: 3, backoff: (n) => Duration.seconds(n) },
+    timeout: {
+      duration: Duration.seconds(5),
+      onTimeout: () => new ApiError("request timed out"),
+    },
   },
 );
 ```
@@ -220,7 +232,7 @@ fetchUser.abort();
 
 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?_
+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.
 
@@ -228,23 +240,26 @@ different answer to the same question: _what happens to the previous call when a
 
 ```ts
 import { Op } from "@nlozgachev/pipelined/core";
+import { Duration } from "@nlozgachev/pipelined/types";
 
 const searchOp = Op.create(
   (signal) => (query: string) =>
-    fetch(`/search?q=${query}`, { signal }).then((r) => r.json() as Promise<SearchResult[]>),
+    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 },
+  retry: { attempts: 2, backoff: Duration.milliseconds(300) },
 });
 
 search.subscribe((state) => {
   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);
+  if (Op.isErr(state)) showError(state.error);
 });
 
 input.addEventListener("input", (e) => search.run(e.currentTarget.value));
@@ -255,7 +270,9 @@ input.addEventListener("input", (e) => search.run(e.currentTarget.value));
 ```ts
 const submitOp = Op.create(
   (signal) => (data: FormData) =>
-    fetch("/orders", { method: "POST", body: data, signal }).then((r) => r.json()),
+    fetch("/orders", { method: "POST", body: data, signal }).then((r) =>
+      r.json()
+    ),
   (e) => new ApiError(e),
 );
 
@@ -266,7 +283,7 @@ const submit = Op.interpret(submitOp, {
 submit.subscribe((state) => {
   submitButton.disabled = Op.isPending(state);
   if (Op.isOk(state)) showConfirmation(state.value);
-  if (Op.isError(state)) showError(state.error);
+  if (Op.isErr(state)) showError(state.error);
 });
 
 form.addEventListener("submit", (e) => {
@@ -275,32 +292,48 @@ form.addEventListener("submit", (e) => {
 });
 ```
 
-`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.
+`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?
 
-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.
+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.
-- **`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`.
+- **`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.
+- **`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.
-- **`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.
+- **`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.
+- **`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`.
 
@@ -311,14 +344,16 @@ Everyday utilities for built-in JS types.
 - **`Arr`** — array utilities, data-last, returning `Maybe` instead of `undefined`.
 - **`Rec`** — record/object utilities, data-last, with `Maybe`-returning key lookup.
 - **`Dict`** — `ReadonlyMap<K, V>` utilities: `lookup`, `groupBy`, `upsert`, set operations.
-- **`Uniq`** — `ReadonlySet<A>` utilities: `insert`, `remove`, `union`, `intersection`, `difference`.
+- **`Uniq`** — `ReadonlySet<A>` utilities: `insert`, `remove`, `union`, `intersection`,
+  `difference`.
 - **`Num`** — number utilities: `range`, `clamp`, `between`, safe `parse`, and curried arithmetic.
-- **`Str`** — string utilities: `split`, `trim`, `words`, `lines`, and safe `parse.int` / `parse.float`.
+- **`Str`** — string utilities: `split`, `trim`, `words`, `lines`, and safe `parse.int` /
+  `parse.float`.
 
 Every utility is benchmarked against its native equivalent. The data-last currying adds a function
 call; that is the expected cost of composability. Operations that exceeded a reasonable overhead
-have custom implementations that in several cases run faster than the native method they replace. See the
-[benchmarks page](https://pipelined.lozgachev.dev/appendix/benchmarks) for the methodology.
+have custom implementations that in several cases run faster than the native method they replace.
+See the [benchmarks page](https://pipelined.lozgachev.dev/appendix/benchmarks) for the methodology.
 
 ### pipelined/types
 

package/dist/{Task-5na0QzS4.d.mts → Task-DXsuurnc.d.mts}

@@ -24,19 +24,19 @@ type WithLog<T> = {
 /** Retry policy for `Op.interpret`. */
 type RetryOptions<E> = {
     readonly attempts: number;
-    readonly backoff?: number | ((attempt: number) => 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 ms: number;
+    readonly duration: Duration;
     readonly onTimeout: () => E;
 };
 type WithTimeout<E> = {
     readonly timeout?: TimeoutOptions<E>;
 };
-type WithMs = {
-    readonly ms: number;
+type WithDuration = {
+    readonly duration: Duration;
 };
 type WithN = {
     readonly n: number;
@@ -48,22 +48,22 @@ type WithSize = {
     readonly size?: number;
 };
 type WithCooldown = {
-    readonly cooldown?: number;
+    readonly cooldown?: Duration;
 };
 type WithMinInterval = {
-    readonly minInterval?: number;
+    readonly minInterval?: Duration;
 };
 
 type Ok<A> = WithKind<"Ok"> & WithValue<A>;
-type Error<E> = WithKind<"Error"> & WithError<E>;
+type Err<E> = WithKind<"Err"> & WithError<E>;
 /**
- * Result represents a value that can be one of two types: a success (Ok) or a failure (Error).
+ * 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.error("Division by zero") : Result.ok(a / b);
+ *   b === 0 ? Result.err("Division by zero") : Result.ok(a / b);
  *
  * pipe(
  *   divide(10, 2),
@@ -72,7 +72,7 @@ type Error<E> = WithKind<"Error"> & WithError<E>;
  * ); // 10
  * ```
  */
-type Result<E, A> = Ok<A> | Error<E>;
+type Result<E, A> = Ok<A> | Err<E>;
 declare namespace Result {
     /**
      * Creates a successful Result with the given value.
@@ -81,17 +81,17 @@ declare namespace Result {
     /**
      * Creates a failed Result with the given error.
      */
-    const error: <E>(e: E) => Error<E>;
+    const err: <E>(e: E) => Err<E>;
     /**
-     * Type guard that checks if an Result is Ok.
+     * Type guard that checks if a Result is Ok.
      */
     const isOk: <E, A>(data: Result<E, A>) => data is Ok<A>;
     /**
-     * Type guard that checks if an Result is Error.
+     * Type guard that checks if a Result is Err.
      */
-    const isError: <E, A>(data: Result<E, A>) => data is Error<E>;
+    const isErr: <E, A>(data: Result<E, A>) => data is Err<E>;
     /**
-     * Creates an Result from a function that may throw.
+     * Creates a Result from a function that may throw.
      * Catches any errors and transforms them using the onError function.
      *
      * @example
@@ -105,21 +105,21 @@ declare namespace Result {
      */
     const tryCatch: <E, A>(f: () => A, onError: (e: unknown) => E) => Result<E, A>;
     /**
-     * Transforms the success value inside an Result.
+     * Transforms the success value inside a Result.
      *
      * @example
      * ```ts
      * pipe(Result.ok(5), Result.map(n => n * 2)); // Ok(10)
-     * pipe(Result.error("error"), Result.map(n => n * 2)); // Error("error")
+     * 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.
+     * Transforms the error value inside a Result.
      *
      * @example
      * ```ts
-     * pipe(Result.error("oops"), Result.mapError(e => e.toUpperCase())); // Error("OOPS")
+     * 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>;
@@ -130,15 +130,15 @@ declare namespace Result {
      * @example
      * ```ts
      * const validatePositive = (n: number): Result<string, number> =>
-     *   n > 0 ? Result.ok(n) : Result.error("Must be positive");
+     *   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)); // Error("Must be positive")
+     * 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.
+     * Extracts the value from a Result by providing handlers for both cases.
      *
      * @example
      * ```ts
@@ -178,8 +178,8 @@ declare namespace Result {
      * @example
      * ```ts
      * pipe(Result.ok(5), Result.getOrElse(() => 0)); // 5
-     * pipe(Result.error("error"), Result.getOrElse(() => 0)); // 0
-     * pipe(Result.error("error"), Result.getOrElse(() => null)); // null — typed as number | null
+     * 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;
@@ -204,7 +204,7 @@ declare namespace Result {
      * @example
      * ```ts
      * pipe(
-     *   Result.error("not found"),
+     *   Result.err("not found"),
      *   Result.tapError(e => console.error("validation failed:", e)),
      *   Result.chain(save),
      * )
@@ -218,8 +218,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`)); // Error("-1 is not positive")
-     * pipe("", Result.fromPredicate(s => s.length > 0, () => "empty string")); // Error("empty string")
+     * 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")
      * ```
      */
     const fromPredicate: <E, A>(pred: (a: A) => boolean, onFalse: (a: A) => E) => (a: A) => Result<E, A>;
@@ -229,7 +229,7 @@ declare namespace Result {
      *
      * @example
      * ```ts
-     * pipe(null, Result.fromNullable(() => "is null")); // Error("is null")
+     * pipe(null, Result.fromNullable(() => "is null")); // Err("is null")
      * pipe(42, Result.fromNullable(() => "is null"));   // Ok(42)
      * ```
      */
@@ -240,7 +240,7 @@ declare namespace Result {
      *
      * @example
      * ```ts
-     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Error("is none")
+     * pipe(Maybe.none(), Result.fromMaybe(() => "is none")); // Err("is none")
      * pipe(Maybe.some(42), Result.fromMaybe(() => "is none")); // Ok(42)
      * ```
      */
@@ -257,7 +257,7 @@ declare namespace Result {
      * );
      *
      * safeParse('{"a":1}'); // Ok({ a: 1 })
-     * safeParse('invalid');  // Error(Error)
+     * safeParse('invalid');  // Err(Error)
      * ```
      */
     const fromThrowable: <Args extends readonly unknown[], A, E>(f: (...args: Args) => A, onError: (e: unknown) => E) => (...args: Args) => Result<E, A>;
@@ -273,25 +273,25 @@ declare namespace Result {
      * @example
      * ```ts
      * pipe(
-     *   Result.error(new Error("not found")),
+     *   Result.err(new Error("not found")),
      *   Result.recoverUnless(e => e.message === "fatal", () => Result.ok(0))
      * ); // Ok(0)
      * ```
      */
     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.
+     * Converts a Result to a Maybe.
      * Ok becomes Some, Err becomes None (the error is discarded).
      *
      * @example
      * ```ts
      * Result.toMaybe(Result.ok(42)); // Some(42)
-     * Result.toMaybe(Result.error("oops")); // None
+     * Result.toMaybe(Result.err("oops")); // None
      * ```
      */
     const toMaybe: <E, A>(data: Result<E, A>) => Maybe<A>;
     /**
-     * Applies a function wrapped in an Result to a value wrapped in an Result.
+     * Applies a function wrapped in a Result to a value wrapped in a Result.
      *
      * @example
      * ```ts
@@ -314,14 +314,13 @@ type None = WithKind<"None">;
  *
  * @example
  * ```ts
- * const findUser = (id: string): Maybe<User> =>
- *   users.has(id) ? Maybe.some(users.get(id)!) : Maybe.none();
+ * const user = { name: "Alice", email: Maybe.some("alice@example.com") };
  *
  * pipe(
- *   findUser("123"),
- *   Maybe.map(user => user.name),
- *   Maybe.getOrElse(() => "Unknown")
- * );
+ *   user.email,
+ *   Maybe.map(email => email.toUpperCase()),
+ *   Maybe.getOrElse(() => "NO EMAIL")
+ * ); // "ALICE@EXAMPLE.COM"
  * ```
  */
 type Maybe<T> = Some<T> | None;
@@ -376,7 +375,7 @@ declare namespace Maybe {
      */
     const fromPredicate: <A>(pred: (a: A) => boolean) => (a: A) => Maybe<A>;
     /**
-     * Converts an Maybe to a Result.
+     * Converts a Maybe to a Result.
      * Some becomes Ok, None becomes Err with the provided error.
      *
      * @example
@@ -394,13 +393,13 @@ declare namespace Maybe {
      */
     const toResult: <E>(onNone: () => E) => <A>(data: Maybe<A>) => Result<E, A>;
     /**
-     * Creates an Maybe from a Result.
+     * Creates a Maybe from a Result.
      * Ok becomes Some, Err becomes None (the error is discarded).
      *
      * @example
      * ```ts
      * Maybe.fromResult(Result.ok(42)); // Some(42)
-     * Maybe.fromResult(Result.error("oops")); // None
+     * Maybe.fromResult(Result.err("oops")); // None
      * ```
      */
     const fromResult: <E, A>(data: Result<E, A>) => Maybe<A>;
@@ -464,7 +463,7 @@ declare namespace Maybe {
         some: (a: A) => B;
     }) => (data: Maybe<A>) => B;
     /**
-     * Returns the value inside an Maybe, or a default value if None.
+     * Returns the value inside a Maybe, or a default value if None.
      * The default is a thunk `() => B` — evaluated only when the Maybe is None.
      * The default can be a different type, widening the result to `A | B`.
      *
@@ -882,7 +881,7 @@ declare namespace Task {
      */
     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 or duration.
+     * Delays the execution of a Task by the specified duration.
      * Useful for debouncing or rate limiting.
      *
      * @example
@@ -893,10 +892,10 @@ declare namespace Task {
      * )(); // Resolves after 1 second
      * ```
      */
-    const delay: (ms: number | Duration) => <A>(data: Task<A>) => Task<A>;
+    const delay: (duration: Duration) => <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 or Duration) can be inserted between runs.
+     * An optional delay duration can be inserted between runs.
      *
      * @example
      * ```ts
@@ -908,11 +907,11 @@ declare namespace Task {
      */
     const repeat: (options: {
         times: number;
-        delay?: number | Duration;
+        delay?: Duration;
     }) => <A>(task: Task<A>) => Task<readonly A[]>;
     /**
      * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
-     * An optional delay (ms or Duration) can be inserted between runs.
+     * An optional delay duration 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.
      *
@@ -926,7 +925,7 @@ declare namespace Task {
      */
     const repeatUntil: <A>(options: {
         when: (a: A) => boolean;
-        delay?: number | Duration;
+        delay?: Duration;
         maxAttempts?: number;
     }) => (task: Task<A>) => Task<A>;
     /**
@@ -973,8 +972,8 @@ declare namespace Task {
     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. The inner Task receives an
-     * `AbortSignal` that fires when the deadline passes, so operations like `fetch`
+     * Task does not complete within the given duration. The inner Task receives an
+     * `AbortSignal` that fires when the deadline passes, so asynchronous operations
      * that accept a signal are cancelled rather than left dangling.
      *
      * @example
@@ -986,7 +985,7 @@ declare namespace Task {
      * );
      * ```
      */
-    const timeout: <E>(ms: number | Duration, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
+    const timeout: <E>(duration: Duration, onTimeout: () => E) => <A>(task: Task<A>) => Task<Result<E, A>>;
     /**
      * Creates a Task paired with an `abort` handle. Calling `abort()` cancels the
      * current in-flight call immediately. Unlike a one-shot abort, calling `task()`
@@ -1018,7 +1017,7 @@ declare namespace Task {
      * @example
      * ```ts
      * const name = await pipe(
-     *     fetchConfig,
+     *     loadConfig,
      *     Task.map(config => config.name),
      *     Task.run(),
      * );
@@ -1027,4 +1026,4 @@ declare namespace Task {
     const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
 }
 
-export { Deferred as D, Equality 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 Error as a, Ordering as b, type WithLog as c, type WithKind as d, type WithError as e, type RetryOptions as f, type TimeoutOptions as g, type WithTimeout as h, type WithMinInterval as i, type WithCooldown as j, type WithConcurrency as k, type WithSize as l, type WithMs as m, type WithN as n, type WithErrors as o, type WithFirst as p, type WithSecond as q };
+export { Deferred as D, Equality 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 Err as a, Ordering as b, type WithLog as c, type WithKind as d, type WithError as e, type RetryOptions as f, type TimeoutOptions as g, type WithTimeout as h, type WithMinInterval as i, type WithCooldown as j, type WithConcurrency as k, type WithSize as l, type WithDuration as m, type WithN as n, type WithErrors as o, type WithFirst as p, type WithSecond as q };