@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/breaker-ugSdq54q.d.cts

@@ -0,0 +1,175 @@
+import { Node } from '@graphrefly/pure-ts/core';
+import { N as NodeOrValue } from './_internal-B23BagFd.cjs';
+import { B as BackoffStrategy } from './backoff-Bnb9OoPh.cjs';
+
+/**
+ * Central gate-state vocabulary for resilience primitives.
+ *
+ * **DS-13.5.B follow-on (locked 2026-05-01).** Two-state base enum
+ * (`"open" | "closed"`) used as the literal vocabulary inside
+ * gate-shaped `<Primitive>State` companions on `budgetGate`. Other
+ * primitives extend this base with primitive-specific values:
+ *
+ * - `rateLimiter` → `GateState | "throttled"`.
+ * - `circuitBreaker` → `GateState | "half-open"`.
+ *
+ * Keeping the base as a separate exported type lets callers narrow
+ * generic gate-state consumers without coupling to any one primitive's
+ * extension axis.
+ *
+ * @category extra/resilience
+ */
+type GateState = "open" | "closed";
+
+/**
+ * Circuit breaker — open/half-open/closed state machine + companion bundle.
+ *
+ * - {@link circuitBreaker} returns a synchronous breaker handle (counters,
+ *   state machine, optional reactive-options subscription).
+ * - {@link withBreaker} wraps a `Node<T>` and surfaces a reactive
+ *   `Node<CircuitState>` companion (`bundle.breakerState`) for telemetry.
+ */
+
+type CircuitState = "closed" | "open" | "half-open";
+/**
+ * Lifecycle-shaped state companion emitted by {@link withBreaker}
+ * (DS-13.5.B, locked 2026-05-01). Pre-1.0 break vs the prior
+ * `Node<CircuitState>` (string-only) shape.
+ *
+ * `status` extends {@link GateState} with `"half-open"`. The numeric
+ * fields surface the breaker's full internal state for telemetry and
+ * `describe()` traversal.
+ *
+ * @category extra/resilience
+ */
+interface BreakerState {
+    readonly status: GateState | "half-open";
+    readonly failureCount: number;
+    readonly openCycle: number;
+    readonly lastOpenedAtNs: number;
+    readonly halfOpenAttempts: number;
+    readonly lastCooldownNs: number;
+}
+/**
+ * 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<BreakerState>;
+};
+/**
+ * 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>;
+
+export { type BreakerState as B, type CircuitBreaker as C, type GateState as G, type WithBreakerBundle as W, type CircuitBreakerOptions as a, CircuitOpenError as b, type CircuitState as c, circuitBreaker as d, withBreaker as w };

package/dist/{cascading-BglDkMdX.d.cts → cascading-CSSbKGrJ.d.ts}

@@ -1,5 +1,5 @@
-import { L as LLMAdapter, C as ChatMessage, a as LLMInvokeOptions } from './types-C0_yquda.cjs';
-import { b as CircuitBreakerOptions, C as CircuitBreaker } from './index-C1T3d7V-.cjs';
+import { L as LLMAdapter, a as ChatMessage, b as LLMInvokeOptions } from './types-BB5Lw-pB.js';
+import { a as CircuitBreakerOptions, C as CircuitBreaker } from './breaker-C9skL3d8.js';
 
 /**
  * OpenAICompatAdapter — default fetch-backed, optional SDK-backed.
@@ -196,4 +196,4 @@ declare function tier(name: string, adapter: LLMAdapter, opts?: {
     filter?: AdapterTier["filter"];
 }): AdapterTier;
 
-export { type AdapterProvider as A, type CascadingLlmAdapterOptions as C, type OpenAICompatAdapterOptions as O, type CascadeExhaustionReport as a, type AdapterTier as b, createAdapter as c, AllTiersExhaustedError as d, type CreateAdapterOptions as e, type OpenAICompatPreset as f, type OpenAISdkLike as g, cascadingLlmAdapter as h, openAICompatAdapter as o, tier as t };
+export { type AdapterProvider as A, type CascadeExhaustionReport as C, type OpenAICompatAdapterOptions as O, type AdapterTier as a, AllTiersExhaustedError as b, type CascadingLlmAdapterOptions as c, type CreateAdapterOptions as d, type OpenAICompatPreset as e, type OpenAISdkLike as f, cascadingLlmAdapter as g, createAdapter as h, openAICompatAdapter as o, tier as t };

package/dist/{cascading-MFgxu7Yo.d.ts → cascading-baGkiihI.d.cts}

@@ -1,5 +1,5 @@
-import { L as LLMAdapter, C as ChatMessage, a as LLMInvokeOptions } from './types-CWFysE9E.js';
-import { b as CircuitBreakerOptions, C as CircuitBreaker } from './index-B1F8Enjf.js';
+import { L as LLMAdapter, a as ChatMessage, b as LLMInvokeOptions } from './types-BB5Lw-pB.cjs';
+import { a as CircuitBreakerOptions, C as CircuitBreaker } from './breaker-ugSdq54q.cjs';
 
 /**
  * OpenAICompatAdapter — default fetch-backed, optional SDK-backed.
@@ -196,4 +196,4 @@ declare function tier(name: string, adapter: LLMAdapter, opts?: {
     filter?: AdapterTier["filter"];
 }): AdapterTier;
 
-export { type AdapterProvider as A, type CascadingLlmAdapterOptions as C, type OpenAICompatAdapterOptions as O, type CascadeExhaustionReport as a, type AdapterTier as b, createAdapter as c, AllTiersExhaustedError as d, type CreateAdapterOptions as e, type OpenAICompatPreset as f, type OpenAISdkLike as g, cascadingLlmAdapter as h, openAICompatAdapter as o, tier as t };
+export { type AdapterProvider as A, type CascadeExhaustionReport as C, type OpenAICompatAdapterOptions as O, type AdapterTier as a, AllTiersExhaustedError as b, type CascadingLlmAdapterOptions as c, type CreateAdapterOptions as d, type OpenAICompatPreset as e, type OpenAISdkLike as f, cascadingLlmAdapter as g, createAdapter as h, openAICompatAdapter as o, tier as t };

package/dist/chunk-255UCBG4.js

@@ -0,0 +1,58 @@
+import {
+  __export
+} from "./chunk-AZDQPQ3V.js";
+
+// src/compat/zustand/index.ts
+var zustand_exports = {};
+__export(zustand_exports, {
+  create: () => create
+});
+import { DATA, node as nodeFactory } from "@graphrefly/pure-ts/core";
+import { Graph } from "@graphrefly/pure-ts/graph";
+var alwaysDiffer = () => false;
+function create(initializer) {
+  const g = new Graph("zustand");
+  const s = nodeFactory([], {
+    initial: void 0,
+    name: "state",
+    equals: alwaysDiffer
+  });
+  g.add(s, { name: "state" });
+  const getState = () => s.cache;
+  const setState = (partial, replace) => {
+    const prev = s.cache;
+    const next = typeof partial === "function" ? partial(prev) : partial;
+    s.emit(replace ? next : { ...prev, ...next });
+  };
+  const api = {
+    getState,
+    setState,
+    getInitialState: () => initialValue,
+    subscribe: (listener) => {
+      let initial = true;
+      let prev = s.cache;
+      return s.subscribe((msgs) => {
+        for (const [t, v] of msgs) {
+          if (t === DATA) {
+            if (initial) {
+              initial = false;
+              continue;
+            }
+            listener(v, prev);
+            prev = v;
+          }
+        }
+      });
+    },
+    destroy: g.destroy.bind(g)
+  };
+  const initialValue = initializer(setState, getState, api);
+  s.emit(initialValue);
+  return Object.assign(g, api);
+}
+
+export {
+  create,
+  zustand_exports
+};
+//# sourceMappingURL=chunk-255UCBG4.js.map

package/dist/chunk-255UCBG4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compat/zustand/index.ts"],"sourcesContent":["import { DATA, node as nodeFactory } from \"@graphrefly/pure-ts/core\";\nimport { Graph } from \"@graphrefly/pure-ts/graph\";\n\n// Zustand fires listeners on every setState, regardless of reference\n// equality. Configure the state node with a permissive equals so every\n// emit produces DATA (not RESOLVED). Diamond coordination still works\n// because `n.emit` routes through the framed pipeline which auto-\n// prefixes `[DIRTY]`.\nconst alwaysDiffer = () => false;\n\n/** Zustand-compatible Store API. */\nexport interface StoreApi<T> {\n\tgetState: () => T;\n\tsetState: (partial: T | Partial<T> | ((state: T) => T | Partial<T>), replace?: boolean) => void;\n\tgetInitialState: () => T;\n\tsubscribe: (listener: (state: T, prevState: T) => void) => () => void;\n\tdestroy: () => void;\n}\n\n/** Function type for initializing the store. */\nexport type StateCreator<T> = (\n\tset: StoreApi<T>[\"setState\"],\n\tget: StoreApi<T>[\"getState\"],\n\tapi: StoreApi<T>,\n) => T;\n\n/**\n * Creates a Zustand-compatible store backed by a GraphReFly state node.\n * returns an object that is both a Graph and a StoreApi.\n *\n * @example\n * ```ts\n * const store = create((set) => ({\n *   count: 0,\n *   inc: () => set((s) => ({ count: s.count + 1 }))\n * }));\n * store.getState().inc();\n * ```\n *\n * @category compat\n */\nexport function create<T extends object>(initializer: StateCreator<T>): Graph & StoreApi<T> {\n\tconst g = new Graph(\"zustand\");\n\tconst s = nodeFactory<T>([], {\n\t\tinitial: undefined as unknown as T,\n\t\tname: \"state\",\n\t\tequals: alwaysDiffer,\n\t});\n\tg.add(s, { name: \"state\" });\n\n\t// `getState` and `setState` read/write through `s` directly — the single\n\t// source of truth. `s.cache` is `undefined` (SENTINEL) until `emit()` is\n\t// called, but action closures (e.g. `inc: () => set(...)`) are only ever\n\t// invoked after initialization, so `s.cache` is valid by that time.\n\tconst getState = () => s.cache as T;\n\tconst setState = (partial: any, replace?: boolean): void => {\n\t\tconst prev = s.cache as T;\n\t\tconst next = typeof partial === \"function\" ? partial(prev) : partial;\n\t\t// `n.emit` goes through `_actionEmit` → `bundle()`, which auto-\n\t\t// prefixes `[DIRTY]` so diamond legs coordinate under downstream\n\t\t// composition. The `alwaysDiffer` equals keeps zustand's \"fire\n\t\t// on every setState\" semantics.\n\t\ts.emit(replace ? next : { ...prev, ...next });\n\t};\n\n\tconst api: StoreApi<T> = {\n\t\tgetState,\n\t\tsetState,\n\t\tgetInitialState: () => initialValue,\n\t\tsubscribe: (listener) => {\n\t\t\t// Skip the initial push-on-subscribe DATA — zustand subscribe fires on changes only.\n\t\t\tlet initial = true;\n\t\t\tlet prev = s.cache as T;\n\t\t\treturn s.subscribe((msgs) => {\n\t\t\t\tfor (const [t, v] of msgs) {\n\t\t\t\t\tif (t === DATA) {\n\t\t\t\t\t\tif (initial) {\n\t\t\t\t\t\t\tinitial = false;\n\t\t\t\t\t\t\tcontinue;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tlistener(v as T, prev);\n\t\t\t\t\t\tprev = v as T;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\t\tdestroy: g.destroy.bind(g),\n\t};\n\n\tconst initialValue = initializer(setState, getState, api);\n\ts.emit(initialValue);\n\n\treturn Object.assign(g, api);\n}\n"],"mappings":";;;;;AAAA;AAAA;AAAA;AAAA;AAAA,SAAS,MAAM,QAAQ,mBAAmB;AAC1C,SAAS,aAAa;AAOtB,IAAM,eAAe,MAAM;AAiCpB,SAAS,OAAyB,aAAmD;AAC3F,QAAM,IAAI,IAAI,MAAM,SAAS;AAC7B,QAAM,IAAI,YAAe,CAAC,GAAG;AAAA,IAC5B,SAAS;AAAA,IACT,MAAM;AAAA,IACN,QAAQ;AAAA,EACT,CAAC;AACD,IAAE,IAAI,GAAG,EAAE,MAAM,QAAQ,CAAC;AAM1B,QAAM,WAAW,MAAM,EAAE;AACzB,QAAM,WAAW,CAAC,SAAc,YAA4B;AAC3D,UAAM,OAAO,EAAE;AACf,UAAM,OAAO,OAAO,YAAY,aAAa,QAAQ,IAAI,IAAI;AAK7D,MAAE,KAAK,UAAU,OAAO,EAAE,GAAG,MAAM,GAAG,KAAK,CAAC;AAAA,EAC7C;AAEA,QAAM,MAAmB;AAAA,IACxB;AAAA,IACA;AAAA,IACA,iBAAiB,MAAM;AAAA,IACvB,WAAW,CAAC,aAAa;AAExB,UAAI,UAAU;AACd,UAAI,OAAO,EAAE;AACb,aAAO,EAAE,UAAU,CAAC,SAAS;AAC5B,mBAAW,CAAC,GAAG,CAAC,KAAK,MAAM;AAC1B,cAAI,MAAM,MAAM;AACf,gBAAI,SAAS;AACZ,wBAAU;AACV;AAAA,YACD;AACA,qBAAS,GAAQ,IAAI;AACrB,mBAAO;AAAA,UACR;AAAA,QACD;AAAA,MACD,CAAC;AAAA,IACF;AAAA,IACA,SAAS,EAAE,QAAQ,KAAK,CAAC;AAAA,EAC1B;AAEA,QAAM,eAAe,YAAY,UAAU,UAAU,GAAG;AACxD,IAAE,KAAK,YAAY;AAEnB,SAAO,OAAO,OAAO,GAAG,GAAG;AAC5B;","names":[]}

package/dist/chunk-2LO3EL4W.js

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-2LO3EL4W.js.map

package/dist/chunk-2LO3EL4W.js.map

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