@nlozgachev/pipelined 0.19.0 → 0.21.0

package/dist/core.d.ts

@@ -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-DUdIQm-Q.js';
-export { D as Deferred, E as Err, N as None, O as Ok, S as Some } from './Task-DUdIQm-Q.js';
+import { M as Maybe, W as WithValue, a as WithLog, D as Deferred, R as Result, b as WithKind, c as WithError, d as RetryOptions, e as TimeoutOptions, f as WithMs, g as WithTrailing, h as WithRetry, i as WithTimeout, j as WithLeading, k as WithMaxWait, l as WithN, m as WithOverflow, n as WithKey, o as WithPerKey, p as WithMinInterval, q as WithCooldown, r as WithMaxSize, s as WithDedupe, t as WithConcurrency, u as WithSize, T as Task, v as WithErrors, w as WithFirst, x as WithSecond } from './Task-GSGtQO1m.js';
+export { E as Err, N as None, O as Ok, S as Some } from './Task-GSGtQO1m.js';
 import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.js';
 
 /** Keys of T for which undefined is assignable (i.e. optional fields). */
@@ -399,6 +399,600 @@ declare namespace Logged {
     const run: <W, A>(data: Logged<W, A>) => readonly [A, ReadonlyArray<W>];
 }
 
+/**
+ * A reusable description of async work — decoupled from execution strategy and lifetime.
+ *
+ * Separate concerns:
+ * - **What** to do: encoded in the `Op` via `Op.create`
+ * - **How** to execute: chosen at `Op.interpret` time (restartable, exclusive, queue, etc.)
+ *
+ * An `Op` never runs on its own. It only executes when passed to `Op.interpret`, which
+ * attaches a concurrency strategy and returns a `Manager` that owns the execution.
+ *
+ * @example
+ * ```ts
+ * const fetchUser = Op.create(
+ *   (id: string, signal) => fetch(`/users/${id}`, { signal }).then(r => r.json()),
+ *   (e) => new ApiError(e),
+ * );
+ *
+ * const manager = Op.interpret(fetchUser, { strategy: "restartable" });
+ * manager.subscribe(state => {
+ *   if (state.kind === "Pending") showSpinner();
+ *   if (state.kind === "Ok")      render(state.value);
+ *   if (state.kind === "Err")     showError(state.error);
+ *   if (state.kind === "Nil")     resetUI();
+ * });
+ * manager.run(userId);
+ * ```
+ */
+type Op<I, E, A> = {
+    /**
+     * @internal — Used by `Op.interpret`. Do not call directly.
+     * Returns `null` when the operation was aborted (signal fired before factory resolved).
+     */
+    readonly _factory: (input: I, signal: AbortSignal) => Deferred<Result<E, A> | null>;
+};
+declare namespace Op {
+    /**
+     * The three terminal states of a completed async operation.
+     *
+     * - `Ok` — produced a value.
+     * - `Err` — produced a typed error.
+     * - `Nil` — completed without a value or error. The `reason` field says why:
+     *   `"aborted"` — `abort()` was called; `"dropped"` — a new `run()` was ignored
+     *   because the strategy was already busy; `"replaced"` — a newer `run()` took
+     *   over a call that was already running; `"evicted"` — a newer `run()` took over
+     *   a call that was waiting and had not yet started.
+     */
+    type Outcome<E, A> = Ok<A> | Err<E> | Nil;
+    /** A successful outcome with a value. */
+    type Ok<A> = WithKind<"Ok"> & WithValue<A>;
+    /** A failed outcome with a typed error. */
+    type Err<E> = WithKind<"Err"> & WithError<E>;
+    /**
+     * An outcome that produced nothing. `reason` identifies why:
+     * - `"aborted"` — `abort()` was called explicitly.
+     * - `"dropped"` — the invocation was ignored because the strategy was busy.
+     * - `"replaced"` — a newer invocation took over a call that was already running.
+     * - `"evicted"` — a newer invocation took a slot from a call that was waiting and
+     *   had not yet started (buffered slot, debounce timer, throttle trailing slot).
+     */
+    type Nil = WithKind<"Nil"> & {
+        readonly reason: NilReason;
+    };
+    /** The reason a `Nil` outcome was produced. */
+    type NilReason = "aborted" | "dropped" | "replaced" | "evicted";
+    /** A `Nil` produced by an explicit `abort()` call. */
+    type AbortedNil = Nil & {
+        readonly reason: "aborted";
+    };
+    /** A `Nil` produced when an invocation was silently ignored (strategy was busy). */
+    type DroppedNil = Nil & {
+        readonly reason: "dropped";
+    };
+    /** A `Nil` produced when a newer invocation took over a call that was already running. */
+    type ReplacedNil = Nil & {
+        readonly reason: "replaced";
+    };
+    /** A `Nil` produced when a newer invocation took a slot from a call that was waiting and had not yet started. */
+    type EvictedNil = Nil & {
+        readonly reason: "evicted";
+    };
+    /** The full set of states a manager can emit, including transient states. */
+    type State<E, A> = Idle | Pending | Queued | Retrying<E> | Outcome<E, A>;
+    /** The manager has not been run yet (initial state). */
+    type Idle = WithKind<"Idle">;
+    /** An operation is in-flight. */
+    type Pending = WithKind<"Pending">;
+    /** An operation is waiting in a queue. `position` is 0-indexed (0 = next to run). */
+    type Queued = WithKind<"Queued"> & {
+        readonly position: number;
+    };
+    /** A retry attempt is about to start. */
+    type Retrying<E> = WithKind<"Retrying"> & {
+        readonly attempt: number;
+        readonly lastError: E;
+        readonly nextRetryIn?: number;
+    };
+    /**
+     * A stateful execution manager. `run()` both emits state transitions through
+     * subscribers and returns a `Deferred` tied to that specific invocation.
+     * `S` is narrowed to only the states reachable for this manager's strategy
+     * and configuration.
+     *
+     * @example
+     * ```ts
+     * const manager = Op.interpret(saveConfig, { strategy: "exclusive" });
+     *
+     * manager.subscribe(state => {
+     *   if (state.kind === "Pending") lockForm();
+     *   if (state.kind === "Ok")      toast("Saved");
+     *   if (state.kind === "Err")     toast(`Error: ${state.error.message}`);
+     * });
+     *
+     * // Fire and subscribe (subscriber pattern)
+     * manager.run(formData);
+     *
+     * // Or await the specific invocation's outcome
+     * const result = await manager.run(formData);
+     * if (Op.isNil(result)) return; // dropped — another save was in-flight
+     * ```
+     */
+    type Manager<I, E, A, S extends State<E, A>> = {
+        /** The current state. Useful for synchronous reads (e.g., `useSyncExternalStore`). */
+        readonly state: S;
+        /**
+         * Submits an invocation. Emits state transitions via subscribers and returns a
+         * `Deferred` that resolves to the terminal outcome for this specific invocation.
+         * `Nil` means this invocation was not executed (dropped, replaced, or aborted).
+         */
+        run: (input: I) => Deferred<Exclude<S, Idle | Pending | Queued | Retrying<E>>>;
+        /**
+         * Cancels any in-flight operation and clears the queue.
+         * Every pending `run()` Deferred — including queued invocations — settles to `AbortedNil`.
+         * Resolution is asynchronous; no Deferred hangs indefinitely.
+         */
+        abort: () => void;
+        /**
+         * Registers a subscriber for state transitions. Returns an unsubscribe function.
+         * The callback fires immediately with the current state if the manager is not idle.
+         */
+        subscribe: (cb: (state: S) => void) => () => void;
+    };
+    /**
+     * A stateful manager that maintains independent per-key execution slots.
+     * Different keys run in parallel; the same key follows the `perKey` sub-strategy.
+     * `abort(key)` cancels a specific key; `abort()` cancels all.
+     * `state` is a map of each key's last known state — updated on every transition.
+     *
+     * @example
+     * ```ts
+     * const getUser = Op.interpret(fetchUser, {
+     *   strategy: "keyed",
+     *   key: (input) => input.id,
+     *   perKey: "exclusive",
+     * });
+     *
+     * getUser.subscribe((map) => {
+     *   for (const [id, state] of map) {
+     *     if (state.kind === "Pending") showSpinner(id);
+     *     if (state.kind === "Ok")      render(id, state.value);
+     *   }
+     * });
+     *
+     * getUser.run({ id: "user-1" }); // starts key "user-1"
+     * getUser.run({ id: "user-2" }); // starts key "user-2" in parallel
+     * ```
+     */
+    type KeyedManager<I, K, E, PerKeyS> = {
+        /** Current state map. Keys are present from first `run()` through their last terminal state. */
+        readonly state: ReadonlyMap<K, PerKeyS>;
+        /**
+         * Submits an invocation for the key derived from the input. Returns a `Deferred` tied
+         * to this specific invocation. Same-key behaviour is controlled by `perKey`.
+         */
+        run: (input: I) => Deferred<Exclude<PerKeyS, Pending | Retrying<E>>>;
+        /** Cancels the in-flight operation for a specific key, or all keys if omitted. */
+        abort: (key?: K) => void;
+        /**
+         * Registers a subscriber. The callback receives a fresh snapshot of the state map
+         * on every transition. Returns an unsubscribe function.
+         * Fires immediately with the current map if any key is active.
+         */
+        subscribe: (cb: (state: ReadonlyMap<K, PerKeyS>) => void) => () => void;
+    };
+    /** States reachable by a `once` manager (no retry). */
+    type OnceState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `once` manager with retry configured. */
+    type RetryableOnceState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `restartable` manager (no retry). */
+    type RestartableState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | ReplacedNil;
+    /** States reachable by a `restartable` manager with retry configured. */
+    type RetryableRestartableState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | ReplacedNil;
+    /** States reachable by an `exclusive` manager (no retry). */
+    type ExclusiveState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by an `exclusive` manager with retry configured. */
+    type RetryableExclusiveState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `queue` manager (no retry, no overflow, no dedupe). */
+    type QueueState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil;
+    /** States reachable by a `queue` manager with retry (no overflow, no dedupe). */
+    type RetryableQueueState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil;
+    /** States reachable by a `queue` manager with `overflow:"drop"` or `dedupe` (no retry). */
+    type QueueDropState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `queue` manager with `overflow:"drop"` or `dedupe`, with retry. */
+    type RetryableQueueDropState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `queue` manager with `overflow:"replace-last"` and no `dedupe` (no retry). */
+    type QueueReplaceState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `queue` manager with `overflow:"replace-last"` and no `dedupe`, with retry. */
+    type RetryableQueueReplaceState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `queue` manager with `overflow:"replace-last"` AND `dedupe` (no retry). */
+    type QueueDropAndReplaceState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil | DroppedNil | EvictedNil;
+    /** States reachable by a `queue` manager with `overflow:"replace-last"` AND `dedupe`, with retry. */
+    type RetryableQueueDropAndReplaceState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil | EvictedNil;
+    /** States reachable by a `buffered` manager (no retry). */
+    type BufferedState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `buffered` manager with retry configured. */
+    type RetryableBufferedState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `debounced` manager (no retry). */
+    type DebouncedState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `debounced` manager with retry configured. */
+    type RetryableDebouncedState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `throttled` manager (leading-only, no retry). */
+    type ThrottledState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `throttled` manager (leading-only, with retry). */
+    type RetryableThrottledState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `throttled` manager with `trailing: true` (no retry). */
+    type ThrottledTrailingState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `throttled` manager with `trailing: true` and retry. */
+    type RetryableThrottledTrailingState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | EvictedNil;
+    /** States reachable by a `concurrent` manager with `overflow: "queue"` (no retry). */
+    type ConcurrentQueueState<E, A> = Idle | Pending | Queued | Ok<A> | Err<E> | AbortedNil;
+    /** States reachable by a `concurrent` manager with `overflow: "queue"` and retry. */
+    type RetryableConcurrentQueueState<E, A> = Idle | Pending | Queued | Retrying<E> | Ok<A> | Err<E> | AbortedNil;
+    /** States reachable by a `concurrent` manager with `overflow: "drop"` (no retry). */
+    type ConcurrentDropState<E, A> = Idle | Pending | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** States reachable by a `concurrent` manager with `overflow: "drop"` and retry. */
+    type RetryableConcurrentDropState<E, A> = Idle | Pending | Retrying<E> | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** Per-key state union for a `keyed` manager with `perKey: "exclusive"`. */
+    type KeyedExclusivePerKey<E, A> = Pending | Ok<A> | Err<E> | AbortedNil | DroppedNil;
+    /** Per-key state union for a `keyed` manager with `perKey: "restartable"`. */
+    type KeyedRestartablePerKey<E, A> = Pending | Ok<A> | Err<E> | AbortedNil | ReplacedNil;
+    type RetryOptions<E> = RetryOptions<E>;
+    type TimeoutOptions<E> = TimeoutOptions<E>;
+    /**
+     * Creates a `Nil` outcome with a reason.
+     *
+     * @example
+     * ```ts
+     * Op.nil("aborted");  // { kind: "Nil", reason: "aborted" }
+     * Op.nil("dropped");  // { kind: "Nil", reason: "dropped" }
+     * Op.nil("replaced"); // { kind: "Nil", reason: "replaced" }
+     * Op.nil("evicted");  // { kind: "Nil", reason: "evicted" }
+     * ```
+     */
+    const nil: (reason: NilReason) => Nil;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * const saveProfile = Op.create(
+     *   (data: ProfileData, signal) =>
+     *     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>;
+    /**
+     * Creates a successful Outcome.
+     *
+     * @example
+     * ```ts
+     * Op.ok(42); // { kind: "Ok", value: 42 }
+     * ```
+     */
+    const ok: <A>(value: A) => Ok<A>;
+    /**
+     * Creates a failed Outcome with a typed error.
+     *
+     * @example
+     * ```ts
+     * Op.err(new ApiError("not found")); // { kind: "Err", error: ApiError }
+     * ```
+     */
+    const err: <E>(error: E) => Err<E>;
+    /**
+     * Returns `true` if the Outcome is `Ok`.
+     *
+     * @example
+     * ```ts
+     * if (Op.isOk(outcome)) render(outcome.value);
+     * ```
+     */
+    const isOk: <E, A>(outcome: Outcome<E, A>) => outcome is Ok<A>;
+    /**
+     * Returns `true` if the Outcome is `Err`.
+     *
+     * @example
+     * ```ts
+     * if (Op.isErr(outcome)) logger.error(outcome.error);
+     * ```
+     */
+    const isErr: <E, A>(outcome: Outcome<E, A>) => outcome is Err<E>;
+    /**
+     * Returns `true` if the Outcome is `Nil`.
+     *
+     * @example
+     * ```ts
+     * if (Op.isNil(outcome)) resetUI();
+     * ```
+     */
+    const isNil: <E, A>(outcome: Outcome<E, A>) => outcome is Nil;
+    /**
+     * Pattern matches on an Outcome using named case handlers.
+     *
+     * @example
+     * ```ts
+     * Op.match({
+     *   ok:  (user) => render(user),
+     *   err: (e)    => showError(e.message),
+     *   nil: ()     => resetUI(),
+     * })(outcome);
+     * ```
+     */
+    const match: <E, A, B>(cases: {
+        ok: (a: A) => B;
+        err: (e: E) => B;
+        nil: () => B;
+    }) => (outcome: Outcome<E, A>) => B;
+    /**
+     * Eliminates an Outcome with positional handlers.
+     * Order: `onErr`, `onOk`, `onNil` — mirrors `Result.fold` for the first two.
+     *
+     * @example
+     * ```ts
+     * Op.fold(
+     *   (e) => `error: ${e.message}`,
+     *   (v) => `value: ${v}`,
+     *   ()  => "nothing",
+     * )(outcome);
+     * ```
+     */
+    const fold: <E, A, B>(onErr: (e: E) => B, onOk: (a: A) => B, onNil: () => B) => (outcome: Outcome<E, A>) => B;
+    /**
+     * Returns the success value, or the result of `defaultValue()` for `Err` or `Nil`.
+     *
+     * @example
+     * ```ts
+     * Op.getOrElse(() => [] as User[])(outcome);
+     * ```
+     */
+    const getOrElse: <E, A, B>(defaultValue: () => B) => (outcome: Outcome<E, A>) => A | B;
+    /**
+     * Transforms the success value. `Err` and `Nil` pass through unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(outcome, Op.map(user => user.name));
+     * ```
+     */
+    const map: <E, A, B>(f: (a: A) => B) => (outcome: Outcome<E, A>) => Outcome<E, B>;
+    /**
+     * Transforms the error value. `Ok` and `Nil` pass through unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(outcome, Op.mapError(e => e.message));
+     * ```
+     */
+    const mapError: <E, F, A>(f: (e: E) => F) => (outcome: Outcome<E, A>) => Outcome<F, A>;
+    /**
+     * Chains Outcome computations. Runs `f` on `Ok`; `Err` and `Nil` pass through.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   outcome,
+     *   Op.chain(user => user.active ? Op.ok(user) : Op.err(new Error("inactive"))),
+     * );
+     * ```
+     */
+    const chain: <E, A, B>(f: (a: A) => Outcome<E, B>) => (outcome: Outcome<E, A>) => Outcome<E, B>;
+    /**
+     * Runs a side effect on the success value without changing the Outcome.
+     *
+     * @example
+     * ```ts
+     * pipe(outcome, Op.tap(user => console.log("loaded", user.id)));
+     * ```
+     */
+    const tap: <E, A>(f: (a: A) => void) => (outcome: Outcome<E, A>) => Outcome<E, A>;
+    /**
+     * Provides a fallback Outcome when the result is `Err`. `Ok` and `Nil` pass through.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   outcome,
+     *   Op.recover(e => e.isRetryable ? Op.ok(cachedValue) : Op.err(e)),
+     * );
+     * ```
+     */
+    const recover: <E, A, B>(f: (e: E) => Outcome<E, B>) => (outcome: Outcome<E, A>) => Outcome<E, A | B>;
+    /**
+     * Converts an Outcome to a `Result`. `Nil` becomes `Err(onNil())`.
+     *
+     * @example
+     * ```ts
+     * Op.toResult(() => new ApiError("no result"))(outcome);
+     * ```
+     */
+    const toResult: <E, A>(onNil: () => E) => (outcome: Outcome<E, A>) => Result<E, A>;
+    /**
+     * Converts an Outcome to a `Maybe`. `Ok` becomes `Some`; `Err` and `Nil` become `None`.
+     *
+     * @example
+     * ```ts
+     * Op.toMaybe(outcome); // Maybe<User>
+     * ```
+     */
+    const toMaybe: <E, A>(outcome: Outcome<E, A>) => Maybe<A>;
+    /**
+     * Resolves when all invocations settle, returning their outcomes in order.
+     * An alternative to `Promise.all` that stays within the `Op` type system.
+     *
+     * @example
+     * ```ts
+     * const [a, b] = await Op.all([manager.run(inputA), manager.run(inputB)]);
+     * ```
+     */
+    const all: <E, A>(invocations: ReadonlyArray<Deferred<Outcome<E, A>>>) => Deferred<ReadonlyArray<Outcome<E, A>>>;
+    /**
+     * Resolves to the outcome of whichever invocation settles first.
+     * An alternative to `Promise.race` that stays within the `Op` type system.
+     *
+     * @example
+     * ```ts
+     * const winner = await Op.race([manager.run(inputA), manager.run(inputB)]);
+     * ```
+     */
+    const race: <E, A>(invocations: ReadonlyArray<Deferred<Outcome<E, A>>>) => Deferred<Outcome<E, A>>;
+    /**
+     * Attaches a concurrency strategy to an `Op`, returning a `Manager`.
+     *
+     * Strategy is data, not a method name. The `S` type parameter is narrowed to only
+     * the states reachable for the chosen strategy and options — subscribers cannot
+     * reference states that cannot occur.
+     *
+     * **Strategies:**
+     * - `once`        — fires once. Only the first `run()` executes; subsequent calls
+     *                   return `DroppedNil` immediately. State is permanent after completion.
+     * - `restartable` — new call cancels the previous (`ReplacedNil`). Only the latest result matters.
+     * - `exclusive`   — new calls while in-flight return `DroppedNil` immediately.
+     * - `queue`       — calls run in submission order. `Queued` state shows position.
+     * - `buffered`    — 1 in-flight + 1 waiting slot. Newer calls evict the slot (`EvictedNil`).
+     * - `debounced`   — waits `ms` ms of quiet before starting. Earlier calls get `EvictedNil`.
+     *
+     * **`retry` and `timeout`** can be combined with any strategy. Both are applied
+     * internally per `run()` call — set the policy once, not at every call site.
+     * The timeout wraps the entire retry sequence (one deadline for all attempts).
+     * When `retry` is present, `Retrying` is added to the subscriber type.
+     *
+     * @example
+     * ```ts
+     * // Load once on mount — further calls are no-ops
+     * const getUser = Op.interpret(fetchUser, { strategy: "once" });
+     * getUser.subscribe(state => {
+     *   if (state.kind === "Pending") showSpinner();
+     *   if (state.kind === "Ok")      render(state.value);
+     * });
+     * getUser.run(userId);
+     *
+     * // Search: cancel the previous query when a new one starts
+     * const search = Op.interpret(searchOp, { strategy: "restartable" });
+     *
+     * // Form submit: ignore double-clicks while in-flight
+     * const submit = Op.interpret(submitOp, {
+     *   strategy: "exclusive",
+     *   retry: { attempts: 3, backoff: n => n * 500 },
+     *   timeout: { ms: 10_000, onTimeout: () => new ApiError("timed out") },
+     * });
+     *
+     * // Auto-save: current save commits fully; latest pending edit saves next
+     * const save = Op.interpret(saveOp, { strategy: "buffered" });
+     * ```
+     */
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "throttled";
+    } & WithMs & WithTrailing & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableThrottledTrailingState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "throttled";
+    } & WithMs & WithTrailing & WithTimeout<E>): Manager<I, E, A, ThrottledTrailingState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "throttled";
+    } & WithMs & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableThrottledState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "throttled";
+    } & WithMs & WithTimeout<E>): Manager<I, E, A, ThrottledState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithLeading & WithMaxWait & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableDebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithLeading & WithMaxWait & WithTimeout<E>): Manager<I, E, A, DebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithLeading & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableDebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithLeading & WithTimeout<E>): Manager<I, E, A, DebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithMaxWait & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableDebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithMaxWait & WithTimeout<E>): Manager<I, E, A, DebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableDebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "debounced";
+    } & WithMs & WithTimeout<E>): Manager<I, E, A, DebouncedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "concurrent";
+    } & WithN & WithOverflow<"queue"> & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableConcurrentQueueState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "concurrent";
+    } & WithN & WithOverflow<"queue"> & WithTimeout<E>): Manager<I, E, A, ConcurrentQueueState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "concurrent";
+    } & WithN & WithOverflow<"drop"> & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableConcurrentDropState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "concurrent";
+    } & WithN & WithOverflow<"drop"> & WithTimeout<E>): Manager<I, E, A, ConcurrentDropState<E, A>>;
+    function interpret<I, K, E, A>(op: Op<I, E, A>, options: {
+        strategy: "keyed";
+    } & WithKey<I, K> & WithPerKey<"exclusive"> & WithTimeout<E>): KeyedManager<I, K, E, KeyedExclusivePerKey<E, A>>;
+    function interpret<I, K, E, A>(op: Op<I, E, A>, options: {
+        strategy: "keyed";
+    } & WithKey<I, K> & WithPerKey<"restartable"> & WithTimeout<E>): KeyedManager<I, K, E, KeyedRestartablePerKey<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "once";
+    } & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableOnceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "once";
+    } & WithTimeout<E>): Manager<I, E, A, OnceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "restartable";
+    } & WithMinInterval & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableRestartableState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "restartable";
+    } & WithMinInterval & WithTimeout<E>): Manager<I, E, A, RestartableState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "exclusive";
+    } & WithCooldown & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableExclusiveState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "exclusive";
+    } & WithCooldown & WithTimeout<E>): Manager<I, E, A, ExclusiveState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithMaxSize & WithOverflow<"replace-last"> & WithDedupe<I> & WithRetry<E> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, RetryableQueueDropAndReplaceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithMaxSize & WithOverflow<"replace-last"> & WithDedupe<I> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, QueueDropAndReplaceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithMaxSize & WithOverflow<"replace-last"> & WithRetry<E> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, RetryableQueueReplaceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithMaxSize & WithOverflow<"replace-last"> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, QueueReplaceState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & (WithMaxSize | WithDedupe<I>) & WithRetry<E> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, RetryableQueueDropState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & (WithMaxSize | WithDedupe<I>) & WithConcurrency & WithTimeout<E>): Manager<I, E, A, QueueDropState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithRetry<E> & WithConcurrency & WithTimeout<E>): Manager<I, E, A, RetryableQueueState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "queue";
+    } & WithConcurrency & WithTimeout<E>): Manager<I, E, A, QueueState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "buffered";
+    } & WithSize & WithRetry<E> & WithTimeout<E>): Manager<I, E, A, RetryableBufferedState<E, A>>;
+    function interpret<I, E, A>(op: Op<I, E, A>, options: {
+        strategy: "buffered";
+    } & WithSize & WithTimeout<E>): Manager<I, E, A, BufferedState<E, A>>;
+}
+
 /**
  * A function from `A` to `A is B` — a type predicate paired with a runtime check.
  *
@@ -1053,7 +1647,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 +1665,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.
      */
@@ -1121,75 +1716,6 @@ declare namespace TaskResult {
      * Useful for logging or debugging.
      */
     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.
-     *
-     * @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
-     * @param options.when - Only retry when this returns true; defaults to always retry on Err
-     *
-     * @example
-     * ```ts
-     * // Retry up to 3 times with exponential backoff
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.retry({ attempts: 3, backoff: n => n * 1000 })
-     * );
-     *
-     * // Only retry on network errors, not auth errors
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.retry({ attempts: 3, when: e => e instanceof NetworkError })
-     * );
-     * ```
-     */
-    const retry: <E>(options: {
-        attempts: number;
-        backoff?: number | ((attempt: number) => number);
-        when?: (error: E) => boolean;
-    }) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
-    /**
-     * Polls a TaskResult repeatedly until the success value satisfies a predicate.
-     * Stops immediately and returns `Err` if the task fails.
-     *
-     * `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.
-     *
-     * @example
-     * ```ts
-     * const checkJob = (id: string): TaskResult<string, { status: "pending" | "done" }> =>
-     *   TaskResult.tryCatch(() => fetch(`/jobs/${id}`).then(r => r.json()), String);
-     *
-     * // Fixed delay: poll every 2s
-     * pipe(
-     *   checkJob(jobId),
-     *   TaskResult.pollUntil({ when: job => job.status === "done", delay: 2000 }),
-     * );
-     *
-     * // Computed delay: 1s, 2s, 3s, ...
-     * pipe(
-     *   checkJob(jobId),
-     *   TaskResult.pollUntil({ when: job => job.status === "done", delay: n => n * 1000 }),
-     * );
-     * ```
-     */
-    const pollUntil: <A>(options: {
-        when: (a: A) => boolean;
-        delay?: number | ((attempt: number) => number);
-    }) => <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.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   fetchUser,
-     *   TaskResult.timeout(5000, () => new TimeoutError("fetch user timed out"))
-     * );
-     * ```
-     */
-    const timeout: <E>(ms: number, onTimeout: () => E) => <A>(data: TaskResult<E, A>) => TaskResult<E, A>;
 }
 
 /**
@@ -2292,4 +2818,4 @@ declare namespace Tuple {
     const tap: <A, B>(f: (a: A, b: B) => void) => (tuple: Tuple<A, B>) => Tuple<A, B>;
 }
 
-export { type Failure, type Invalid, Lens, type Loading, Logged, Maybe, type NotAsked, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, TaskMaybe, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };
+export { Deferred, type Failure, type Invalid, Lens, type Loading, Logged, Maybe, type NotAsked, Op, Optional, Predicate, Reader, Refinement, RemoteData, Resource, Result, State, type Success, Task, TaskMaybe, TaskResult, TaskValidation, These, type TheseBoth, type TheseFirst, type TheseSecond, Tuple, type Valid, Validation };