@graphrefly/graphrefly 0.44.0 → 0.45.0

package/dist/index-B1F8Enjf.d.ts

@@ -1,704 +0,0 @@
-import { N as Node } from './node-kK3CvTrR.js';
-
-/**
- * Backoff strategies for {@link retry} (roadmap §3.1). Delays are in **nanoseconds**.
- *
- * Convention: all graphrefly-ts timestamps and durations use nanoseconds (`_ns` suffix).
- * 1 second = 1_000_000_000 ns, 1 ms = 1_000_000 ns.
- */
-declare const NS_PER_MS = 1000000;
-declare const NS_PER_SEC = 1000000000;
-type JitterMode = "none" | "full" | "equal";
-type BackoffPreset = "constant" | "linear" | "exponential" | "fibonacci" | "decorrelatedJitter";
-/** `(attempt, error?, previousDelayNs?) => delayNs | null` — `null` means zero delay. */
-type BackoffStrategy = (attempt: number, error?: unknown, prevDelayNs?: number | null) => number | null;
-/**
- * Builds a strategy that always returns the same delay in nanoseconds.
- *
- * @param delayNs - Non-negative delay in nanoseconds; values below zero are clamped to zero.
- * @returns `BackoffStrategy` for use with {@link retry} or custom timers.
- *
- * @example
- * ```ts
- * import { constant, retry, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * const out = retry(source, { count: 3, backoff: constant(0.25 * NS_PER_SEC) });
- * ```
- *
- * @category extra
- */
-declare function constant(delayNs: number): BackoffStrategy;
-/**
- * Builds linear backoff: `baseNs + stepNs * attempt` (`stepNs` defaults to `baseNs`).
- *
- * @param baseNs - Base delay in nanoseconds (clamped non-negative).
- * @param stepNs - Added per retry attempt in nanoseconds (clamped non-negative).
- * @returns `BackoffStrategy` for {@link retry}.
- *
- * @example
- * ```ts
- * import { linear, retry, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * // Attempt 0 → 1 s, attempt 1 → 2 s, attempt 2 → 3 s …
- * const out = retry(source, { count: 4, backoff: linear(NS_PER_SEC) });
- * ```
- *
- * @category extra
- */
-declare function linear(baseNs: number, stepNs?: number): BackoffStrategy;
-type ExponentialBackoffOptions = {
-    baseNs?: number;
-    factor?: number;
-    maxDelayNs?: number;
-    jitter?: JitterMode;
-};
-/**
- * Builds exponential backoff in nanoseconds, capped by `maxDelayNs`, with optional jitter.
- *
- * @param options - Base, factor, cap, and jitter mode.
- * @returns `BackoffStrategy` for {@link retry}.
- *
- * @remarks
- * **Jitter:** `"full"` spreads delay across `[0, delay]`; `"equal"` uses `[delay/2, delay]`.
- *
- * @example
- * ```ts
- * import { exponential, retry, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * // 100 ms → 200 ms → 400 ms … capped at 30 s, with full jitter
- * const out = retry(source, {
- *   count: 5,
- *   backoff: exponential({ baseNs: 100 * NS_PER_SEC / 1000, jitter: "full" }),
- * });
- * ```
- *
- * @category extra
- */
-declare function exponential(options?: ExponentialBackoffOptions): BackoffStrategy;
-/**
- * Builds Fibonacci-scaled delays: `1, 2, 3, 5, … × baseNs`, capped at `maxDelayNs`.
- *
- * @param baseNs - Multiplier applied to the Fibonacci unit (default `100ms` in nanoseconds).
- * @param maxDelayNs - Upper bound in nanoseconds (default `30s`).
- * @returns `BackoffStrategy` for {@link retry}.
- *
- * @example
- * ```ts
- * import { fibonacci, retry, NS_PER_MS } from "@graphrefly/graphrefly-ts";
- *
- * // Delays: 100 ms, 200 ms, 300 ms, 500 ms, 800 ms … (× 100 ms base)
- * const out = retry(source, { count: 5, backoff: fibonacci(100 * NS_PER_MS) });
- * ```
- *
- * @category extra
- */
-declare function fibonacci(baseNs?: number, maxDelayNs?: number): BackoffStrategy;
-/**
- * Decorrelated jitter (AWS-recommended): `random(baseNs, min(maxNs, lastDelay * 3))`.
- *
- * Stateless — uses `prevDelayNs` (passed by the consumer) instead of closure state.
- * Safe to share across concurrent retry sequences.
- *
- * @param baseNs - Floor of the random range (default `100ms` in nanoseconds).
- * @param maxNs - Ceiling cap (default `30s` in nanoseconds).
- * @returns `BackoffStrategy` for {@link retry}.
- *
- * @example
- * ```ts
- * import { decorrelatedJitter, retry, NS_PER_MS, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * const out = retry(source, {
- *   count: 6,
- *   backoff: decorrelatedJitter(100 * NS_PER_MS, 10 * NS_PER_SEC),
- * });
- * ```
- *
- * @category extra
- */
-declare function decorrelatedJitter(baseNs?: number, maxNs?: number): BackoffStrategy;
-/**
- * Decorator that caps any strategy at `maxAttempts`. Returns `null` (stop retrying) after the cap.
- *
- * @param strategy - Inner strategy to wrap.
- * @param maxAttempts - Maximum number of attempts (inclusive).
- * @returns Wrapped `BackoffStrategy`.
- *
- * @example
- * ```ts
- * import { withMaxAttempts, exponential } from "@graphrefly/graphrefly-ts";
- *
- * const capped = withMaxAttempts(exponential(), 3);
- * capped(3); // null — no more retries beyond attempt 3
- * ```
- *
- * @category extra
- */
-declare function withMaxAttempts(strategy: BackoffStrategy, maxAttempts: number): BackoffStrategy;
-/**
- * Maps a preset name to a concrete {@link BackoffStrategy} with library-default parameters.
- *
- * @param name - One of `constant`, `linear`, `exponential`, `fibonacci`, or `decorrelatedJitter`.
- * @returns Configured strategy with default parameters.
- * @throws Error when `name` is not a known preset.
- *
- * @example
- * ```ts
- * import { resolveBackoffPreset, retry } from "@graphrefly/graphrefly-ts";
- *
- * const out = retry(source, { count: 3, backoff: resolveBackoffPreset("exponential") });
- * // Equivalent to retry(source, { count: 3, backoff: exponential() })
- * ```
- *
- * @category extra
- */
-declare function resolveBackoffPreset(name: BackoffPreset): BackoffStrategy;
-
-/**
- * Resilience utilities — roadmap §3.1 + §3.1c (retry, breaker, rate limit, status,
- * fallback, cache, timeout, budgetGate).
- */
-
-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>): Node<T>;
-declare function retry<T>(input: () => Node<T>, opts?: NodeOrValue<RetryFactoryOptions<T>>): Node<T>;
-type CircuitState = "closed" | "open" | "half-open";
-/**
- * Thrown when {@link withBreaker} is configured with `onOpen: "error"` and the breaker rejects work.
- *
- * @category extra
- */
-declare class CircuitOpenError extends Error {
-    name: string;
-    constructor();
-}
-interface CircuitBreakerOptions {
-    /** Number of consecutive failures before opening. Default: 5. */
-    failureThreshold?: number;
-    /** Base cooldown in nanoseconds before transitioning to half-open. Default: 30s. */
-    cooldownNs?: number;
-    /** Backoff strategy for cooldown escalation across consecutive open cycles. Overrides `cooldownNs` when provided. */
-    cooldown?: BackoffStrategy;
-    /** Max trial requests allowed in half-open state. Default: 1. */
-    halfOpenMax?: number;
-    /**
-     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
-     * (monotonically non-decreasing; suitable for elapsed-time arithmetic — never
-     * use `Date.now()` because wall-clock skew can flip elapsed math negative).
-     * Default: `monotonicNs` from `core/clock`. Override for deterministic tests.
-     */
-    now?: () => number;
-}
-interface CircuitBreaker {
-    /** Whether a request should be allowed through. Triggers open→half-open transition when cooldown expires. */
-    canExecute(): boolean;
-    /** Record a successful execution. Resets to closed. */
-    recordSuccess(): void;
-    /** Record a failed execution. May transition to open. */
-    recordFailure(error?: unknown): void;
-    /**
-     * Current circuit state (read-only, does not trigger transitions).
-     *
-     * **Telemetry:** wrap with {@link withBreaker} to surface this as a reactive
-     * `Node<CircuitState>` companion (`bundle.breakerState`) — every state
-     * transition (`closed`/`open`/`half-open`) emits to subscribers.
-     */
-    readonly state: CircuitState;
-    /** Number of consecutive failures in the current closed period. */
-    readonly failureCount: number;
-    /** Manually reset to closed state, clearing all counters. */
-    reset(): void;
-    /**
-     * Release the reactive-options subscription (Tier 6.5 3.2.4, 2026-04-29).
-     * No-op when constructed with static options. Call when retiring a
-     * breaker whose options came from a `Node<CircuitBreakerOptions>` to
-     * avoid leaking the option-Node subscription.
-     */
-    dispose(): void;
-}
-/**
- * Factory for a synchronous circuit breaker with `closed`, `open`, and `half-open` states.
- *
- * Supports escalating cooldown via an optional {@link BackoffStrategy} — each consecutive
- * open→half-open→open cycle increments the backoff attempt.
- *
- * @param options - Threshold, cooldown, half-open limit, and optional clock
- *   override; OR a `Node<CircuitBreakerOptions>` carrying the same shape
- *   reactively (Tier 6.5 3.2.4).
- * @returns {@link CircuitBreaker} instance.
- *
- * @remarks
- * **Timing:** Uses `monotonicNs()` by default (nanoseconds). Override `now` for tests.
- *
- * **Reactive options (locked semantics, Tier 6.5 3.2.4, 2026-04-29).**
- * When `options` is a `Node<CircuitBreakerOptions>`, the breaker
- * subscribes at construction and re-reads `failureThreshold` /
- * `cooldownNs` / `cooldown` / `halfOpenMax` / `now` on each DATA. **An
- * option swap RESETS the breaker to `"closed"`** with all counters
- * cleared — operators tuning a runaway breaker get a clean baseline.
- * If retaining failure history across re-tunings matters, derive a new
- * breaker per-tuning instead. Call `breaker.dispose()` when retiring to
- * release the option-Node subscription.
- *
- * @example
- * ```ts
- * import { circuitBreaker, exponential, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * const b = circuitBreaker({
- *   failureThreshold: 3,
- *   cooldown: exponential({ baseNs: 1 * NS_PER_SEC }),
- * });
- * ```
- *
- * @category extra
- */
-declare function circuitBreaker(options?: NodeOrValue<CircuitBreakerOptions>): CircuitBreaker;
-type WithBreakerBundle<T> = {
-    node: Node<T>;
-    breakerState: Node<CircuitState>;
-};
-/**
- * Returns a unary wrapper that gates upstream `DATA` through a {@link CircuitBreaker}.
- *
- * @param breaker - Shared breaker instance (typically one per resource).
- * @param options - `onOpen: "skip"` emits `RESOLVED` when open; `"error"` emits {@link CircuitOpenError}.
- * @returns Function mapping `Node<T>` to `{ node, breakerState }` companion nodes.
- *
- * @remarks
- * **Success path:** `COMPLETE` calls {@link CircuitBreaker.recordSuccess}. **Failure path:** upstream `ERROR` calls {@link CircuitBreaker.recordFailure} and is forwarded.
- *
- * **State telemetry:** `breakerState: Node<CircuitState>` is a reactive companion that mirrors `breaker.state` — every transition (`closed`/`open`/`half-open`) emits a `DATA`. Also accessible via `node.meta.breakerState` for `describe()` traversal.
- *
- * @example
- * ```ts
- * import { state, withBreaker, circuitBreaker } from "@graphrefly/graphrefly-ts";
- *
- * const b = circuitBreaker({ failureThreshold: 2 });
- * const s = state(1);
- * const { node, breakerState } = withBreaker(b)(s);
- * ```
- *
- * @category extra
- */
-declare function withBreaker<T>(breaker: CircuitBreaker, options?: {
-    onOpen?: "skip" | "error";
-    meta?: Record<string, unknown>;
-}): (source: Node<T>) => WithBreakerBundle<T>;
-interface TokenBucket {
-    /**
-     * Number of tokens currently available (after refill).
-     *
-     * **Float-valued.** When `refillPerSecond` is fractional (or `capacity` × elapsed-fraction
-     * yields a non-integer), the bucket accumulates fractional refill credit between
-     * `tryConsume`s. Consumers should not assume integer tokens — e.g. with
-     * `tokenBucket(10, 2.5)` after 100ms of elapsed time `available()` may report `0.25`.
-     */
-    available(): number;
-    /** Try to consume `cost` tokens. Returns `true` if successful. */
-    tryConsume(cost?: number): boolean;
-    /**
-     * Return `cost` tokens to the bucket (capped at capacity). Used when a
-     * multi-bucket admission fails partway — e.g., `adaptiveRateLimiter`
-     * consumes from an rpm bucket, then a tpm bucket; if tpm fails, call
-     * `rpmBucket.putBack(requestCost)` so the rpm slot isn't wasted.
-     * No-op for non-positive `cost`.
-     */
-    putBack(cost?: number): void;
-}
-/** Optional configuration for {@link tokenBucket}. */
-interface TokenBucketOptions {
-    /**
-     * Clock function returning **nanoseconds** with `monotonicNs()` semantics
-     * (monotonically non-decreasing). Default: `monotonicNs` from `core/clock`.
-     * Override for deterministic tests — eliminates the need for `vi.useFakeTimers`
-     * to drive token-refill scheduling.
-     */
-    clock?: () => number;
-}
-/**
- * Token-bucket meter (capacity + refill rate per second). Use with {@link rateLimiter} or custom gates.
- *
- * @param capacity - Maximum tokens (must be positive).
- * @param refillPerSecond - Tokens added per elapsed second (non-negative; may be fractional).
- * @param opts - Optional `clock` override for deterministic testing.
- * @returns {@link TokenBucket} instance.
- *
- * @remarks
- * **Float behavior:** the internal token counter is float-valued — fractional refill
- * accumulates between `tryConsume` calls. See {@link TokenBucket.available} for caveats.
- *
- * **Clock injection:** pass `opts.clock` to drive refill scheduling deterministically
- * in tests. The contract matches {@link circuitBreaker}'s `now` option: must return
- * `monotonicNs()`-style nanoseconds, never `Date.now()` (wall-clock skew breaks
- * elapsed math).
- *
- * @example
- * ```ts
- * import { tokenBucket } from "@graphrefly/graphrefly-ts";
- *
- * const bucket = tokenBucket(10, 2); // capacity 10, refill 2 tokens/sec
- * bucket.tryConsume(3); // true — 7 tokens remaining
- * bucket.available();   // ~7 (plus any elapsed refill — float-valued)
- *
- * // Deterministic test:
- * let t = 0;
- * const tb = tokenBucket(5, 1, { clock: () => t });
- * tb.tryConsume(5);    // exhausts
- * t = 1_000_000_000;   // advance 1s → +1 refill
- * tb.tryConsume(1);    // true
- * ```
- *
- * @category extra
- */
-declare function tokenBucket(capacity: number, refillPerSecond: number, opts?: TokenBucketOptions): TokenBucket;
-type RateLimiterOverflowPolicy = "drop-oldest" | "drop-newest" | "error";
-type RateLimiterOptions = {
-    /** Maximum `DATA` emissions per window (must be > 0). */
-    maxEvents: number;
-    /** Window length in nanoseconds (must be > 0). */
-    windowNs: number;
-    /**
-     * Cap on items queued while waiting for token refill.
-     *
-     * **Required.** Pass a finite positive integer (>= 1) for a bounded queue, OR
-     * the literal `Infinity` to opt in to an unbounded queue (caller acknowledges
-     * the unbounded-memory-growth risk on a high-rate source). Omitting this
-     * throws at construction time — the silent-unbounded-buffer footgun is the
-     * most common rateLimiter mis-configuration.
-     */
-    maxBuffer: number;
-    /** Overflow policy when `maxBuffer` is exceeded. Default: `"drop-newest"`. */
-    onOverflow?: RateLimiterOverflowPolicy;
-    /**
-     * Caller-supplied metadata merged into the produced node's `meta` (Tier 5.2
-     * D8 widening). Use {@link domainMeta} to tag the layer for `describe()` /
-     * mermaid grouping (e.g. `domainMeta("resilient", "rate-limit")`). The
-     * primitive's own `factoryTag("rateLimiter", opts)` and the `droppedCount`
-     * / `rateLimitState` companion seeds always win against caller-supplied
-     * keys so the audit trail can't be silently overwritten.
-     */
-    meta?: Record<string, unknown>;
-};
-/**
- * Thrown by {@link rateLimiter} when `onOverflow: "error"` and the pending buffer is full.
- *
- * @category extra
- */
-declare class RateLimiterOverflowError extends Error {
-    name: string;
-    constructor(maxBuffer: number);
-}
-/**
- * Combined runtime state surfaced by {@link rateLimiter} alongside `droppedCount`.
- * Tier 5.2 D7 widening — exposes pending-buffer occupancy and a `paused`
- * flag so consumers can render backpressure (UI), feed `lens.health`, or
- * gate downstream effects.
- */
-type RateLimiterState = {
-    /** Cumulative `DATA` items dropped due to overflow since this subscription cycle started. */
-    droppedCount: number;
-    /** Items currently buffered awaiting a token refill. `0` when the limiter is passing through. */
-    pendingCount: number;
-    /** `true` when at least one item is queued (the limiter is actively throttling). */
-    paused: boolean;
-};
-/** Bundle returned by {@link rateLimiter}. */
-type RateLimiterBundle<T> = {
-    /** The throttled stream — at most `maxEvents` `DATA` per `windowNs`. */
-    node: Node<T>;
-    /**
-     * Reactive companion: count of `DATA` items dropped since the producer
-     * activated.
-     *
-     * - Increments on every drop under any overflow policy (`drop-newest`,
-     *   `drop-oldest`). The `error` policy terminates the stream after a single
-     *   overflow, so `droppedCount` increments at most once in that path.
-     * - **Lifecycle scoping (qa A1 + EC7):** the counter retains its final
-     *   value through terminal (`COMPLETE` / `ERROR` / `TEARDOWN`) so consumers
-     *   see the final drop count, not zero. The closure-held counter resets to
-     *   `0` only when the producer fn re-runs — which only happens on a new
-     *   subscription cycle, and only if the producer was constructed with
-     *   `resubscribable: true`. The default `rateLimiter` producer is NOT
-     *   resubscribable, so a single producer-fn run is the typical lifetime.
-     * - Producer-pattern note: this companion is invisible to `describe()`
-     *   traversal from `node` (effect-mirror limitation; same shape as
-     *   `withBreaker.breakerState` and `withStatus.status`). Surface it via
-     *   `node.meta.droppedCount` if you need it in topology snapshots.
-     */
-    droppedCount: Node<number>;
-    /**
-     * Reactive companion: combined `{droppedCount, pendingCount, paused}` view.
-     *
-     * - `pendingCount` reflects the live buffer occupancy and updates on every
-     *   push / shift / overflow drop; `paused` is shorthand for
-     *   `pendingCount > 0`.
-     * - Equality-deduped — re-emits only when one of the three fields actually
-     *   changes (so a busy steady-state where every DATA passes immediately
-     *   produces one `paused: false` emission, not one per DATA).
-     * - **Lifecycle scoping (qa EC7):** same contract as `droppedCount` —
-     *   retains its final value through terminal; resets to the initial
-     *   `{droppedCount: 0, pendingCount: 0, paused: false}` only on a new
-     *   producer-fn run (resubscribable upstream required).
-     * - Same producer-pattern caveat as `droppedCount` re: `describe()` visibility.
-     */
-    rateLimitState: Node<RateLimiterState>;
-};
-/**
- * Token-bucket rate limiter: at most `maxEvents` `DATA` values per `windowNs`.
- *
- * Uses {@link tokenBucket} internally (capacity = `maxEvents`, refill = `maxEvents / windowSeconds`).
- * Excess items are queued FIFO (in a fixed-capacity {@link RingBuffer} for O(1) push/shift)
- * until a token is available. The queue is bounded by the **required** `maxBuffer` option
- * with a configurable overflow policy.
- *
- * @param source - Upstream node.
- * @param opts - Rate + bounded-buffer configuration. `maxBuffer` is required (use `Infinity` to opt in to unbounded).
- * @returns `{ node, droppedCount }` bundle. Subscribe to `node` for the throttled stream and to `droppedCount` for backpressure pressure.
- *
- * @throws {RangeError} when `maxEvents` / `windowNs` is non-positive, when `maxBuffer` is omitted, or when `maxBuffer` is a finite value < 1.
- *
- * @remarks
- * **Terminal:** `COMPLETE` / `ERROR` cancel the refill timer, drop the pending queue,
- * reset `droppedCount` to `0`, and propagate.
- *
- * @example
- * ```ts
- * import { rateLimiter, state, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * const src = state(0);
- * // Allow at most 5 DATA values per second; queue up to 100 excess items, drop newest beyond.
- * const { node: limited, droppedCount } = rateLimiter(src, {
- *   maxEvents: 5,
- *   windowNs: NS_PER_SEC,
- *   maxBuffer: 100,
- * });
- * droppedCount.subscribe(([m]) => console.log("dropped so far:", m[1]));
- * ```
- *
- * @category extra
- */
-declare function rateLimiter<T>(source: Node<T>, opts: NodeOrValue<RateLimiterOptions>): RateLimiterBundle<T>;
-type StatusValue = "pending" | "running" | "completed" | "errored";
-type WithStatusBundle<T> = {
-    node: Node<T>;
-    status: Node<StatusValue>;
-    error: Node<unknown | null>;
-};
-/**
- * Wraps `src` with `status` and `error` {@link state} companions for UI or meta snapshots.
- *
- * @param src - Upstream node to mirror.
- * @param options - `initialStatus` defaults to `"pending"`.
- * @returns `{ node, status, error }` where `out` is the mirrored stream, `status` is a
- *   reactive `Node<StatusValue>` (`"pending" | "running" | "completed" | "errored"`),
- *   and `error` holds the last `ERROR` payload (cleared to `null` on the next `DATA`
- *   after `errored`).
- *
- * @remarks
- * **Lifecycle:** `pending` (no DATA yet) → `running` (on first DATA) → `completed`
- * (on COMPLETE) or `errored` (on ERROR). After `errored`, the next `DATA` clears
- * `error` and re-enters `running` inside a {@link batch} so subscribers see one
- * consistent transition (matches graphrefly-py).
- *
- * **Producer-pattern visibility:** `out` is built via `node([], fn, …)`, so `src`
- * appears as the source dependency in `describe()` traversal but the `status` /
- * `error` companions are mirrored via subscribe-callback effects — they appear
- * under `out.meta.status` / `out.meta.error` (and as `<name>::__meta__::status`
- * paths in `describe()`) rather than as separate top-level edges. Subscribers
- * to `out` see the throttled DATA stream; `status` / `error` companions may not
- * appear as edges in `describe()` if no consumer subscribes to them (per
- * COMPOSITION-GUIDE §1, push-on-subscribe semantics).
- *
- * **Per-subscribe lifecycle (DF8, 2026-04-29 doc lock).** When the wrapped
- * source is `resubscribable: true` and multiple consumers attach in
- * sequence, each new subscription cycle re-runs the producer fn AND
- * re-emits the initial `pending` + `null` companion DATAs. Downstream
- * subscribers to the `status` / `error` companions see thrash:
- * `pending → running → completed → pending → running …`. This is the
- * intended fresh-cycle semantic (each subscription cycle reports its own
- * lifecycle); consumers that need a "stable" status across cycles should
- * derive a snapshot via a separate `state()` mirror rather than depending
- * on the per-cycle reset.
- *
- * @example
- * ```ts
- * import { withStatus, state } from "@graphrefly/graphrefly-ts";
- *
- * const src = state<number>(0);
- * const { node, status, error } = withStatus(src);
- *
- * status.subscribe((msgs) => console.log("status:", msgs));
- * src.down([[DATA, 42]]); // status → "running"
- * ```
- *
- * @category extra
- */
-declare function withStatus<T>(src: Node<T>, options?: {
-    initialStatus?: StatusValue;
-    meta?: Record<string, unknown>;
-}): WithStatusBundle<T>;
-/**
- * Thrown by {@link timeout} when no `DATA` arrives within the deadline.
- *
- * @category extra
- */
-declare class TimeoutError extends Error {
-    name: string;
-    constructor(ns: number);
-}
-/**
- * Either a literal value or a reactive Node carrying it. Mirrors
- * {@link FallbackInput}'s precedent for "options that may be reactive."
- *
- * Used by {@link timeout} / {@link retry} / {@link rateLimiter} /
- * {@link circuitBreaker} / {@link budgetGate} to accept reactive option
- * configurations (Tier 6.5 3.2, 2026-04-29). Each primitive subscribes
- * to the option Node via {@link resolveReactiveOption} and rebinds
- * internal state per its locked swap-semantic rule (see each primitive's
- * JSDoc for the rule).
- *
- * @category extra
- */
-type NodeOrValue<T> = T | Node<T>;
-/** Inputs accepted by {@link fallback}. */
-type FallbackInput<T> = T | Node<T> | PromiseLike<T> | AsyncIterable<T>;
-/**
- * On upstream terminal `ERROR`, switch to a fallback source instead of propagating the error.
- *
- * Accepts any of:
- * - **scalar value** — emits `[[DATA, fb], [COMPLETE]]`
- * - **`Node<T>`** — subscribes and forwards all messages (push-on-subscribe delivers current cache)
- * - **`Promise<T>` / thenable** — resolves into a one-shot `DATA` then `COMPLETE` (via {@link fromAny})
- * - **`AsyncIterable<T>`** — streams each yielded value as `DATA`, then `COMPLETE` (via {@link fromAny})
- *
- * Non-`Node` inputs are routed through {@link fromAny} so the fallback participates in the
- * reactive protocol uniformly. Bare strings, arrays, and other synchronous scalars are treated
- * as single values (NOT split into characters / elements) to avoid the `fromAny`-on-string
- * iteration gotcha.
- *
- * Composes naturally with {@link retry}:
- * `pipe(source, retry({count:3}), fallback("default"))`.
- *
- * @param source - Upstream node.
- * @param fb - Fallback value, node, promise, or async iterable.
- * @returns Node that replaces errors with the fallback.
- *
- * @example
- * ```ts
- * import { fallback, throwError } from "@graphrefly/graphrefly-ts";
- *
- * const safe = fallback(throwError(new Error("boom")), "default");
- * safe.cache; // "default" after subscribe
- * ```
- *
- * @category extra
- */
-declare function fallback<T>(source: Node<T>, fb: FallbackInput<T>, options?: {
-    meta?: Record<string, unknown>;
-}): Node<T>;
-/**
- * Emits `ERROR` with {@link TimeoutError} if no `DATA` arrives within the deadline.
- *
- * The timer starts on subscription and resets on each `DATA`. `DIRTY` does NOT reset
- * the timer. Terminal messages (`COMPLETE`/`ERROR`) cancel the timer.
- *
- * @param source - Upstream node.
- * @param timeoutNs - Deadline in **nanoseconds** (must be > 0), or a
- *   `Node<number>` carrying the deadline reactively (Tier 6.5 3.2.1).
- *   Internally converted to milliseconds for `setTimeout` scheduling.
- * @returns Node that errors on timeout.
- *
- * @throws {RangeError} when `timeoutNs <= 0`.
- *
- * @remarks
- * **Scheduling:** internally uses {@link ResettableTimer} (raw `setTimeout`) per spec §5.10's resilience-operator carve-out. The deadline is `timeoutNs / NS_PER_MS` ms; sub-millisecond `timeoutNs` values get the same minimum-1ms host-scheduler granularity that `setTimeout` provides.
- *
- * **Reactive `timeoutNs` (locked semantics, Tier 6.5 3.2.1, 2026-04-29).**
- * When `timeoutNs` is a `Node<number>`, each timer-(re)start reads the
- * latest value. An option swap mid-flight applies to the **next** timer
- * window (no in-flight reset) — the active timer keeps its original
- * deadline; the next DATA-driven `startTimer()` call reads the new
- * value. Static-form callers see no behavior change.
- *
- * @example
- * ```ts
- * import { timeout, never, NS_PER_SEC } from "@graphrefly/graphrefly-ts";
- *
- * const t = timeout(never(), 5 * NS_PER_SEC);
- * // After 5 seconds with no DATA: [[ERROR, TimeoutError]]
- * ```
- *
- * @category extra
- */
-declare function timeout<T>(source: Node<T>, timeoutNs: NodeOrValue<number>, options?: {
-    meta?: Record<string, unknown>;
-}): Node<T>;
-
-export { type BackoffPreset as B, type CircuitBreaker as C, type ExponentialBackoffOptions as E, type FallbackInput as F, type JitterMode as J, NS_PER_MS as N, type RateLimiterOptions as R, type StatusValue as S, TimeoutError as T, type WithBreakerBundle as W, type BackoffStrategy as a, type CircuitBreakerOptions as b, CircuitOpenError as c, type CircuitState as d, NS_PER_SEC as e, RateLimiterOverflowError as f, type RateLimiterOverflowPolicy as g, type RetryOptions as h, type TokenBucket as i, type WithStatusBundle as j, circuitBreaker as k, constant as l, decorrelatedJitter as m, exponential as n, fallback as o, fibonacci as p, linear as q, rateLimiter as r, resolveBackoffPreset as s, retry as t, timeout as u, tokenBucket as v, withBreaker as w, withMaxAttempts as x, withStatus as y };