@graphrefly/graphrefly 0.27.0 → 0.29.0

package/dist/resilience-CBfYJW5C.d.ts

@@ -0,0 +1,493 @@
+import { a as Node } from './node-Dd6wHSib.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;
+
+type RetryOptions = {
+    /** Max retry attempts after each terminal `ERROR` (not counting the first failure). */
+    count?: number;
+    /** Delay between attempts; strategies use **nanoseconds**. */
+    backoff?: BackoffStrategy | BackoffPreset;
+};
+/**
+ * Resubscribes to the upstream node after each terminal `ERROR`, after an optional delay.
+ *
+ * @param source - Upstream node (should use `resubscribable: true`).
+ * @param opts - `count` caps attempts; `backoff` supplies delay in **nanoseconds** (or a preset name).
+ * @returns Node that retries on error.
+ *
+ * @remarks
+ * **Resubscribable sources:** The upstream should use `resubscribable: true` if it must emit again after `ERROR`.
+ * **Protocol:** Forwards unknown message tuples unchanged; handles `DIRTY`, `DATA`, `RESOLVED`, `COMPLETE`, `ERROR`.
+ *
+ * @example
+ * ```ts
+ * import { ERROR, NS_PER_SEC, pipe, 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) });
+ * ```
+ *
+ * @category extra
+ */
+declare function retry<T>(source: Node<T>, opts?: RetryOptions): Node<T>;
+/**
+ * Options for {@link retrySource}. Superset of {@link RetryOptions} with an
+ * optional `initial` forwarded to the outer node cache.
+ *
+ * @category extra
+ */
+type RetrySourceOptions<T> = RetryOptions & {
+    /** Initial cache value for the outer node (forwarded to `NodeOptions.initial`). */
+    initial?: T;
+};
+/**
+ * Fresh-instance variant of {@link retry}: invokes the `factory` to build a
+ * new `Node<T>` on every connect / reconnect. Unlike {@link retry}, which
+ * re-subscribes to the same node (requiring `resubscribable: true`), this
+ * creates a new source per attempt — ideal for producers that capture
+ * per-attempt resources (sockets, clients, file handles) that become unusable
+ * after an error.
+ *
+ * Synchronous exceptions thrown by `factory` are treated as terminal ERROR
+ * and run through the same retry pipeline as inner-node ERROR.
+ *
+ * @param factory - Called to build a fresh source per attempt.
+ * @param opts - `count` caps attempts; `backoff` supplies delay (ns) or preset.
+ * @returns Node that retries by rebuilding the source.
+ *
+ * @example
+ * ```ts
+ * import { NS_PER_SEC, exponential, retrySource, fromWebSocket } from "@graphrefly/graphrefly-ts";
+ *
+ * // Each reconnect opens a fresh WebSocket:
+ * const connected$ = retrySource(
+ *   () => fromWebSocket(new WebSocket("wss://example/stream")),
+ *   { count: 10, backoff: exponential({ baseNs: 1 * NS_PER_SEC }) },
+ * );
+ * ```
+ *
+ * @category extra
+ */
+declare function retrySource<T>(factory: () => Node<T>, opts?: RetrySourceOptions<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 (for testability). Default: `monotonicNs`. */
+    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). */
+    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;
+}
+/**
+ * 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.
+ * @returns {@link CircuitBreaker} instance.
+ *
+ * @remarks
+ * **Timing:** Uses `monotonicNs()` by default (nanoseconds). Override `now` for tests.
+ *
+ * @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?: 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.
+ *
+ * @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";
+}): (source: Node<T>) => WithBreakerBundle<T>;
+interface TokenBucket {
+    /** Number of tokens currently available (after refill). */
+    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;
+}
+/**
+ * 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).
+ * @returns {@link TokenBucket} instance.
+ *
+ * @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)
+ * ```
+ *
+ * @category extra
+ */
+declare function tokenBucket(capacity: number, refillPerSecond: number): 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 (must be >= 1). Unbounded if omitted. */
+    maxBuffer?: number;
+    /** Overflow policy when `maxBuffer` is exceeded. Default: `"drop-newest"`. */
+    onOverflow?: RateLimiterOverflowPolicy;
+};
+/**
+ * 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);
+}
+/**
+ * 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 until a token is available. The queue may be bounded via
+ * `maxBuffer` with a configurable overflow policy.
+ *
+ * @param source - Upstream node.
+ * @param opts - Rate + optional bounded-buffer configuration.
+ * @returns Node that emits DATA at most `maxEvents` per `windowNs`.
+ *
+ * @remarks
+ * **Terminal:** `COMPLETE` / `ERROR` cancel the refill timer, drop the pending queue, 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 limited = rateLimiter(src, { maxEvents: 5, windowNs: NS_PER_SEC, maxBuffer: 100 });
+ * ```
+ *
+ * @category extra
+ */
+declare function rateLimiter<T>(source: Node<T>, opts: RateLimiterOptions): Node<T>;
+type StatusValue = "pending" | "active" | "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 `error` holds the last `ERROR` payload.
+ *
+ * @remarks
+ * **Recovery:** After `errored`, the next `DATA` clears `error` and sets `active` inside {@link batch} (matches graphrefly-py).
+ *
+ * @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 → "active"
+ * ```
+ *
+ * @category extra
+ */
+declare function withStatus<T>(src: Node<T>, options?: {
+    initialStatus?: StatusValue;
+}): 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);
+}
+/** 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>): 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.
+ * @returns Node that errors on timeout.
+ *
+ * @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: number): Node<T>;
+
+export { withStatus as A, type BackoffPreset as B, type CircuitState 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 CircuitBreakerOptions as a, type RetryOptions as b, NS_PER_SEC as c, type BackoffStrategy as d, type CircuitBreaker as e, CircuitOpenError as f, RateLimiterOverflowError as g, type RateLimiterOverflowPolicy as h, type RetrySourceOptions as i, type TokenBucket as j, type WithStatusBundle as k, circuitBreaker as l, constant as m, decorrelatedJitter as n, exponential as o, fallback as p, fibonacci as q, linear as r, rateLimiter as s, resolveBackoffPreset as t, retry as u, retrySource as v, timeout as w, tokenBucket as x, withBreaker as y, withMaxAttempts as z };

package/dist/resilience-XRUF267O.js

@@ -0,0 +1 @@
+import{a,b,c,d,e,f,g,h,i,j,k,l}from"./chunk-OL33ZI6R.js";import"./chunk-ESMPEKEV.js";import"./chunk-4VVTGLXJ.js";import"./chunk-KASHOCF5.js";import"./chunk-W4TSQ6RJ.js";import"./chunk-CK2E7BTU.js";import"./chunk-QYADASLV.js";export{c as CircuitOpenError,g as RateLimiterOverflowError,j as TimeoutError,d as circuitBreaker,k as fallback,h as rateLimiter,a as retry,b as retrySource,l as timeout,f as tokenBucket,e as withBreaker,i as withStatus};