@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/presets/resilience/index.d.cts

@@ -0,0 +1,205 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+import { N as NodeOrValue } from '../../_internal-B23BagFd.cjs';
+import { c as RetryState, b as RetryOptions } from '../../retry-DWuhjvsA.cjs';
+import { S as StatusValue } from '../../status-U-rUI79b.cjs';
+import { k as TimeoutState, h as RateLimiterState, e as RateLimiterOptions, B as BudgetConstraint, F as FallbackInput } from '../../rate-limiter-DpVbSYdH.cjs';
+import { B as BreakerState, a as CircuitBreakerOptions } from '../../breaker-ugSdq54q.cjs';
+import '../../backoff-Bnb9OoPh.cjs';
+
+/**
+ * Resilience composition with correct nesting order (roadmap §9.0b — Tier 5.2 Wave-B rebuild).
+ *
+ * {@link resilientPipeline} composes the resilience primitives from
+ * `extra/resilience/` in the canonical nesting order:
+ *
+ * ```text
+ *   rateLimit → budget → breaker → timeout → retry → fallback → status
+ * ```
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) with mounted
+ * intermediate nodes and per-layer status companions, replacing the prior
+ * bundle return. Each intermediate is mounted under a stable name so
+ * `pipeline.describe()` shows the resilience chain in topology snapshots,
+ * mermaid renders, and `lens.health` aggregations.
+ *
+ * **Per-attempt timeout vs. retry ordering.** `timeout` is applied BEFORE
+ * `retry` so each retry attempt resubscribes to a fresh deadline (per-attempt
+ * semantics). If `timeout` wrapped `retry`, a single deadline would apply to
+ * the entire retry chain — not what callers expect.
+ *
+ * **`breakerOnOpen` + `retry` interaction.** With `breakerOnOpen: "error"` AND
+ * `retry`, retry sees `CircuitOpenError` and resubscribes; the next attempt
+ * very likely also breaker-open → another error → retry burns its budget
+ * against an open circuit. Either set retry's `backoff` long enough for the
+ * breaker reset window OR keep the default `breakerOnOpen: "skip"` (emits
+ * RESOLVED when open; downstream drops the beat without retry firing).
+ *
+ * **Reactive options (switchMap rebuild).** Every primitive option accepts a
+ * `T | Node<T>` (precedent-aligned with `FallbackInput<T>`). When the caller
+ * supplies a static value, the layer is built once at construction. When the
+ * caller supplies a `Node<T>`, the pipeline subscribes via `switchMap` and
+ * **rebuilds the layer on every option emission** — the chain stalls until
+ * the option Node emits its first DATA. Each rebuild creates a fresh
+ * primitive instance, so internal state is lost (rate-limiter pending buffer,
+ * breaker failure count, retry attempt count, in-flight timeout). Per-layer
+ * **companion Nodes** (`droppedCount`, `rateLimitState`, `breakerState`) are
+ * therefore exposed ONLY for the static-options path. Primitive-side widening
+ * (filed in `docs/optimizations.md` under "Tier 5.2 follow-up — primitive-side
+ * reactive-options widening") will preserve internal state once it lands and
+ * the pipeline will trivially forward Node-form options to the primitive.
+ *
+ * @module
+ */
+
+/**
+ * Options for {@link resilientPipeline}. Every layer is optional — omit a
+ * field and that layer is skipped.
+ *
+ * Reactive (`Node<T>`) forms are accepted everywhere a primitive value would
+ * fit; the pipeline subscribes via `switchMap` and rebuilds the layer on each
+ * emission. See module JSDoc for the rebuild semantics + state-loss caveat.
+ */
+interface ResilientPipelineOptions<T> {
+    /**
+     * Admission control — at most `maxEvents` `DATA` per `windowNs`. See
+     * {@link rateLimiter}.
+     *
+     * `maxBuffer` is optional at the pipeline layer (defaults to `Infinity`,
+     * preserving the historical unbounded behavior). Pass an explicit positive
+     * integer to opt in to a bounded queue.
+     */
+    rateLimit?: NodeOrValue<Omit<RateLimiterOptions, "maxBuffer"> & {
+        maxBuffer?: number;
+    }>;
+    /** Cost/constraint gate. See {@link budgetGate}. */
+    budget?: NodeOrValue<ReadonlyArray<BudgetConstraint>>;
+    /** Circuit breaker — fail-fast when the downstream resource is unhealthy. See {@link circuitBreaker}. */
+    breaker?: NodeOrValue<CircuitBreakerOptions>;
+    /**
+     * Behavior when the breaker is open:
+     * - `"skip"` (default) — emit `RESOLVED` (lets downstream drop the beat).
+     * - `"error"` — emit a `CircuitOpenError` so `retry` / `fallback` can react.
+     *   See module JSDoc for the retry-budget burn caveat.
+     *
+     * Static (configuration-only — no reactive form).
+     */
+    breakerOnOpen?: "skip" | "error";
+    /** Retry policy on terminal `ERROR`. See {@link retry}. */
+    retry?: NodeOrValue<RetryOptions>;
+    /**
+     * Per-attempt deadline in milliseconds. Converted to ns internally. Omit
+     * to skip the timeout wrap.
+     *
+     * Specified in ms (not ns) because callers consistently think in
+     * millisecond deadlines; the underlying {@link timeout} primitive takes ns
+     * internally.
+     */
+    timeoutMs?: NodeOrValue<number>;
+    /** Final fallback value emitted on terminal `ERROR` after retry exhausts. See {@link fallback}. */
+    fallback?: FallbackInput<T>;
+    /**
+     * Initial status reported by the status node. Default `"pending"`. Static.
+     */
+    initialStatus?: StatusValue;
+    /** Wrapper graph name. Default `"resilient_pipeline"`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Graph subclass returned by {@link resilientPipeline}. Mounts each
+ * configured intermediate under a stable name and exposes per-layer status
+ * companions.
+ *
+ * @category patterns
+ */
+declare class ResilientPipelineGraph<T> extends Graph {
+    /**
+     * Final resilient node — subscribe to this for `DATA` emissions.
+     *
+     * Named `output` (not `node`) because `Graph.node(name)` already names the
+     * path-resolution method on the base class; a `readonly node` field would
+     * shadow it.
+     */
+    readonly output: Node<T>;
+    /** Live status: `"pending" | "running" | "completed" | "errored"`. */
+    readonly status: Node<StatusValue>;
+    /**
+     * Last error payload, or `null` when not errored.
+     *
+     * Named `lastError` (not `error`) because `Graph.error(name, err)` already
+     * names a method on the base class.
+     */
+    readonly lastError: Node<unknown | null>;
+    /** Breaker state when `opts.breaker` is provided; `undefined` otherwise. */
+    readonly breakerState: Node<BreakerState> | undefined;
+    /**
+     * Timeout state companion when `opts.timeoutMs` is supplied as a
+     * `Node<Partial<TimeoutOptions>>`-like form; `undefined` otherwise
+     * (DS-13.5.B forwarding contract — Node-form opts skip the switchMap
+     * rebuild and lift the primitive's lifecycle companion onto the
+     * pipeline bundle).
+     */
+    readonly timeoutState: Node<TimeoutState> | undefined;
+    /**
+     * Retry state companion when `opts.retry` is supplied as a
+     * `Node<RetryOptions>`-like form; `undefined` otherwise
+     * (DS-13.5.B forwarding contract).
+     */
+    readonly retryState: Node<RetryState> | undefined;
+    /**
+     * Drop-counter when `opts.rateLimit` is provided; `undefined` otherwise.
+     *
+     * **Lifetime note:** `droppedCount` retains its final value through
+     * terminal (`COMPLETE` / `ERROR` / `TEARDOWN`); the underlying counter
+     * resets to `0` only at the next subscription cycle.
+     */
+    readonly droppedCount: Node<number> | undefined;
+    /**
+     * Combined rate-limit state when `opts.rateLimit` is provided; `undefined`
+     * otherwise. Same lifecycle as {@link droppedCount} but exposes
+     * `pendingCount` and `paused` alongside the drop counter for richer
+     * backpressure observability (Tier 5.2 D7).
+     */
+    readonly rateLimitState: Node<RateLimiterState> | undefined;
+    constructor(source: Node<T>, opts?: ResilientPipelineOptions<T>);
+}
+/**
+ * Compose a resilient pipeline around `source` in the canonical nesting
+ * order — `rateLimit → budget → breaker → timeout → retry → fallback → status`.
+ * Omit any option to skip that layer.
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) —
+ * `pipeline.output` is the externally visible final node; `pipeline.status`
+ * / `pipeline.lastError` / `pipeline.breakerState` / `pipeline.droppedCount`
+ * are the per-layer companions. Call `pipeline.describe()` to see the
+ * mounted intermediates; compose with {@link graphLens}'s `health` for
+ * aggregate status.
+ *
+ * **Naming note:** `output` and `lastError` (not `node` / `error`) avoid
+ * clashes with `Graph.node(name)` and `Graph.error(name, err)` on the base
+ * class.
+ *
+ * @param source - Upstream node to wrap.
+ * @param opts - See {@link ResilientPipelineOptions}. All fields optional.
+ *
+ * @example
+ * ```ts
+ * const safeFetch = resilientPipeline(fetchNode, {
+ *   rateLimit: { maxEvents: 10, windowNs: NS_PER_SEC },
+ *   breaker: { failureThreshold: 5 },
+ *   retry: { count: 3, backoff: "exponential" },
+ *   timeoutMs: 10_000,
+ *   fallback: null,
+ * });
+ * safeFetch.output.subscribe(msgs => console.log(msgs));
+ * safeFetch.status.subscribe(msgs => console.log(msgs));
+ * graphSpecToAscii(safeFetch.describe()); // visualize the chain
+ * ```
+ *
+ * @category patterns
+ */
+declare function resilientPipeline<T>(source: Node<T>, opts?: ResilientPipelineOptions<T>): ResilientPipelineGraph<T>;
+
+export { ResilientPipelineGraph, type ResilientPipelineOptions, resilientPipeline };

package/dist/presets/resilience/index.d.ts

@@ -0,0 +1,205 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { Graph, GraphOptions } from '@graphrefly/pure-ts/graph';
+import { N as NodeOrValue } from '../../_internal-B23BagFd.js';
+import { c as RetryState, b as RetryOptions } from '../../retry-BDbRZ_gx.js';
+import { S as StatusValue } from '../../status-U-rUI79b.js';
+import { k as TimeoutState, h as RateLimiterState, e as RateLimiterOptions, B as BudgetConstraint, F as FallbackInput } from '../../rate-limiter-CEALq4N1.js';
+import { B as BreakerState, a as CircuitBreakerOptions } from '../../breaker-C9skL3d8.js';
+import '../../backoff-Bnb9OoPh.js';
+
+/**
+ * Resilience composition with correct nesting order (roadmap §9.0b — Tier 5.2 Wave-B rebuild).
+ *
+ * {@link resilientPipeline} composes the resilience primitives from
+ * `extra/resilience/` in the canonical nesting order:
+ *
+ * ```text
+ *   rateLimit → budget → breaker → timeout → retry → fallback → status
+ * ```
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) with mounted
+ * intermediate nodes and per-layer status companions, replacing the prior
+ * bundle return. Each intermediate is mounted under a stable name so
+ * `pipeline.describe()` shows the resilience chain in topology snapshots,
+ * mermaid renders, and `lens.health` aggregations.
+ *
+ * **Per-attempt timeout vs. retry ordering.** `timeout` is applied BEFORE
+ * `retry` so each retry attempt resubscribes to a fresh deadline (per-attempt
+ * semantics). If `timeout` wrapped `retry`, a single deadline would apply to
+ * the entire retry chain — not what callers expect.
+ *
+ * **`breakerOnOpen` + `retry` interaction.** With `breakerOnOpen: "error"` AND
+ * `retry`, retry sees `CircuitOpenError` and resubscribes; the next attempt
+ * very likely also breaker-open → another error → retry burns its budget
+ * against an open circuit. Either set retry's `backoff` long enough for the
+ * breaker reset window OR keep the default `breakerOnOpen: "skip"` (emits
+ * RESOLVED when open; downstream drops the beat without retry firing).
+ *
+ * **Reactive options (switchMap rebuild).** Every primitive option accepts a
+ * `T | Node<T>` (precedent-aligned with `FallbackInput<T>`). When the caller
+ * supplies a static value, the layer is built once at construction. When the
+ * caller supplies a `Node<T>`, the pipeline subscribes via `switchMap` and
+ * **rebuilds the layer on every option emission** — the chain stalls until
+ * the option Node emits its first DATA. Each rebuild creates a fresh
+ * primitive instance, so internal state is lost (rate-limiter pending buffer,
+ * breaker failure count, retry attempt count, in-flight timeout). Per-layer
+ * **companion Nodes** (`droppedCount`, `rateLimitState`, `breakerState`) are
+ * therefore exposed ONLY for the static-options path. Primitive-side widening
+ * (filed in `docs/optimizations.md` under "Tier 5.2 follow-up — primitive-side
+ * reactive-options widening") will preserve internal state once it lands and
+ * the pipeline will trivially forward Node-form options to the primitive.
+ *
+ * @module
+ */
+
+/**
+ * Options for {@link resilientPipeline}. Every layer is optional — omit a
+ * field and that layer is skipped.
+ *
+ * Reactive (`Node<T>`) forms are accepted everywhere a primitive value would
+ * fit; the pipeline subscribes via `switchMap` and rebuilds the layer on each
+ * emission. See module JSDoc for the rebuild semantics + state-loss caveat.
+ */
+interface ResilientPipelineOptions<T> {
+    /**
+     * Admission control — at most `maxEvents` `DATA` per `windowNs`. See
+     * {@link rateLimiter}.
+     *
+     * `maxBuffer` is optional at the pipeline layer (defaults to `Infinity`,
+     * preserving the historical unbounded behavior). Pass an explicit positive
+     * integer to opt in to a bounded queue.
+     */
+    rateLimit?: NodeOrValue<Omit<RateLimiterOptions, "maxBuffer"> & {
+        maxBuffer?: number;
+    }>;
+    /** Cost/constraint gate. See {@link budgetGate}. */
+    budget?: NodeOrValue<ReadonlyArray<BudgetConstraint>>;
+    /** Circuit breaker — fail-fast when the downstream resource is unhealthy. See {@link circuitBreaker}. */
+    breaker?: NodeOrValue<CircuitBreakerOptions>;
+    /**
+     * Behavior when the breaker is open:
+     * - `"skip"` (default) — emit `RESOLVED` (lets downstream drop the beat).
+     * - `"error"` — emit a `CircuitOpenError` so `retry` / `fallback` can react.
+     *   See module JSDoc for the retry-budget burn caveat.
+     *
+     * Static (configuration-only — no reactive form).
+     */
+    breakerOnOpen?: "skip" | "error";
+    /** Retry policy on terminal `ERROR`. See {@link retry}. */
+    retry?: NodeOrValue<RetryOptions>;
+    /**
+     * Per-attempt deadline in milliseconds. Converted to ns internally. Omit
+     * to skip the timeout wrap.
+     *
+     * Specified in ms (not ns) because callers consistently think in
+     * millisecond deadlines; the underlying {@link timeout} primitive takes ns
+     * internally.
+     */
+    timeoutMs?: NodeOrValue<number>;
+    /** Final fallback value emitted on terminal `ERROR` after retry exhausts. See {@link fallback}. */
+    fallback?: FallbackInput<T>;
+    /**
+     * Initial status reported by the status node. Default `"pending"`. Static.
+     */
+    initialStatus?: StatusValue;
+    /** Wrapper graph name. Default `"resilient_pipeline"`. */
+    name?: string;
+    /** Wrapper graph options. */
+    graph?: GraphOptions;
+}
+/**
+ * Graph subclass returned by {@link resilientPipeline}. Mounts each
+ * configured intermediate under a stable name and exposes per-layer status
+ * companions.
+ *
+ * @category patterns
+ */
+declare class ResilientPipelineGraph<T> extends Graph {
+    /**
+     * Final resilient node — subscribe to this for `DATA` emissions.
+     *
+     * Named `output` (not `node`) because `Graph.node(name)` already names the
+     * path-resolution method on the base class; a `readonly node` field would
+     * shadow it.
+     */
+    readonly output: Node<T>;
+    /** Live status: `"pending" | "running" | "completed" | "errored"`. */
+    readonly status: Node<StatusValue>;
+    /**
+     * Last error payload, or `null` when not errored.
+     *
+     * Named `lastError` (not `error`) because `Graph.error(name, err)` already
+     * names a method on the base class.
+     */
+    readonly lastError: Node<unknown | null>;
+    /** Breaker state when `opts.breaker` is provided; `undefined` otherwise. */
+    readonly breakerState: Node<BreakerState> | undefined;
+    /**
+     * Timeout state companion when `opts.timeoutMs` is supplied as a
+     * `Node<Partial<TimeoutOptions>>`-like form; `undefined` otherwise
+     * (DS-13.5.B forwarding contract — Node-form opts skip the switchMap
+     * rebuild and lift the primitive's lifecycle companion onto the
+     * pipeline bundle).
+     */
+    readonly timeoutState: Node<TimeoutState> | undefined;
+    /**
+     * Retry state companion when `opts.retry` is supplied as a
+     * `Node<RetryOptions>`-like form; `undefined` otherwise
+     * (DS-13.5.B forwarding contract).
+     */
+    readonly retryState: Node<RetryState> | undefined;
+    /**
+     * Drop-counter when `opts.rateLimit` is provided; `undefined` otherwise.
+     *
+     * **Lifetime note:** `droppedCount` retains its final value through
+     * terminal (`COMPLETE` / `ERROR` / `TEARDOWN`); the underlying counter
+     * resets to `0` only at the next subscription cycle.
+     */
+    readonly droppedCount: Node<number> | undefined;
+    /**
+     * Combined rate-limit state when `opts.rateLimit` is provided; `undefined`
+     * otherwise. Same lifecycle as {@link droppedCount} but exposes
+     * `pendingCount` and `paused` alongside the drop counter for richer
+     * backpressure observability (Tier 5.2 D7).
+     */
+    readonly rateLimitState: Node<RateLimiterState> | undefined;
+    constructor(source: Node<T>, opts?: ResilientPipelineOptions<T>);
+}
+/**
+ * Compose a resilient pipeline around `source` in the canonical nesting
+ * order — `rateLimit → budget → breaker → timeout → retry → fallback → status`.
+ * Omit any option to skip that layer.
+ *
+ * Returns a {@link ResilientPipelineGraph} (Graph subclass) —
+ * `pipeline.output` is the externally visible final node; `pipeline.status`
+ * / `pipeline.lastError` / `pipeline.breakerState` / `pipeline.droppedCount`
+ * are the per-layer companions. Call `pipeline.describe()` to see the
+ * mounted intermediates; compose with {@link graphLens}'s `health` for
+ * aggregate status.
+ *
+ * **Naming note:** `output` and `lastError` (not `node` / `error`) avoid
+ * clashes with `Graph.node(name)` and `Graph.error(name, err)` on the base
+ * class.
+ *
+ * @param source - Upstream node to wrap.
+ * @param opts - See {@link ResilientPipelineOptions}. All fields optional.
+ *
+ * @example
+ * ```ts
+ * const safeFetch = resilientPipeline(fetchNode, {
+ *   rateLimit: { maxEvents: 10, windowNs: NS_PER_SEC },
+ *   breaker: { failureThreshold: 5 },
+ *   retry: { count: 3, backoff: "exponential" },
+ *   timeoutMs: 10_000,
+ *   fallback: null,
+ * });
+ * safeFetch.output.subscribe(msgs => console.log(msgs));
+ * safeFetch.status.subscribe(msgs => console.log(msgs));
+ * graphSpecToAscii(safeFetch.describe()); // visualize the chain
+ * ```
+ *
+ * @category patterns
+ */
+declare function resilientPipeline<T>(source: Node<T>, opts?: ResilientPipelineOptions<T>): ResilientPipelineGraph<T>;
+
+export { ResilientPipelineGraph, type ResilientPipelineOptions, resilientPipeline };

package/dist/presets/resilience/index.js

@@ -0,0 +1,18 @@
+import "../../chunk-KRNQ6RGQ.js";
+import {
+  ResilientPipelineGraph,
+  resilientPipeline
+} from "../../chunk-6XZYT4SW.js";
+import "../../chunk-RJOG4IJU.js";
+import "../../chunk-RAGGHLCV.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-Y52CS6YA.js";
+import "../../chunk-Z4YXAUDN.js";
+import "../../chunk-TSBFTJKM.js";
+import "../../chunk-P5LBT622.js";
+import "../../chunk-AZDQPQ3V.js";
+export {
+  ResilientPipelineGraph,
+  resilientPipeline
+};
+//# sourceMappingURL=index.js.map

package/dist/presets/resilience/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}