@graphrefly/graphrefly 0.40.0 → 0.42.0

package/dist/index-D1Gc7wV5.d.ts

@@ -1,230 +0,0 @@
-import { f as factoryTag, p as placeholderArgs } from './meta-D8OyedKp.js';
-import { N as Node } from './node-BYInONRr.js';
-import { S as StatusValue, C as CircuitState, R as RateLimiterState, a as RateLimiterOptions, b as CircuitBreakerOptions, c as RetryOptions, F as FallbackInput, N as NS_PER_MS, d as NS_PER_SEC } from './index-BAQrjuZF.js';
-import { G as Graph, a as GraphOptions } from './graph-BkIkog4h.js';
-import { B as BudgetConstraint } from './budget-gate-CmmVtasH.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
- */
-
-/**
- * `T | Node<T>` for primitive options — precedent-aligned with
- * {@link FallbackInput} and `policyGate.policies`. 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 {@link switchMap}: the
- * layer is rebuilt on every option emission. **State-loss caveat:** each
- * rebuild creates a fresh primitive instance — `rateLimiter` loses its pending
- * buffer, `circuitBreaker` resets failure count, `retry` resets attempt
- * count, `timeout` cancels in-flight deadline. This is the documented
- * switchMap-pattern semantics; primitive-side widening (filed in
- * `docs/optimizations.md`) will preserve internal state once it lands and the
- * pipeline can forward Node-form options directly.
- *
- * Per-layer **companion Nodes** (`droppedCount`, `rateLimitState`,
- * `breakerState`) are exposed only for the static-options path — Node-form
- * leaves them as `undefined` because each rebuild creates new companion
- * instances and a switchMap-mirrored companion would track only the latest
- * bundle. Callers needing both reactive options AND companions wait for
- * primitive-side widening.
- */
-type NodeOrValue<T> = T | Node<T>;
-/**
- * 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<CircuitState> | 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));
- * safeFetch.describe({ format: "ascii" }); // visualize the chain
- * ```
- *
- * @category patterns
- */
-declare function resilientPipeline<T>(source: Node<T>, opts?: ResilientPipelineOptions<T>): ResilientPipelineGraph<T>;
-
-declare const index_BudgetConstraint: typeof BudgetConstraint;
-declare const index_CircuitBreakerOptions: typeof CircuitBreakerOptions;
-declare const index_CircuitState: typeof CircuitState;
-declare const index_FallbackInput: typeof FallbackInput;
-declare const index_NS_PER_MS: typeof NS_PER_MS;
-declare const index_NS_PER_SEC: typeof NS_PER_SEC;
-type index_NodeOrValue<T> = NodeOrValue<T>;
-declare const index_RateLimiterOptions: typeof RateLimiterOptions;
-declare const index_RateLimiterState: typeof RateLimiterState;
-type index_ResilientPipelineGraph<T> = ResilientPipelineGraph<T>;
-declare const index_ResilientPipelineGraph: typeof ResilientPipelineGraph;
-type index_ResilientPipelineOptions<T> = ResilientPipelineOptions<T>;
-declare const index_RetryOptions: typeof RetryOptions;
-declare const index_StatusValue: typeof StatusValue;
-declare const index_factoryTag: typeof factoryTag;
-declare const index_placeholderArgs: typeof placeholderArgs;
-declare const index_resilientPipeline: typeof resilientPipeline;
-declare namespace index {
-  export { index_BudgetConstraint as BudgetConstraint, index_CircuitBreakerOptions as CircuitBreakerOptions, index_CircuitState as CircuitState, index_FallbackInput as FallbackInput, index_NS_PER_MS as NS_PER_MS, index_NS_PER_SEC as NS_PER_SEC, type index_NodeOrValue as NodeOrValue, index_RateLimiterOptions as RateLimiterOptions, index_RateLimiterState as RateLimiterState, index_ResilientPipelineGraph as ResilientPipelineGraph, type index_ResilientPipelineOptions as ResilientPipelineOptions, index_RetryOptions as RetryOptions, index_StatusValue as StatusValue, index_factoryTag as factoryTag, index_placeholderArgs as placeholderArgs, index_resilientPipeline as resilientPipeline };
-}
-
-export { type NodeOrValue as N, ResilientPipelineGraph as R, type ResilientPipelineOptions as a, index as i, resilientPipeline as r };

package/dist/index-N2MAxt7_.d.ts

@@ -1,128 +0,0 @@
-import { N as Node } from './node-BYInONRr.js';
-import { b as GraphDescribeOutput, G as Graph } from './graph-BkIkog4h.js';
-import { w as watchTopologyTree } from './topology-tree-mF7Emqzm.js';
-
-/**
- * Reactive graph observability preset (Tier 5.3 reshape — Session A.4 lock).
- *
- * `graphLens(target)` is a thin compositor (~30 LOC of glue) over two
- * already-shipped reactive primitives:
- *
- * - `target.describe({ reactive: true })` — live topology snapshot.
- * - `target.observe({ reactive: true, tiers: ["data"] })` — coalesced data
- *   changesets per outermost batch flush.
- *
- * It returns three Nodes plus a dispose function:
- *
- * - `topology: Node<GraphDescribeOutput>` — the live describe snapshot,
- *   re-emitting on every settle of the target tree (structural change,
- *   error/complete/teardown transition).
- * - `health: Node<HealthReport>` — `{ok, problems[]}` aggregated from the
- *   live describe; `ok=false` when any node enters `"errored"` status,
- *   with `upstreamCause` walked backward through deps.
- * - `flow: Node<ReadonlyMap<string, FlowEntry>>` — per-path DATA counters
- *   accumulating as `target.observe({reactive: true, tiers: ["data"]})`
- *   delivers changesets. The map is reconciled against `topology` on each
- *   topology change so removed nodes drop their entries.
- *
- * Pre-Tier-5.3 shipped a `LensGraph` class with `stats` / `health` / `flow`
- * (as a `ReactiveMapBundle`) / `why(from, to)` / `flowEntryNode(...)`. The
- * surface collapsed because every concern was already a one-liner over
- * `describe({reactive:true})` + `observe({reactive:true, tiers})` once those
- * landed in Tier 1.5.1 / 1.5.2 — the class added no protocol-level concept,
- * just glue. Callers who need topology stats compose a derived over
- * `topology` directly; callers who need a causal chain call
- * `target.explain(from, to, { reactive: true })`.
- *
- * The transitive topology-subscription helper {@link watchTopologyTree} is
- * re-exported here for downstream factories that need full-tree dynamic
- * coverage without taking a dep on `graph/`.
- *
- * @module
- */
-
-/** A single health problem entry. */
-interface HealthProblem {
-    path: string;
-    /** V1 only reports `"errored"`. Future versions may add `"completed"`, `"disconnected"`. */
-    status: "errored";
-    /** First errored upstream ancestor along the dep chain, when one exists and is distinct from `path`. */
-    upstreamCause?: string;
-}
-/** Aggregate health snapshot. `ok=true` iff `problems.length === 0`. */
-interface HealthReport {
-    ok: boolean;
-    problems: readonly HealthProblem[];
-}
-/** Per-path flow entry stored in the {@link GraphLensView.flow} map. */
-interface FlowEntry {
-    path: string;
-    /** Cumulative DATA emissions observed since the lens activated. */
-    count: number;
-    /** Monotonic ns at the most recent DATA emission for this path, or `null` if none yet. */
-    lastUpdate_ns: number | null;
-}
-/** Output of {@link graphLens}. */
-interface GraphLensView {
-    /** Live describe snapshot. Re-emits on structural change AND status transitions. */
-    topology: Node<GraphDescribeOutput>;
-    /** Live `{ok, problems[]}`. Aggregated from `topology`; equality-deduped. */
-    health: Node<HealthReport>;
-    /** Per-path DATA counter map. Re-emits per outermost batch flush. */
-    flow: Node<ReadonlyMap<string, FlowEntry>>;
-    /**
-     * Tear down the underlying `describe({reactive:true})` subscription.
-     * The `flow` node activates lazily; subscribing-then-unsubscribing reclaims
-     * its observe stream automatically. Call `dispose()` once when finished.
-     */
-    dispose(): void;
-}
-/** Build a `HealthReport` from a fresh `GraphDescribeOutput`. */
-declare function computeHealthReport(described: GraphDescribeOutput): HealthReport;
-/** Structural equality for {@link HealthReport} — used as the `health` derived's `equals`. */
-declare function healthReportEqual(a: HealthReport, b: HealthReport): boolean;
-/**
- * Reactive observability preset over a target {@link Graph}.
- *
- * @param target - The graph to observe.
- *
- * @example
- * ```ts
- * const g = new Graph("app");
- * g.add(state(0, { name: "counter" }), { name: "counter" });
- *
- * const lens = graphLens(g);
- * lens.topology.subscribe((msgs) => console.log("topology:", msgs));
- * lens.health.subscribe((msgs) => console.log("health:", msgs));
- * lens.flow.subscribe((msgs) => {
- *   for (const [type, payload] of msgs) {
- *     if (type === DATA) console.log("flow map size:", (payload as ReadonlyMap<string, FlowEntry>).size);
- *   }
- * });
- *
- * // Causal chains: use the underlying primitive directly — `graphLens` no
- * // longer wraps it, since `graph.explain({ reactive: true })` already
- * // provides everything the old `lens.why()` did.
- * const why = g.explain("counter", "consumer", { reactive: true });
- *
- * // Tear down when done.
- * lens.dispose();
- * ```
- *
- * @category observability
- */
-declare function graphLens(target: Graph): GraphLensView;
-
-type index_FlowEntry = FlowEntry;
-type index_GraphLensView = GraphLensView;
-type index_HealthProblem = HealthProblem;
-type index_HealthReport = HealthReport;
-declare const index_computeHealthReport: typeof computeHealthReport;
-declare const index_graphLens: typeof graphLens;
-declare const index_healthReportEqual: typeof healthReportEqual;
-declare const index_watchTopologyTree: typeof watchTopologyTree;
-declare namespace index {
-  export { type index_FlowEntry as FlowEntry, type index_GraphLensView as GraphLensView, type index_HealthProblem as HealthProblem, type index_HealthReport as HealthReport, index_computeHealthReport as computeHealthReport, index_graphLens as graphLens, index_healthReportEqual as healthReportEqual, index_watchTopologyTree as watchTopologyTree };
-}
-
-export { type FlowEntry as F, type GraphLensView as G, type HealthProblem as H, type HealthReport as a, computeHealthReport as c, graphLens as g, healthReportEqual as h, index as i };