footprintjs 10.0.0 → 10.1.0

package/dist/esm/lib/attempt/runner.d.ts

@@ -0,0 +1,155 @@
+/**
+ * attempt/runner.ts — `runAttempts`, THE retry loop (design §3.1, law 1: one runner, one record).
+ *
+ * Runs a function under a policy and records every try: one frozen `AttemptRecord` per attempt, carrying its
+ * timing, outcome, failure category and the retry-or-stop decision (`attempt/decision.ts`), and one
+ * `AttemptSummary` when the series ends. The engine's stage retry (`FlowchartTraverser · executeStage`) runs on
+ * it; later packets run in-stage calls and standalone `attempt()` on it too.
+ *
+ * The loop, per attempt n — for a failed attempt, the 9.15 loop's order, step for step:
+ *
+ *   start → run(n) → outcome (ok | failed | aborted [it threw the run's abort reason] | paused [a PauseSignal])
+ *         → decide over the inputs, first match wins (`retryRules`) — retryOn is asked here (rule 5)
+ *         → the run's signal aborted inside retryOn? decide again: rule 3 stops the series here, before the
+ *           discard and before backoffMs, as the 9.15 abort check did
+ *         → retry: between(n) — the discard — and THEN backoffMs(n), the wait's length
+ *         → the error's served form and category, read after retryOn and backoffMs ran → the record
+ *         → onEnd(summary)                                               only when the series ends here
+ *         → onAttempt(record, served error)
+ *         → done: return the value · stop: rethrow the attempt's OWN error
+ *         → retry: onRetry(n, of, delay, served error) → wait (cut short by the signal) → aborted? stop
+ *
+ * WHAT IT PRESERVES (the 9.15 loop's behaviour, moved here unchanged): the function runs the same number of
+ * times; `retryOn` is asked only for a failed, non-final attempt; `backoffMs` only when a retry follows, after
+ * the discard; a throwing predicate is "do not retry", a throwing or non-finite backoff is "no wait"; a pause is
+ * never retried; the attempt's own error is rethrown, never a wrapper; and a failed attempt's order —
+ * `retryOn` → the abort check → the discard (`between`) → `backoffMs` → the served error → the retry event →
+ * the wait → the abort check. So an abort inside `retryOn` stops before the discard and never asks `backoffMs`;
+ * an abort inside `backoffMs` comes after the discard, still fires the retry event, then ends at the wait; and
+ * the served error shows what `retryOn` did to the thrown value. The one difference: when the run's signal has
+ * ALREADY aborted as the attempt fails, the series stops without asking `retryOn` (the abort decides first —
+ * rule 3 before rule 5).
+ *
+ * WHAT IT ADDS: the record and the summary. A record is frozen to its leaves and holds only clone-safe data —
+ * the error as the run SERVES it (`serve`, the redaction rule's form) without `raw`. The hook gets the served
+ * `StructuredErrorInfo` whole, `raw` included, as `onStageRetry` always has. A record never rewrites what the
+ * attempt did: an attempt that threw its own error is `failed`, with its category, even when the run aborted
+ * around it — the abort is the series' stop reason (`reason: 'aborted'`); a throwing `retryOn` is `declined`
+ * with `retryOnThrew: true`, apart from a real `false`.
+ *
+ * TIME (P1b). Each attempt runs under `min(policy.timeoutMs, time left before options.deadline)` and gets an
+ * `AttemptContext` — its signal, composed from the run's and its own cap's timer (`LiveAttempt`). The cap's timer
+ * aborts with an `AttemptTimeoutError`; the run's deadline aborts the run's signal with a branded reason
+ * (`attempt/deadline.ts`). Either way the attempt is `'timeout'`, never `'aborted'`: the deadline is not a
+ * cancellation, so rule 3 does not match and rule 6 (`timeLeftAfterWaitMs ≤ 0`) stops a series whose next wait
+ * would outlast it. Under a deadline rule 6 needs the wait's length, so `backoffMs(n, error)` is asked DURING the
+ * decision — before the discard; without one the 9.15 order above holds unchanged. No attempt starts at or past
+ * the deadline: a wait the deadline cut ends the series `no-time-left`, recording no further attempt.
+ *
+ * THE FENCE. The moment an attempt ends without an answer — its signal aborts (synchronously, before any listener
+ * the function added) or it throws — `onAbandon(n)` fires once, and the engine closes that attempt's scope: the
+ * function may still be running, and nothing it does afterwards may land beside a later attempt.
+ *
+ * ONE async frame with ONE await per attempt: the engine relies on that to keep a retried stage's microtask
+ * shape, so parallel siblings settle in the order they always did. The engine races the attempt's signal itself,
+ * at the stage boundary (`raced: true`); any other caller gets the race here, so the series never waits on an
+ * attempt past its cap.
+ *
+ * CALLS (P2). The same loop runs a call a stage makes (`attempt/call.ts · runCall`, kind `'call'`, its `target` on
+ * every record) and the standalone `attempt()`. An attempt's cap is the DEADLINE of every call made inside it, so
+ * the cap's reason is branded a time limit (`attempt/deadline.ts · markTimeLimit`): a call cut by its stage
+ * attempt's cap timed out, it was not cancelled. `attemptEndsAt` says when an attempt must end; an `interrupt()`
+ * thrown inside a call is a pause, like a `PauseSignal` — never retried.
+ */
+import type { StructuredErrorInfo } from '../errors/errorInfo.js';
+import type { EffectTarget } from './effect.js';
+import type { AttemptContext, AttemptKind, AttemptRecord, AttemptSummary, ObservedAttempt, RetryPolicy } from './types.js';
+/** What a series reports, and the engine's between-attempt step. Every member is optional. */
+export interface AttemptRunOptions {
+    /** The series every record names — for a stage attempt, its execution's `runtimeStageId`. */
+    readonly series: string;
+    /** Default `'stage'`. */
+    readonly kind?: AttemptKind;
+    /** The outside target every record names — a call's (`$call`, `attempt()`); absent for a stage attempt. */
+    readonly target?: string;
+    /**
+     * The run's signal. Once it has aborted (other than at the deadline), rule 3 stops the series
+     * (`reason: 'aborted'`); it cuts a wait short. An attempt that threw its reason is recorded `'aborted'` — or
+     * `'timeout'` when the reason is the deadline's (`attempt/deadline.ts`).
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * The run's deadline, epoch milliseconds. Every attempt is capped by the time left; rule 6 stops a series whose
+     * next wait would outlast it (`no-time-left`). Absent (or not finite) = no deadline: the time left is `Infinity`.
+     */
+    readonly deadline?: number;
+    /** The clock, epoch milliseconds. Default `Date.now`. */
+    readonly now?: () => number;
+    /** The served form of a failed attempt's error. Default `extractErrorInfo` (no redaction rule). */
+    readonly serve?: (error: unknown) => StructuredErrorInfo;
+    /** Between a failed attempt and the next, before `backoffMs`: the engine discards the attempt's staged writes. */
+    readonly between?: (attempt: number) => void;
+    /** Every attempt, at its end, with its served error (`undefined` for `'ok'` and `'paused'`). */
+    readonly onAttempt?: (record: AttemptRecord, structuredError: StructuredErrorInfo | undefined) => void;
+    /** A failed attempt that WILL be retried — after `between` and `onAttempt`, before the wait. */
+    readonly onRetry?: (attempt: number, of: number, delayMs: number, structuredError: StructuredErrorInfo) => void;
+    /** The series ended: called once, before the last `onAttempt` (or after a wait the run's signal cut). */
+    readonly onEnd?: (summary: AttemptSummary) => void;
+    /** `retryOn` threw — the attempt is treated as declined; the engine logs the throw here. */
+    readonly onRetryOnThrew?: (thrown: unknown) => void;
+    /**
+     * The attempt ended without an answer — called SYNCHRONOUSLY the moment its signal aborts (its cap, the deadline,
+     * a cancellation), else as soon as it failed. Whatever the abandoned function does afterwards is not this
+     * series': the engine fences its scope here. Once per attempt; never for `'ok'` or `'paused'` — except an attempt
+     * that STARTED under an already-aborted signal, fenced once its synchronous part has run (nobody waits for it).
+     */
+    readonly onAbandon?: (attempt: number) => void;
+    /**
+     * The caller races `run`'s promise against the attempt's signal itself — the engine does, at the stage boundary
+     * (`StageRunner`), so a stage keeps its one await per attempt. Otherwise the runner races it: the series never
+     * waits on an attempt past its cap.
+     */
+    readonly raced?: boolean;
+    /**
+     * What an attempt's `observed(report)` does (P2) — the owner of the attempt records the report: `runCall` hands
+     * a call's reports to the scope, `attempt()` keeps its own. `ended` says the attempt had already ended when the
+     * report came (the owner drops it). Absent — a stage attempt's context, whose `observed` the scope's
+     * `$attempt()` replaces — `observed` is refused with a `TypeError`.
+     */
+    readonly observe?: (report: ObservedAttempt, at: {
+        readonly attempt: number;
+        readonly ended: boolean;
+    }) => void;
+    /**
+     * The outside system the target touches (P3, design §3.3). Every record then says what its attempt did to it
+     * (`effect`) and names the system and the RECORDED key; every attempt's context carries the REAL key. A series
+     * that ends without an answer after any attempt of unknown effect fails with `UnknownEffectError` (its `cause` the attempt's own error) —
+     * except a pause, which stays a pause. A touching series that may retry without a key is refused before anything
+     * runs: the law's last door.
+     */
+    readonly effect?: EffectTarget;
+}
+/**
+ * When the attempt behind `context` must end, epoch milliseconds — its start plus its cap (`min(timeoutMs, time
+ * left)`, so never past the run's deadline) — or `undefined` for an uncapped attempt. A call made inside the
+ * attempt runs under it as its deadline (`attempt/call.ts`). Only the runner's own contexts are known.
+ */
+export declare function attemptEndsAt(context: AttemptContext | undefined): number | undefined;
+/**
+ * Run `run` until it succeeds or the policy stops it; resolve with its value or reject with the LAST attempt's
+ * own error. `run(n)` is called with the attempt number, 1-based.
+ */
+export declare function runAttempts<T>(run: (attempt: number, context: AttemptContext) => Promise<T> | T, policy: RetryPolicy, options: AttemptRunOptions): Promise<T>;
+/**
+ * Resolve a policy's `backoffMs` for the attempt that just failed (1-based) and its error. Anything that is not a finite,
+ * positive number — a missing dial, a negative value, a `NaN` from a consumer's arithmetic, or a throwing
+ * function — becomes `0`, i.e. retry immediately. A backoff dial must never be able to crash a run or park it
+ * forever.
+ */
+export declare function resolveBackoffMs(backoffMs: RetryPolicy['backoffMs'], attempt: number, error?: unknown): number;
+/**
+ * Await `ms`, cut short by an abort. Resolves either way — the caller re-checks `signal.aborted` and rethrows
+ * the attempt's own error, so a cancelled run never sits out a long backoff and never loses the failure that
+ * caused it. The timer and the listener are always cleaned up.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;