@graphrefly/graphrefly 0.21.0 → 0.22.0

package/README.md

@@ -200,10 +200,10 @@ import { node, map, Graph } from "@graphrefly/graphrefly";
 
 ## Resilience & checkpoints
 
-Built-in retry, circuit breakers, rate limiters, and persistent checkpoints:
+Built-in retry, circuit breakers, rate limiters, and persistent storage:
 
 ```ts
-import { retry, circuitBreaker, saveGraphCheckpoint, FileCheckpointAdapter } from "@graphrefly/graphrefly";
+import { retry, circuitBreaker, fileStorage, memoryStorage } from "@graphrefly/graphrefly";
 
 // Retry with exponential backoff
 const resilient = pipe(source, retry({ strategy: "exponential" }));
@@ -211,9 +211,11 @@ const resilient = pipe(source, retry({ strategy: "exponential" }));
 // Circuit breaker
 const breaker = circuitBreaker({ threshold: 5, resetTimeout: 30_000 });
 
-// Checkpoint to file system
-const adapter = new FileCheckpointAdapter("./checkpoints");
-await saveGraphCheckpoint(graph, adapter);
+// Multi-tier storage with auto-restore: hot in-memory + warm on disk.
+graph.attachStorage(
+  [memoryStorage(), fileStorage("./checkpoints")],
+  { autoRestore: true },
+);
 ```
 
 ## Project layout

package/dist/chunk-44HD4BTA.js

@@ -0,0 +1,47 @@
+import {
+  GRAPH_META_SEGMENT,
+  Graph,
+  OVERHEAD,
+  SIZEOF_SYMBOL,
+  diffForWAL,
+  graphProfile,
+  reachable,
+  sizeof
+} from "./chunk-NXC35KC5.js";
+import {
+  ENVELOPE_VERSION,
+  JsonCodec,
+  __export,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  decodeEnvelope,
+  encodeEnvelope,
+  registerBuiltinCodecs,
+  replayWAL
+} from "./chunk-QA3RP5NH.js";
+
+// src/graph/index.ts
+var graph_exports = {};
+__export(graph_exports, {
+  ENVELOPE_VERSION: () => ENVELOPE_VERSION,
+  GRAPH_META_SEGMENT: () => GRAPH_META_SEGMENT,
+  Graph: () => Graph,
+  JsonCodec: () => JsonCodec,
+  SIZEOF_OVERHEAD: () => OVERHEAD,
+  SIZEOF_SYMBOL: () => SIZEOF_SYMBOL,
+  createDagCborCodec: () => createDagCborCodec,
+  createDagCborZstdCodec: () => createDagCborZstdCodec,
+  decodeEnvelope: () => decodeEnvelope,
+  diffForWAL: () => diffForWAL,
+  encodeEnvelope: () => encodeEnvelope,
+  graphProfile: () => graphProfile,
+  reachable: () => reachable,
+  registerBuiltinCodecs: () => registerBuiltinCodecs,
+  replayWAL: () => replayWAL,
+  sizeof: () => sizeof
+});
+
+export {
+  graph_exports
+};
+//# sourceMappingURL=chunk-44HD4BTA.js.map

package/dist/chunk-44HD4BTA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph/index.ts"],"sourcesContent":["/**\n * Graph container: registry, wiring, introspection (Phase 1).\n */\n\nexport { OVERHEAD as SIZEOF_OVERHEAD, SIZEOF_SYMBOL, sizeof } from \"../extra/utils/sizeof.js\";\nexport {\n\tcreateDagCborCodec,\n\tcreateDagCborZstdCodec,\n\tdecodeEnvelope,\n\tENVELOPE_VERSION,\n\ttype EvictedSubgraphInfo,\n\ttype EvictionPolicy,\n\tencodeEnvelope,\n\ttype GraphCodec,\n\tJsonCodec,\n\ttype LazyGraphCodec,\n\tregisterBuiltinCodecs,\n\treplayWAL,\n\ttype WALEntry,\n} from \"./codec.js\";\nexport {\n\ttype DescribeFilter,\n\tdiffForWAL,\n\tGRAPH_META_SEGMENT,\n\tGraph,\n\ttype GraphActorOptions,\n\ttype GraphAttachStorageOptions,\n\ttype GraphCheckpointRecord,\n\ttype GraphDescribeOptions,\n\ttype GraphDescribeOutput,\n\ttype GraphDiagramDirection,\n\ttype GraphDiagramOptions,\n\ttype GraphDiffChange,\n\ttype GraphDiffResult,\n\ttype GraphFactoryContext,\n\ttype GraphNodeFactory,\n\ttype GraphObserveAll,\n\ttype GraphObserveOne,\n\ttype GraphOptions,\n\ttype GraphPersistSnapshot,\n\ttype GraphVersionChange,\n\ttype GraphWALDiff,\n\ttype ObserveDetail,\n\ttype ObserveEvent,\n\ttype ObserveOptions,\n\ttype ObserveResult,\n\ttype ObserveTheme,\n\ttype ObserveThemeName,\n\ttype ReachableDirection,\n\ttype ReachableOptions,\n\treachable,\n\ttype TraceEntry,\n} from \"./graph.js\";\nexport {\n\ttype GraphProfileOptions,\n\ttype GraphProfileResult,\n\tgraphProfile,\n\ttype NodeProfile,\n} from \"./profile.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/chunk-7TAQJHQV.js

@@ -0,0 +1,103 @@
+// src/extra/timer.ts
+var ResettableTimer = class {
+  _timer;
+  _gen = 0;
+  /** Schedule callback after delayMs. Cancels any pending timer. */
+  start(delayMs, callback) {
+    this.cancel();
+    this._gen += 1;
+    const gen = this._gen;
+    this._timer = setTimeout(() => {
+      this._timer = void 0;
+      if (gen !== this._gen) return;
+      callback();
+    }, delayMs);
+  }
+  /** Cancel the pending timer (if any). */
+  cancel() {
+    if (this._timer !== void 0) {
+      clearTimeout(this._timer);
+      this._timer = void 0;
+    }
+  }
+  /** Whether a timer is currently pending. */
+  get pending() {
+    return this._timer !== void 0;
+  }
+};
+
+// src/extra/utils/ring-buffer.ts
+var RingBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`RingBuffer capacity must be a positive integer (got ${capacity})`);
+    }
+    this.buf = new Array(capacity);
+  }
+  buf;
+  head = 0;
+  _size = 0;
+  /** Current number of stored entries. */
+  get size() {
+    return this._size;
+  }
+  /** Configured maximum before drop-oldest eviction fires. */
+  get maxSize() {
+    return this.capacity;
+  }
+  /**
+   * Append an item. If size equals capacity, drops the oldest entry and
+   * advances the head pointer.
+   */
+  push(item) {
+    const idx = (this.head + this._size) % this.capacity;
+    this.buf[idx] = item;
+    if (this._size < this.capacity) this._size++;
+    else this.head = (this.head + 1) % this.capacity;
+  }
+  /** Remove and return the oldest entry; `undefined` when empty. */
+  shift() {
+    if (this._size === 0) return void 0;
+    const item = this.buf[this.head];
+    this.buf[this.head] = void 0;
+    this.head = (this.head + 1) % this.capacity;
+    this._size--;
+    return item;
+  }
+  /**
+   * O(1) index lookup. Negative indices count from the tail (Python-style).
+   * Returns `undefined` for out-of-range.
+   */
+  at(i) {
+    if (this._size === 0) return void 0;
+    const n = i < 0 ? this._size + i : i;
+    if (n < 0 || n >= this._size) return void 0;
+    return this.buf[(this.head + n) % this.capacity];
+  }
+  /**
+   * Materialize the contents in insertion order (oldest → newest).
+   * Returns a new array each call.
+   */
+  toArray() {
+    const result = new Array(this._size);
+    for (let i = 0; i < this._size; i++) {
+      result[i] = this.buf[(this.head + i) % this.capacity];
+    }
+    return result;
+  }
+  /** Reset to empty. Storage slots are released so held refs can GC. */
+  clear() {
+    for (let i = 0; i < this._size; i++) {
+      this.buf[(this.head + i) % this.capacity] = void 0;
+    }
+    this.head = 0;
+    this._size = 0;
+  }
+};
+
+export {
+  ResettableTimer,
+  RingBuffer
+};
+//# sourceMappingURL=chunk-7TAQJHQV.js.map

package/dist/chunk-7TAQJHQV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/extra/timer.ts","../src/extra/utils/ring-buffer.ts"],"sourcesContent":["/**\n * Creates a resettable deadline timer for internal timeout, retry, and rate-limiting use.\n *\n * @remarks **Centralised primitive:** wraps `setTimeout`/`clearTimeout` with a generation guard\n * so that stale callbacks never fire after `cancel()` or a new `start()`.\n *\n * @remarks **Spec §5.10 exception:** resilience operators (`timeout`, `retry`, `rateLimiter`)\n * need raw timers — `fromTimer` creates a new Node per reset, which is too heavy here.\n * Lives in `src/extra/` (not `src/core/`) because it is a documented escape hatch from\n * the protocol-pure core layer.\n *\n * @example\n * ```ts\n * import { ResettableTimer } from \"@graphrefly/graphrefly-ts\";\n *\n * const timer = new ResettableTimer();\n * timer.start(1000, () => console.log(\"fired\"));\n * timer.cancel();          // cancels before firing\n * timer.start(500, () => console.log(\"new deadline\"));\n * console.log(timer.pending); // true\n * ```\n *\n * @category extra\n */\nexport class ResettableTimer {\n\tprivate _timer: ReturnType<typeof setTimeout> | undefined;\n\tprivate _gen = 0;\n\n\t/** Schedule callback after delayMs. Cancels any pending timer. */\n\tstart(delayMs: number, callback: () => void): void {\n\t\tthis.cancel();\n\t\tthis._gen += 1;\n\t\tconst gen = this._gen;\n\t\tthis._timer = setTimeout(() => {\n\t\t\tthis._timer = undefined;\n\t\t\tif (gen !== this._gen) return;\n\t\t\tcallback();\n\t\t}, delayMs);\n\t}\n\n\t/** Cancel the pending timer (if any). */\n\tcancel(): void {\n\t\tif (this._timer !== undefined) {\n\t\t\tclearTimeout(this._timer);\n\t\t\tthis._timer = undefined;\n\t\t}\n\t}\n\n\t/** Whether a timer is currently pending. */\n\tget pending(): boolean {\n\t\treturn this._timer !== undefined;\n\t}\n}\n","/**\n * Fixed-capacity ring buffer — O(1) push and drop-oldest eviction.\n *\n * Used by `Graph._traceRing` (reasoning trace), `reactiveLog` (append-only\n * log backend), and `reactiveSink` (drop-oldest backpressure buffer). One\n * implementation, three use sites.\n *\n * @module\n * @internal\n */\n\n/**\n * Fixed-capacity ring buffer. Once `capacity` entries are stored, subsequent\n * `push` calls evict the oldest entry (drop-oldest / FIFO eviction).\n *\n * Operations:\n * - `push(item)` — O(1).\n * - `shift()` — O(1) remove oldest (returns `undefined` when empty).\n * - `at(i)` — O(1) index lookup, with Python-style negative indexing.\n * - `toArray()` — O(n) materialize in insertion order.\n * - `clear()` — O(1) reset to empty.\n *\n * Not thread-safe; JS semantics assumed (single-threaded within a sync call).\n */\nexport class RingBuffer<T> {\n\tprivate buf: (T | undefined)[];\n\tprivate head = 0;\n\tprivate _size = 0;\n\n\tconstructor(private capacity: number) {\n\t\tif (!Number.isInteger(capacity) || capacity <= 0) {\n\t\t\tthrow new Error(`RingBuffer capacity must be a positive integer (got ${capacity})`);\n\t\t}\n\t\tthis.buf = new Array(capacity);\n\t}\n\n\t/** Current number of stored entries. */\n\tget size(): number {\n\t\treturn this._size;\n\t}\n\n\t/** Configured maximum before drop-oldest eviction fires. */\n\tget maxSize(): number {\n\t\treturn this.capacity;\n\t}\n\n\t/**\n\t * Append an item. If size equals capacity, drops the oldest entry and\n\t * advances the head pointer.\n\t */\n\tpush(item: T): void {\n\t\tconst idx = (this.head + this._size) % this.capacity;\n\t\tthis.buf[idx] = item;\n\t\tif (this._size < this.capacity) this._size++;\n\t\telse this.head = (this.head + 1) % this.capacity;\n\t}\n\n\t/** Remove and return the oldest entry; `undefined` when empty. */\n\tshift(): T | undefined {\n\t\tif (this._size === 0) return undefined;\n\t\tconst item = this.buf[this.head];\n\t\tthis.buf[this.head] = undefined;\n\t\tthis.head = (this.head + 1) % this.capacity;\n\t\tthis._size--;\n\t\treturn item;\n\t}\n\n\t/**\n\t * O(1) index lookup. Negative indices count from the tail (Python-style).\n\t * Returns `undefined` for out-of-range.\n\t */\n\tat(i: number): T | undefined {\n\t\tif (this._size === 0) return undefined;\n\t\tconst n = i < 0 ? this._size + i : i;\n\t\tif (n < 0 || n >= this._size) return undefined;\n\t\treturn this.buf[(this.head + n) % this.capacity];\n\t}\n\n\t/**\n\t * Materialize the contents in insertion order (oldest → newest).\n\t * Returns a new array each call.\n\t */\n\ttoArray(): T[] {\n\t\tconst result: T[] = new Array(this._size);\n\t\tfor (let i = 0; i < this._size; i++) {\n\t\t\tresult[i] = this.buf[(this.head + i) % this.capacity]!;\n\t\t}\n\t\treturn result;\n\t}\n\n\t/** Reset to empty. Storage slots are released so held refs can GC. */\n\tclear(): void {\n\t\tfor (let i = 0; i < this._size; i++) {\n\t\t\tthis.buf[(this.head + i) % this.capacity] = undefined;\n\t\t}\n\t\tthis.head = 0;\n\t\tthis._size = 0;\n\t}\n}\n"],"mappings":";AAwBO,IAAM,kBAAN,MAAsB;AAAA,EACpB;AAAA,EACA,OAAO;AAAA;AAAA,EAGf,MAAM,SAAiB,UAA4B;AAClD,SAAK,OAAO;AACZ,SAAK,QAAQ;AACb,UAAM,MAAM,KAAK;AACjB,SAAK,SAAS,WAAW,MAAM;AAC9B,WAAK,SAAS;AACd,UAAI,QAAQ,KAAK,KAAM;AACvB,eAAS;AAAA,IACV,GAAG,OAAO;AAAA,EACX;AAAA;AAAA,EAGA,SAAe;AACd,QAAI,KAAK,WAAW,QAAW;AAC9B,mBAAa,KAAK,MAAM;AACxB,WAAK,SAAS;AAAA,IACf;AAAA,EACD;AAAA;AAAA,EAGA,IAAI,UAAmB;AACtB,WAAO,KAAK,WAAW;AAAA,EACxB;AACD;;;AC5BO,IAAM,aAAN,MAAoB;AAAA,EAK1B,YAAoB,UAAkB;AAAlB;AACnB,QAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,YAAY,GAAG;AACjD,YAAM,IAAI,MAAM,uDAAuD,QAAQ,GAAG;AAAA,IACnF;AACA,SAAK,MAAM,IAAI,MAAM,QAAQ;AAAA,EAC9B;AAAA,EATQ;AAAA,EACA,OAAO;AAAA,EACP,QAAQ;AAAA;AAAA,EAUhB,IAAI,OAAe;AAClB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA,EAGA,IAAI,UAAkB;AACrB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KAAK,MAAe;AACnB,UAAM,OAAO,KAAK,OAAO,KAAK,SAAS,KAAK;AAC5C,SAAK,IAAI,GAAG,IAAI;AAChB,QAAI,KAAK,QAAQ,KAAK,SAAU,MAAK;AAAA,QAChC,MAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;AAAA,EACzC;AAAA;AAAA,EAGA,QAAuB;AACtB,QAAI,KAAK,UAAU,EAAG,QAAO;AAC7B,UAAM,OAAO,KAAK,IAAI,KAAK,IAAI;AAC/B,SAAK,IAAI,KAAK,IAAI,IAAI;AACtB,SAAK,QAAQ,KAAK,OAAO,KAAK,KAAK;AACnC,SAAK;AACL,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,GAAG,GAA0B;AAC5B,QAAI,KAAK,UAAU,EAAG,QAAO;AAC7B,UAAM,IAAI,IAAI,IAAI,KAAK,QAAQ,IAAI;AACnC,QAAI,IAAI,KAAK,KAAK,KAAK,MAAO,QAAO;AACrC,WAAO,KAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ;AAAA,EAChD;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,UAAe;AACd,UAAM,SAAc,IAAI,MAAM,KAAK,KAAK;AACxC,aAAS,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK;AACpC,aAAO,CAAC,IAAI,KAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ;AAAA,IACrD;AACA,WAAO;AAAA,EACR;AAAA;AAAA,EAGA,QAAc;AACb,aAAS,IAAI,GAAG,IAAI,KAAK,OAAO,KAAK;AACpC,WAAK,KAAK,KAAK,OAAO,KAAK,KAAK,QAAQ,IAAI;AAAA,IAC7C;AACA,SAAK,OAAO;AACZ,SAAK,QAAQ;AAAA,EACd;AACD;","names":[]}