@nlozgachev/pipelined 0.19.0 → 0.20.0

package/README.md

@@ -10,15 +10,83 @@ Opinionated functional abstractions for TypeScript.
 npm add @nlozgachev/pipelined
 ```
 
-## What is this?
+## Possibly maybe
 
-A toolkit for expressing uncertainty precisely. Instead of `T | null`, `try/catch`, and loading
-state flag soup, you get types that name every possible state and make invalid ones unrepresentable.
-Each type comes with a consistent set of operations — `map`, `chain`, `match`, `getOrElse` — that
-compose with `pipe` and `flow`.
+**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.
+
+## Documentation
+
+Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
+
+## Example
+
+The standard approach to "fetch with retry and timeout":
+
+```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;
+}
+```
+
+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.
+
+With **pipelined**:
+
+```ts
+import { TaskResult } from "@nlozgachev/pipelined/core";
+import { pipe } from "@nlozgachev/pipelined/composition";
+
+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 }),
+  );
+```
+
+`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.
+
+```ts
+const controller = new AbortController();
+const result = await fetchUser("42")(controller.signal);
+
+if (Result.isOk(result)) {
+  render(result.value); // User
+} else {
+  showError(result.error.message); // ApiError, not unknown
+}
+```
 
 ## 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.
+
 ### pipelined/core
 
 - **`Maybe<A>`** — a value that may not exist; propagates absence without null checks.
@@ -45,9 +113,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`.
 - **`Num`** — number utilities: `range`, `clamp`, `between`, safe `parse`, and curried arithmetic.
 - **`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.
+
 ### pipelined/types
 
 - **`Brand<K, T>`** — nominal typing at compile time, zero runtime cost.
@@ -58,33 +133,8 @@ Everyday utilities for built-in JS types.
 - **`pipe`**, **`flow`**, **`compose`** — function composition.
 - **`curry`** / **`uncurry`**, **`tap`**, **`memoize`**, and other function utilities.
 
-## Example
 
-```ts
-import { Maybe, Result } from "@nlozgachev/pipelined/core";
-import { pipe } from "@nlozgachev/pipelined/composition";
-
-// Chain nullable lookups without nested null checks
-const city = pipe(
-  getUser(userId), // User | null
-  Maybe.fromNullable, // Maybe<User>
-  Maybe.chain((u) => Maybe.fromNullable(u.address)), // Maybe<Address>
-  Maybe.chain((a) => Maybe.fromNullable(a.city)), // Maybe<string>
-  Maybe.map((c) => c.toUpperCase()), // Maybe<string>
-  Maybe.getOrElse("UNKNOWN"), // string
-);
-
-// Parse input and look up a record — both steps can fail
-const record = pipe(
-  parseId(rawInput), // Result<ParseError, number>
-  Result.chain((id) => db.find(id)), // Result<ParseError | NotFoundError, Record>
-  Result.map((r) => r.name), // Result<ParseError | NotFoundError, string>
-);
-```
 
-## Documentation
-
-Full guides and API reference at **[pipelined.lozgachev.dev](https://pipelined.lozgachev.dev)**.
 
 ## License
 

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

@@ -465,6 +465,10 @@ declare namespace Maybe {
  * - **Infallible** — it never rejects. If failure is possible, encode it in the
  *   return type using `TaskResult<E, A>` instead.
  *
+ * An optional `AbortSignal` can be passed at the call site. Combinators like
+ * `retry`, `pollUntil`, and `timeout` thread it automatically to every inner
+ * operation. Existing tasks that ignore the signal continue to work unchanged.
+ *
  * Calling a Task returns a `Deferred<A>` — a one-shot async value that supports
  * `await` but has no `.catch()`, `.finally()`, or chainable `.then()`.
  *
@@ -495,7 +499,7 @@ declare namespace Maybe {
  * const result = await formatted();
  * ```
  */
-type Task<A> = () => Deferred<A>;
+type Task<A> = (signal?: AbortSignal) => Deferred<A>;
 declare namespace Task {
     /**
      * Creates a Task that immediately resolves to the given value.
@@ -509,13 +513,14 @@ declare namespace Task {
     const resolve: <A>(value: A) => Task<A>;
     /**
      * Creates a Task from a function that returns a Promise.
+     * The factory optionally receives an `AbortSignal` forwarded from the call site.
      *
      * @example
      * ```ts
      * const getTimestamp = Task.from(() => Promise.resolve(Date.now()));
      * ```
      */
-    const from: <A>(f: () => Promise<A>) => Task<A>;
+    const from: <A>(f: (signal?: AbortSignal) => Promise<A>) => Task<A>;
     /**
      * Transforms the value inside a Task.
      *
@@ -660,7 +665,9 @@ 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.
+     * Task does not complete within the given time. The inner Task receives an
+     * `AbortSignal` that fires when the deadline passes, so operations like `fetch`
+     * that accept a signal are cancelled rather than left dangling.
      *
      * @example
      * ```ts
@@ -672,6 +679,28 @@ 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.
+     *
+     * If an outer signal is also present (passed at the call site), aborting it
+     * propagates into the internal controller.
+     *
+     * @example
+     * ```ts
+     * const { task: poll, abort } = Task.abortable(
+     *   (signal) => waitForEvent(bus, "ready", { signal }),
+     * );
+     *
+     * onUnmount(abort);
+     * await poll();
+     * ```
+     */
+    const abortable: <A>(factory: (signal: AbortSignal) => Promise<A>) => {
+        task: Task<A>;
+        abort: () => void;
+    };
 }
 
 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 };

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

@@ -465,6 +465,10 @@ declare namespace Maybe {
  * - **Infallible** — it never rejects. If failure is possible, encode it in the
  *   return type using `TaskResult<E, A>` instead.
  *
+ * An optional `AbortSignal` can be passed at the call site. Combinators like
+ * `retry`, `pollUntil`, and `timeout` thread it automatically to every inner
+ * operation. Existing tasks that ignore the signal continue to work unchanged.
+ *
  * Calling a Task returns a `Deferred<A>` — a one-shot async value that supports
  * `await` but has no `.catch()`, `.finally()`, or chainable `.then()`.
  *
@@ -495,7 +499,7 @@ declare namespace Maybe {
  * const result = await formatted();
  * ```
  */
-type Task<A> = () => Deferred<A>;
+type Task<A> = (signal?: AbortSignal) => Deferred<A>;
 declare namespace Task {
     /**
      * Creates a Task that immediately resolves to the given value.
@@ -509,13 +513,14 @@ declare namespace Task {
     const resolve: <A>(value: A) => Task<A>;
     /**
      * Creates a Task from a function that returns a Promise.
+     * The factory optionally receives an `AbortSignal` forwarded from the call site.
      *
      * @example
      * ```ts
      * const getTimestamp = Task.from(() => Promise.resolve(Date.now()));
      * ```
      */
-    const from: <A>(f: () => Promise<A>) => Task<A>;
+    const from: <A>(f: (signal?: AbortSignal) => Promise<A>) => Task<A>;
     /**
      * Transforms the value inside a Task.
      *
@@ -660,7 +665,9 @@ 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.
+     * Task does not complete within the given time. The inner Task receives an
+     * `AbortSignal` that fires when the deadline passes, so operations like `fetch`
+     * that accept a signal are cancelled rather than left dangling.
      *
      * @example
      * ```ts
@@ -672,6 +679,28 @@ 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.
+     *
+     * If an outer signal is also present (passed at the call site), aborting it
+     * propagates into the internal controller.
+     *
+     * @example
+     * ```ts
+     * const { task: poll, abort } = Task.abortable(
+     *   (signal) => waitForEvent(bus, "ready", { signal }),
+     * );
+     *
+     * onUnmount(abort);
+     * await poll();
+     * ```
+     */
+    const abortable: <A>(factory: (signal: AbortSignal) => Promise<A>) => {
+        task: Task<A>;
+        abort: () => void;
+    };
 }
 
 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 };

package/dist/{chunk-UWGFO7BH.mjs → chunk-7COGDULU.mjs}

@@ -3,7 +3,7 @@ import {
   Maybe,
   Result,
   Task
-} from "./chunk-EAR4TIGH.mjs";
+} from "./chunk-RUDOUVQR.mjs";
 
 // src/Core/Lens.ts
 var Lens;
@@ -312,12 +312,23 @@ var TaskMaybe;
 })(TaskMaybe || (TaskMaybe = {}));
 
 // src/Core/TaskResult.ts
+var cancellableWait = (ms, signal) => {
+  if (ms <= 0) return Promise.resolve();
+  if (!signal) return new Promise((r) => setTimeout(r, ms));
+  return new Promise((resolve) => {
+    const id = setTimeout(resolve, ms);
+    signal.addEventListener("abort", () => {
+      clearTimeout(id);
+      resolve();
+    }, { once: true });
+  });
+};
 var TaskResult;
 ((TaskResult2) => {
   TaskResult2.ok = (value) => Task.resolve(Result.ok(value));
   TaskResult2.err = (error) => Task.resolve(Result.err(error));
   TaskResult2.tryCatch = (f, onError) => Task.from(
-    () => f().then(Result.ok).catch((e) => Result.err(onError(e)))
+    (signal) => f(signal).then(Result.ok).catch((e) => Result.err(onError(e)))
   );
   TaskResult2.map = (f) => (data) => Task.map(Result.map(f))(data);
   TaskResult2.mapError = (f) => (data) => Task.map(Result.mapError(f))(data);
@@ -331,43 +342,75 @@ var TaskResult;
   )(data);
   TaskResult2.getOrElse = (defaultValue) => (data) => Task.map(Result.getOrElse(defaultValue))(data);
   TaskResult2.tap = (f) => (data) => Task.map(Result.tap(f))(data);
-  TaskResult2.retry = (options) => (data) => Task.from(() => {
+  TaskResult2.retry = (options) => (data) => Task.from((signal) => {
     const { attempts, backoff, when: shouldRetry } = options;
     const getDelay = (n) => backoff === void 0 ? 0 : typeof backoff === "function" ? backoff(n) : backoff;
-    const run = (left) => Deferred.toPromise(data()).then((result) => {
+    const run = (left) => Deferred.toPromise(data(signal)).then((result) => {
       if (Result.isOk(result)) return result;
       if (left <= 1) return result;
       if (shouldRetry !== void 0 && !shouldRetry(result.error)) {
         return result;
       }
+      if (signal?.aborted) return result;
       const ms = getDelay(attempts - left + 1);
-      return (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve()).then(() => run(left - 1));
+      return cancellableWait(ms, signal).then(() => {
+        if (signal?.aborted) return result;
+        return run(left - 1);
+      });
     });
     return run(attempts);
   });
-  TaskResult2.pollUntil = (options) => (task) => Task.from(() => {
+  TaskResult2.pollUntil = (options) => (task) => Task.from((signal) => {
     const { when: predicate, delay } = options;
     const getDelay = (attempt) => delay === void 0 ? 0 : typeof delay === "function" ? delay(attempt) : delay;
-    const run = (attempt) => Deferred.toPromise(task()).then((result) => {
+    const run = (attempt) => Deferred.toPromise(task(signal)).then((result) => {
       if (Result.isErr(result)) return result;
       if (predicate(result.value)) return result;
+      if (signal?.aborted) return result;
       const ms = getDelay(attempt);
-      return (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve()).then(() => run(attempt + 1));
+      return cancellableWait(ms, signal).then(() => {
+        if (signal?.aborted) return result;
+        return run(attempt + 1);
+      });
     });
     return run(1);
   });
-  TaskResult2.timeout = (ms, onTimeout) => (data) => Task.from(() => {
+  TaskResult2.timeout = (ms, onTimeout) => (data) => Task.from((outerSignal) => {
+    const controller = new AbortController();
+    const onOuterAbort = () => controller.abort();
+    outerSignal?.addEventListener("abort", onOuterAbort, { once: true });
     let timerId;
     return Promise.race([
-      Deferred.toPromise(data()).then((result) => {
+      Deferred.toPromise(data(controller.signal)).then((result) => {
         clearTimeout(timerId);
+        outerSignal?.removeEventListener("abort", onOuterAbort);
         return result;
       }),
       new Promise((resolve) => {
-        timerId = setTimeout(() => resolve(Result.err(onTimeout())), ms);
+        timerId = setTimeout(() => {
+          controller.abort();
+          outerSignal?.removeEventListener("abort", onOuterAbort);
+          resolve(Result.err(onTimeout()));
+        }, ms);
       })
     ]);
   });
+  TaskResult2.abortable = (factory, onError) => {
+    const controller = new AbortController();
+    const task = (outerSignal) => {
+      if (outerSignal) {
+        if (outerSignal.aborted) {
+          controller.abort(outerSignal.reason);
+        } else {
+          outerSignal.addEventListener("abort", () => controller.abort(outerSignal.reason), { once: true });
+        }
+      }
+      return Deferred.fromPromise(
+        factory(controller.signal).then(Result.ok).catch((e) => Result.err(onError(e)))
+      );
+    };
+    return { task, abort: () => controller.abort() };
+  };
 })(TaskResult || (TaskResult = {}));
 
 // src/Core/Validation.ts

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

@@ -3,7 +3,7 @@ import {
   Maybe,
   Result,
   Task
-} from "./chunk-EAR4TIGH.mjs";
+} from "./chunk-RUDOUVQR.mjs";
 import {
   isNonEmptyList
 } from "./chunk-DBIC62UV.mjs";

package/dist/{chunk-EAR4TIGH.mjs → chunk-RUDOUVQR.mjs}

@@ -69,77 +69,99 @@ var Result;
 })(Result || (Result = {}));
 
 // src/Core/Task.ts
-var toPromise = (task) => Deferred.toPromise(task());
+var toPromise = (task, signal) => Deferred.toPromise(task(signal));
 var Task;
 ((Task2) => {
   Task2.resolve = (value) => () => Deferred.fromPromise(Promise.resolve(value));
-  Task2.from = (f) => () => Deferred.fromPromise(f());
-  Task2.map = (f) => (data) => (0, Task2.from)(() => toPromise(data).then(f));
-  Task2.chain = (f) => (data) => (0, Task2.from)(() => toPromise(data).then((a) => toPromise(f(a))));
+  Task2.from = (f) => (signal) => Deferred.fromPromise(f(signal));
+  Task2.map = (f) => (data) => (0, Task2.from)((signal) => toPromise(data, signal).then(f));
+  Task2.chain = (f) => (data) => (0, Task2.from)((signal) => toPromise(data, signal).then((a) => toPromise(f(a), signal)));
   Task2.ap = (arg) => (data) => (0, Task2.from)(
-    () => Promise.all([
-      toPromise(data),
-      toPromise(arg)
+    (signal) => Promise.all([
+      toPromise(data, signal),
+      toPromise(arg, signal)
     ]).then(([f, a]) => f(a))
   );
   Task2.tap = (f) => (data) => (0, Task2.from)(
-    () => toPromise(data).then((a) => {
+    (signal) => toPromise(data, signal).then((a) => {
       f(a);
       return a;
     })
   );
   Task2.all = (tasks) => (0, Task2.from)(
-    () => Promise.all(tasks.map((t) => toPromise(t)))
+    (signal) => Promise.all(tasks.map((t) => toPromise(t, signal)))
   );
   Task2.delay = (ms) => (data) => (0, Task2.from)(
-    () => new Promise(
+    (signal) => new Promise(
       (resolve2) => setTimeout(
-        () => toPromise(data).then(resolve2),
+        () => toPromise(data, signal).then(resolve2),
         ms
       )
     )
   );
-  Task2.repeat = (options) => (task) => (0, Task2.from)(() => {
+  Task2.repeat = (options) => (task) => (0, Task2.from)((signal) => {
     const { times, delay: ms } = options;
     if (times <= 0) return Promise.resolve([]);
     const results = [];
     const wait = () => ms !== void 0 && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
-    const run = (left) => toPromise(task).then((a) => {
+    const run = (left) => toPromise(task, signal).then((a) => {
       results.push(a);
       if (left <= 1) return results;
       return wait().then(() => run(left - 1));
     });
     return run(times);
   });
-  Task2.repeatUntil = (options) => (task) => (0, Task2.from)(() => {
+  Task2.repeatUntil = (options) => (task) => (0, Task2.from)((signal) => {
     const { when: predicate, delay: ms } = options;
     const wait = () => ms !== void 0 && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
-    const run = () => toPromise(task).then((a) => {
+    const run = () => toPromise(task, signal).then((a) => {
       if (predicate(a)) return a;
       return wait().then(run);
     });
     return run();
   });
-  Task2.race = (tasks) => (0, Task2.from)(() => Promise.race(tasks.map(toPromise)));
-  Task2.sequential = (tasks) => (0, Task2.from)(async () => {
+  Task2.race = (tasks) => (0, Task2.from)((signal) => Promise.race(tasks.map((t) => toPromise(t, signal))));
+  Task2.sequential = (tasks) => (0, Task2.from)(async (signal) => {
     const results = [];
     for (const task of tasks) {
-      results.push(await toPromise(task));
+      results.push(await toPromise(task, signal));
     }
     return results;
   });
-  Task2.timeout = (ms, onTimeout) => (task) => (0, Task2.from)(() => {
+  Task2.timeout = (ms, onTimeout) => (task) => (0, Task2.from)((outerSignal) => {
+    const controller = new AbortController();
+    const onOuterAbort = () => controller.abort();
+    outerSignal?.addEventListener("abort", onOuterAbort, { once: true });
     let timerId;
     return Promise.race([
-      toPromise(task).then((a) => {
+      toPromise(task, controller.signal).then((a) => {
         clearTimeout(timerId);
+        outerSignal?.removeEventListener("abort", onOuterAbort);
         return Result.ok(a);
       }),
       new Promise((resolve2) => {
-        timerId = setTimeout(() => resolve2(Result.err(onTimeout())), ms);
+        timerId = setTimeout(() => {
+          controller.abort();
+          outerSignal?.removeEventListener("abort", onOuterAbort);
+          resolve2(Result.err(onTimeout()));
+        }, ms);
       })
     ]);
   });
+  Task2.abortable = (factory) => {
+    const controller = new AbortController();
+    const task = (outerSignal) => {
+      if (outerSignal) {
+        if (outerSignal.aborted) {
+          controller.abort(outerSignal.reason);
+        } else {
+          outerSignal.addEventListener("abort", () => controller.abort(outerSignal.reason), { once: true });
+        }
+      }
+      return Deferred.fromPromise(factory(controller.signal));
+    };
+    return { task, abort: () => controller.abort() };
+  };
 })(Task || (Task = {}));
 
 export {

package/dist/core.d.mts

@@ -1,5 +1,5 @@
-import { M as Maybe, W as WithValue, a as WithLog, R as Result, b as WithKind, c as WithError, T as Task, d as WithErrors, e as WithFirst, f as WithSecond } from './Task-DBW4nOZR.mjs';
-export { D as Deferred, E as Err, N as None, O as Ok, S as Some } from './Task-DBW4nOZR.mjs';
+import { M as Maybe, W as WithValue, a as WithLog, R as Result, b as WithKind, c as WithError, T as Task, d as WithErrors, e as WithFirst, f as WithSecond } from './Task-JOnNAaPq.mjs';
+export { D as Deferred, E as Err, N as None, O as Ok, S as Some } from './Task-JOnNAaPq.mjs';
 import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.mjs';
 
 /** Keys of T for which undefined is assignable (i.e. optional fields). */
@@ -1053,7 +1053,7 @@ declare namespace RemoteData {
  * ```ts
  * const fetchUser = (id: string): TaskResult<Error, User> =>
  *   TaskResult.tryCatch(
- *     () => fetch(`/users/${id}`).then(r => r.json()),
+ *     (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
  *     (e) => new Error(`Failed to fetch user: ${e}`)
  *   );
  * ```
@@ -1071,17 +1071,18 @@ declare namespace TaskResult {
     /**
      * Creates a TaskResult from a function that may throw.
      * Catches any errors and transforms them using the onError function.
+     * The factory optionally receives an `AbortSignal` forwarded from the call site.
      *
      * @example
      * ```ts
-     * const parseJson = (s: string): TaskResult<string, unknown> =>
+     * const fetchUser = (id: string): TaskResult<string, User> =>
      *   TaskResult.tryCatch(
-     *     async () => JSON.parse(s),
-     *     (e) => `Parse error: ${e}`
+     *     (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
+     *     String
      *   );
      * ```
      */
-    const tryCatch: <E, A>(f: () => Promise<A>, onError: (e: unknown) => E) => TaskResult<E, A>;
+    const tryCatch: <E, A>(f: (signal?: AbortSignal) => Promise<A>, onError: (e: unknown) => E) => TaskResult<E, A>;
     /**
      * Transforms the success value inside a TaskResult.
      */
@@ -1123,6 +1124,8 @@ declare namespace TaskResult {
     const tap: <E, A>(f: (a: A) => void) => (data: TaskResult<E, A>) => TaskResult<E, A>;
     /**
      * Re-runs a TaskResult on `Err` with configurable attempts, backoff, and retry condition.
+     * An `AbortSignal` passed at the call site is forwarded to each attempt; the loop also
+     * checks the signal before starting a new attempt so cancellation stops the loop promptly.
      *
      * @param options.attempts - Total number of attempts (1 = no retry, 3 = up to 3 tries)
      * @param options.backoff - Fixed delay in ms, or a function `(attempt) => ms` for computed delay
@@ -1151,6 +1154,8 @@ declare namespace TaskResult {
     /**
      * Polls a TaskResult repeatedly until the success value satisfies a predicate.
      * Stops immediately and returns `Err` if the task fails.
+     * An `AbortSignal` passed at the call site is forwarded to each attempt; the loop
+     * also checks the signal before starting a new poll so cancellation stops promptly.
      *
      * `delay` accepts a fixed number of milliseconds or a function `(attempt) => ms`
      * for a computed delay — useful for starting fast and slowing down over time.
@@ -1158,7 +1163,10 @@ declare namespace TaskResult {
      * @example
      * ```ts
      * const checkJob = (id: string): TaskResult<string, { status: "pending" | "done" }> =>
-     *   TaskResult.tryCatch(() => fetch(`/jobs/${id}`).then(r => r.json()), String);
+     *   TaskResult.tryCatch(
+     *     (signal) => fetch(`/jobs/${id}`, { signal }).then(r => r.json()),
+     *     String
+     *   );
      *
      * // Fixed delay: poll every 2s
      * pipe(
@@ -1179,7 +1187,8 @@ declare namespace TaskResult {
     }) => <E>(task: TaskResult<E, A>) => TaskResult<E, A>;
     /**
      * Fails a TaskResult with a typed error if it does not resolve within the given time.
-     * Uses `Promise.race` — the underlying operation keeps running after the timeout fires.
+     * The inner task receives an `AbortSignal` that fires when the deadline passes —
+     * operations like `fetch` that accept a signal are cancelled rather than left dangling.
      *
      * @example
      * ```ts
@@ -1190,6 +1199,31 @@ declare namespace TaskResult {
      * ```
      */
     const timeout: <E>(ms: number, onTimeout: () => E) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
+    /**
+     * Creates a TaskResult paired with an `abort` handle. When `abort()` is called the
+     * `AbortSignal` passed to the factory is fired, cancelling any in-flight operation.
+     * The abort error is transformed by `onError` into a typed `Err`.
+     *
+     * If an outer signal is also present (passed at the call site), aborting it
+     * propagates into the internal controller.
+     *
+     * @example
+     * ```ts
+     * const { task: req, abort } = TaskResult.abortable(
+     *   (signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
+     *   String,
+     * );
+     *
+     * const result = pipe(req, TaskResult.retry({ attempts: 3 }));
+     *
+     * onCancel(abort);
+     * await result();
+     * ```
+     */
+    const abortable: <E, A>(factory: (signal: AbortSignal) => Promise<A>, onError: (e: unknown) => E) => {
+        task: TaskResult<E, A>;
+        abort: () => void;
+    };
 }
 
 /**