@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/retry-BDbRZ_gx.d.ts

@@ -0,0 +1,125 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.js';
+import { B as BackoffStrategy, a as BackoffPreset } from './backoff-Bnb9OoPh.js';
+import { S as StatusValue } from './status-U-rUI79b.js';
+
+/**
+ * Retry — re-attempt a node on terminal failure.
+ *
+ * Two modes selected by the type of `input`:
+ * - **Source mode** (`Node<T>`): resubscribes the same node after each ERROR.
+ *   Upstream must be `resubscribable: true` or retries are silent no-ops.
+ * - **Factory mode** (`() => Node<T>`): builds a fresh node per attempt.
+ *
+ * Shared with `circuitBreaker` / `rateLimiter`: `NodeOrValue<RetryOptions>`
+ * lets callers swap retry config reactively (re-validates on each attempt).
+ */
+
+/**
+ * Lifecycle-shaped state companion emitted by {@link retry} (DS-13.5.B,
+ * locked 2026-05-01). Tracks the retry state machine's current status,
+ * the attempt counter, and the last scheduled delay (null before the
+ * first retry).
+ *
+ * @category extra/resilience
+ */
+interface RetryState {
+    status: StatusValue;
+    attempt: number;
+    lastDelay_ns: number | null;
+}
+/**
+ * Bundle returned by {@link retry}: the retry-wrapped output node and its
+ * lifecycle state companion. Pre-1.0 break vs the prior `Node<T>` return.
+ *
+ * **Single-subscriber / pipeline-only contract (DS-13.5.B QA, N1, 2026-05-03).**
+ * The `retryState` companion is allocated once at factory time and shared
+ * across all subscribers to `node`. With one subscriber (the typical use
+ * case — wire `node` into your downstream chain, optionally observe
+ * `retryState` separately) the companion reflects a coherent timeline.
+ * With **two or more subscribers** to `node`, each subscriber re-runs the
+ * producer body and writes into the same `retryState`, including
+ * `publish("pending")` resets that can clobber an in-flight machine's
+ * `running`/`paused` state. Don't fan out `node` to multiple subscribers
+ * and rely on `retryState` accuracy unless you use
+ * {@link keepalive} / `share`-style consolidation.
+ *
+ * @category extra/resilience
+ */
+interface RetryBundle<T> {
+    node: Node<T>;
+    retryState: Node<RetryState>;
+}
+type RetryOptions = {
+    /**
+     * Max retry attempts after each terminal `ERROR` (not counting the first failure).
+     *
+     * **Required when `backoff` is set.** Pass `Infinity` to opt in to unbounded retries
+     * — the explicit value rules out the silent-infinite-budget footgun (a flaky provider
+     * + exponential backoff + omitted `count` would previously default to ~2.1B retries).
+     */
+    count?: number;
+    /** Delay between attempts; strategies use **nanoseconds**. */
+    backoff?: BackoffStrategy | BackoffPreset;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()`
+     * grouping. The primitive's `factoryTag("retry", …)` always wins against
+     * caller keys.
+     */
+    meta?: Record<string, unknown>;
+};
+/** Factory-mode-only options. `initial` seeds the outer node's cache before the first attempt. */
+type RetryFactoryOptions<T> = RetryOptions & {
+    /** Initial cache value for the outer node before the factory runs the first time. */
+    initial?: T;
+};
+/**
+ * Retry operator — two modes selected by the type of `input`:
+ *
+ * **Source mode** (`input: Node<T>`): resubscribes to the same node after each terminal
+ * `ERROR`. The upstream should use `resubscribable: true` if it must emit again after `ERROR`.
+ *
+ * **Factory mode** (`input: () => Node<T>`): invokes the factory to build a fresh `Node<T>`
+ * on every connect / reconnect. Ideal for producers that capture per-attempt resources
+ * (sockets, clients, file handles) that become unusable after an error. Synchronous
+ * exceptions thrown by the factory are treated as terminal ERROR and run through the
+ * same retry pipeline as inner-node ERROR.
+ *
+ * @param input - Upstream node or factory that returns a fresh node per attempt.
+ * @param opts - `count` caps attempts (**required when `backoff` is set**; pass `Infinity` to opt in to unbounded); `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
+ * @returns Node that retries on error.
+ *
+ * @throws {RangeError} when `backoff` is provided without an explicit `count` (unbounded-retry footgun guard) or when `count < 0`.
+ *
+ * @remarks
+ * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
+ *
+ * **Backoff floor:** every scheduled delay is floored at 1ms via `Math.max(1, delayNs / NS_PER_MS)` even when the strategy returns 0ns. This avoids 0-delay re-entrancy on the active stack frame on a tight ERROR loop. Strategies that return `null`/`undefined` stop retrying immediately and forward the original error.
+ *
+ * @example
+ * ```ts
+ * // Source mode — resubscribe the same node:
+ * import { ERROR, NS_PER_SEC, producer, retry, constant } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = producer(
+ *   (a) => { a.down([[ERROR, new Error("x")]]); },
+ *   { resubscribable: true },
+ * );
+ * const out = retry(src, { count: 2, backoff: constant(0.25 * NS_PER_SEC) });
+ *
+ * // Factory mode — fresh node per attempt (e.g. reconnecting WebSocket):
+ * import { NS_PER_SEC, exponential, retry, fromWebSocket } from "@graphrefly/graphrefly-ts";
+ *
+ * const connected$ = retry(
+ *   () => fromWebSocket(new WebSocket("wss://example/stream")),
+ *   { count: 10, backoff: exponential({ baseNs: 1 * NS_PER_SEC }) },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function retry<T>(input: Node<T>, opts?: NodeOrValue<RetryOptions>): RetryBundle<T>;
+declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): RetryBundle<T>;
+
+export { type RetryBundle as R, type RetryFactoryOptions as a, type RetryOptions as b, type RetryState as c, retry as r };

package/dist/retry-DWuhjvsA.d.cts

@@ -0,0 +1,125 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.cjs';
+import { B as BackoffStrategy, a as BackoffPreset } from './backoff-Bnb9OoPh.cjs';
+import { S as StatusValue } from './status-U-rUI79b.cjs';
+
+/**
+ * Retry — re-attempt a node on terminal failure.
+ *
+ * Two modes selected by the type of `input`:
+ * - **Source mode** (`Node<T>`): resubscribes the same node after each ERROR.
+ *   Upstream must be `resubscribable: true` or retries are silent no-ops.
+ * - **Factory mode** (`() => Node<T>`): builds a fresh node per attempt.
+ *
+ * Shared with `circuitBreaker` / `rateLimiter`: `NodeOrValue<RetryOptions>`
+ * lets callers swap retry config reactively (re-validates on each attempt).
+ */
+
+/**
+ * Lifecycle-shaped state companion emitted by {@link retry} (DS-13.5.B,
+ * locked 2026-05-01). Tracks the retry state machine's current status,
+ * the attempt counter, and the last scheduled delay (null before the
+ * first retry).
+ *
+ * @category extra/resilience
+ */
+interface RetryState {
+    status: StatusValue;
+    attempt: number;
+    lastDelay_ns: number | null;
+}
+/**
+ * Bundle returned by {@link retry}: the retry-wrapped output node and its
+ * lifecycle state companion. Pre-1.0 break vs the prior `Node<T>` return.
+ *
+ * **Single-subscriber / pipeline-only contract (DS-13.5.B QA, N1, 2026-05-03).**
+ * The `retryState` companion is allocated once at factory time and shared
+ * across all subscribers to `node`. With one subscriber (the typical use
+ * case — wire `node` into your downstream chain, optionally observe
+ * `retryState` separately) the companion reflects a coherent timeline.
+ * With **two or more subscribers** to `node`, each subscriber re-runs the
+ * producer body and writes into the same `retryState`, including
+ * `publish("pending")` resets that can clobber an in-flight machine's
+ * `running`/`paused` state. Don't fan out `node` to multiple subscribers
+ * and rely on `retryState` accuracy unless you use
+ * {@link keepalive} / `share`-style consolidation.
+ *
+ * @category extra/resilience
+ */
+interface RetryBundle<T> {
+    node: Node<T>;
+    retryState: Node<RetryState>;
+}
+type RetryOptions = {
+    /**
+     * Max retry attempts after each terminal `ERROR` (not counting the first failure).
+     *
+     * **Required when `backoff` is set.** Pass `Infinity` to opt in to unbounded retries
+     * — the explicit value rules out the silent-infinite-budget footgun (a flaky provider
+     * + exponential backoff + omitted `count` would previously default to ~2.1B retries).
+     */
+    count?: number;
+    /** Delay between attempts; strategies use **nanoseconds**. */
+    backoff?: BackoffStrategy | BackoffPreset;
+    /**
+     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
+     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()`
+     * grouping. The primitive's `factoryTag("retry", …)` always wins against
+     * caller keys.
+     */
+    meta?: Record<string, unknown>;
+};
+/** Factory-mode-only options. `initial` seeds the outer node's cache before the first attempt. */
+type RetryFactoryOptions<T> = RetryOptions & {
+    /** Initial cache value for the outer node before the factory runs the first time. */
+    initial?: T;
+};
+/**
+ * Retry operator — two modes selected by the type of `input`:
+ *
+ * **Source mode** (`input: Node<T>`): resubscribes to the same node after each terminal
+ * `ERROR`. The upstream should use `resubscribable: true` if it must emit again after `ERROR`.
+ *
+ * **Factory mode** (`input: () => Node<T>`): invokes the factory to build a fresh `Node<T>`
+ * on every connect / reconnect. Ideal for producers that capture per-attempt resources
+ * (sockets, clients, file handles) that become unusable after an error. Synchronous
+ * exceptions thrown by the factory are treated as terminal ERROR and run through the
+ * same retry pipeline as inner-node ERROR.
+ *
+ * @param input - Upstream node or factory that returns a fresh node per attempt.
+ * @param opts - `count` caps attempts (**required when `backoff` is set**; pass `Infinity` to opt in to unbounded); `backoff` supplies delay in **nanoseconds** (or a preset name); `initial` seeds the outer node cache (factory mode only).
+ * @returns Node that retries on error.
+ *
+ * @throws {RangeError} when `backoff` is provided without an explicit `count` (unbounded-retry footgun guard) or when `count < 0`.
+ *
+ * @remarks
+ * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
+ *
+ * **Backoff floor:** every scheduled delay is floored at 1ms via `Math.max(1, delayNs / NS_PER_MS)` even when the strategy returns 0ns. This avoids 0-delay re-entrancy on the active stack frame on a tight ERROR loop. Strategies that return `null`/`undefined` stop retrying immediately and forward the original error.
+ *
+ * @example
+ * ```ts
+ * // Source mode — resubscribe the same node:
+ * import { ERROR, NS_PER_SEC, producer, retry, constant } from "@graphrefly/graphrefly-ts";
+ *
+ * const src = producer(
+ *   (a) => { a.down([[ERROR, new Error("x")]]); },
+ *   { resubscribable: true },
+ * );
+ * const out = retry(src, { count: 2, backoff: constant(0.25 * NS_PER_SEC) });
+ *
+ * // Factory mode — fresh node per attempt (e.g. reconnecting WebSocket):
+ * import { NS_PER_SEC, exponential, retry, fromWebSocket } from "@graphrefly/graphrefly-ts";
+ *
+ * const connected$ = retry(
+ *   () => fromWebSocket(new WebSocket("wss://example/stream")),
+ *   { count: 10, backoff: exponential({ baseNs: 1 * NS_PER_SEC }) },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function retry<T>(input: Node<T>, opts?: NodeOrValue<RetryOptions>): RetryBundle<T>;
+declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): RetryBundle<T>;
+
+export { type RetryBundle as R, type RetryFactoryOptions as a, type RetryOptions as b, type RetryState as c, retry as r };