@graphrefly/graphrefly 0.34.0 → 0.35.0

package/dist/extra/storage-browser.d.ts

@@ -1,27 +1,18 @@
-import { a as Node } from '../node-8qx0kgYt.js';
-import { StorageTier } from './storage-core.js';
+import { a as Node } from '../node-fSc-hCv8.js';
 
 /**
- * Browser-only storage backend + IndexedDB reactive sources.
+ * Browser-only IndexedDB reactive sources.
  *
- * `indexedDbStorage` provides async {@link StorageTier} semantics backed by
- * IndexedDB; `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives
- * as reactive sources. Imports require the DOM lib — not safe to pull into
- * Node-only bundles without `lib: ["dom"]` in the consumer's tsconfig.
+ * `fromIDBRequest` / `fromIDBTransaction` wrap raw IDB primitives as reactive
+ * sources. The old `indexedDbStorage` kv adapter has been replaced by
+ * `indexedDbKv` in `./storage-tiers-browser.js` (Audit 4, 2026-04-24).
  *
- * The legacy `extra/storage.ts` barrel re-exports this module for back-compat;
- * browser-first consumers should import from here directly.
+ * Imports require the DOM lib — not safe to pull into Node-only bundles
+ * without `lib: ["dom"]` in the consumer's tsconfig.
  *
  * @module
  */
 
-type IndexedDbStorageSpec = {
-    dbName: string;
-    storeName: string;
-    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
-    key?: string;
-    version?: number;
-};
 /**
  * Wraps an `IDBRequest` as a one-shot reactive source.
  *
@@ -42,30 +33,5 @@ declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
  * @category extra
  */
 declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
-/**
- * IndexedDB-backed async storage tier (browser runtime).
- *
- * All three methods return `Promise`s — pairs naturally with a warm/cold
- * cadence where async writes are debounced per tier via
- * `Graph.attachStorage`. Writes use `readwrite` transactions; reads use
- * `readonly`. Missing records resolve to `null`.
- *
- * @param spec - Database name, store name, optional `key` (default
- *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
- * @returns Async {@link StorageTier}.
- *
- * @example
- * ```ts
- * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * graph.attachStorage([
- *   memoryStorage(),
- *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
- * ]);
- * ```
- *
- * @category extra
- */
-declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
 
-export { type IndexedDbStorageSpec, fromIDBRequest, fromIDBTransaction, indexedDbStorage };
+export { fromIDBRequest, fromIDBTransaction };

package/dist/extra/storage-browser.js

@@ -1 +1 @@
-import{a,b,c}from"../chunk-IJFSR4NU.js";import"../chunk-LYCLF26R.js";import"../chunk-CK2E7BTU.js";import"../chunk-QYADASLV.js";export{a as fromIDBRequest,b as fromIDBTransaction,c as indexedDbStorage};
+import{a,b}from"../chunk-F3IGTWCQ.js";import"../chunk-LYCLF26R.js";import"../chunk-CK2E7BTU.js";import"../chunk-QYADASLV.js";export{a as fromIDBRequest,b as fromIDBTransaction};

package/dist/extra/storage-core.cjs

@@ -1 +1 @@
-"use strict";var s=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var a=Object.getOwnPropertyNames;var d=Object.prototype.hasOwnProperty;var c=(n,r)=>{for(var e in r)s(n,e,{get:r[e],enumerable:!0})},g=(n,r,e,o)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of a(r))!d.call(n,t)&&t!==e&&s(n,t,{get:()=>r[t],enumerable:!(o=u(r,t))||o.enumerable});return n};var f=n=>g(s({},"__esModule",{value:!0}),n);var S={};c(S,{dictStorage:()=>l,memoryStorage:()=>y,sortJsonValue:()=>i,stableJsonString:()=>k});module.exports=f(S);function i(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(i);let r=n,e=Object.keys(r).sort(),o={};for(let t of e)o[t]=i(r[t]);return o}function k(n){return JSON.stringify(i(n),void 0,0)}function y(){let n=new Map;return{save(r,e){n.set(r,JSON.parse(JSON.stringify(e)))},load(r){let e=n.get(r);return e===void 0?null:JSON.parse(JSON.stringify(e))},clear(r){n.delete(r)},list(){return[...n.keys()].sort()}}}function l(n){return{save(r,e){n[r]=JSON.parse(JSON.stringify(e))},load(r){let e=n[r];return e===void 0?null:JSON.parse(JSON.stringify(e))},clear(r){delete n[r]},list(){return Object.keys(n).sort()}}}0&&(module.exports={dictStorage,memoryStorage,sortJsonValue,stableJsonString});
+"use strict";var i=Object.defineProperty;var c=Object.getOwnPropertyDescriptor;var f=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var k=(n,o)=>{for(var t in o)i(n,t,{get:o[t],enumerable:!0})},d=(n,o,t,s)=>{if(o&&typeof o=="object"||typeof o=="function")for(let r of f(o))!u.call(n,r)&&r!==t&&i(n,r,{get:()=>o[r],enumerable:!(s=c(o,r))||s.enumerable});return n};var g=n=>d(i({},"__esModule",{value:!0}),n);var y={};k(y,{sortJsonValue:()=>e,stableJsonString:()=>p});module.exports=g(y);function e(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(e);let o=n,t=Object.keys(o).sort(),s={};for(let r of t)s[r]=e(o[r]);return s}function p(n){return JSON.stringify(e(n),void 0,0)}0&&(module.exports={sortJsonValue,stableJsonString});

package/dist/extra/storage-core.d.cts

@@ -1,53 +1,18 @@
 /**
- * Storage tier primitive — browser-safe core (types + in-memory backends).
+ * Storage core — browser-safe shared helpers.
  *
- * Split out of `extra/storage.ts` so browser bundles can import the
- * {@link StorageTier} contract, {@link memoryStorage}, {@link dictStorage}
- * and shared JSON helpers without pulling `node:fs` / `node:sqlite` /
- * `node:crypto`. Node-only backends (`fileStorage`, `sqliteStorage`) live in
- * {@link ./storage-node}; browser-only ones (`indexedDbStorage`,
- * `fromIDBRequest`, `fromIDBTransaction`) live in {@link ./storage-browser}.
- * The legacy `extra/storage.ts` module re-exports all three for back-compat.
+ * This module exposes only the stable shared utilities (`StorageHandle`,
+ * `sortJsonValue`, `stableJsonString`). The old `StorageTier` interface and
+ * its in-memory factories (`memoryStorage`, `dictStorage`) have been removed
+ * — use `KvStorageTier` + `memoryKv` / `dictKv` from `./storage-tiers.js`
+ * instead (Audit 4, 2026-04-24).
+ *
+ * Node-only backends (`fileKv`, `sqliteKv`) live in `./storage-tiers-node.js`;
+ * browser-only ones (`indexedDbKv`) live in `./storage-tiers-browser.js`.
  *
  * @module
  */
-/**
- * Single persistence primitive — supports sync and async backends alike via
- * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
- * are per-tier cadence controls honored by `Graph.attachStorage`;
- * `cascadingCache` ignores them (it has its own eviction policy).
- */
-interface StorageTier {
-    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
-    load(key: string): unknown | Promise<unknown>;
-    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
-    save(key: string, data: unknown): void | Promise<void>;
-    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
-    clear?(key: string): void | Promise<void>;
-    /**
-     * Enumerate known keys. Optional — tiers that only address a single record
-     * (e.g. `indexedDbStorage`) or that can't cheaply enumerate (e.g. a remote
-     * write-only sink) may omit it. Callers that require enumeration (the
-     * surface `snapshot.list()` helper, MCP `graphrefly_snapshot_list`, CLI
-     * `graphrefly snapshot list`) should check before calling.
-     */
-    list?(): readonly string[] | Promise<readonly string[]>;
-    /**
-     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
-     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
-     * so cold flushes aren't penalized by hot flushes.
-     */
-    debounceMs?: number;
-    /**
-     * Every Nth record is a full snapshot; others are diffs against this
-     * tier's own baseline. Default `10`. Set `1` for always-full;
-     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
-     */
-    compactEvery?: number;
-    /** Pre-save filter — return `false` to skip this record on this tier. */
-    filter?: (key: string, record: unknown) => boolean;
-}
-/** Handle returned by `Graph.attachStorage` — dispose to stop observing. */
+/** Handle returned by `Graph.attachSnapshotStorage` — dispose to stop observing. */
 interface StorageHandle {
     dispose(): void;
 }
@@ -55,44 +20,9 @@ interface StorageHandle {
 declare function sortJsonValue(value: unknown): unknown;
 /**
  * Stable JSON encoding (no trailing newline). Tiers that want POSIX newline
- * convention (e.g. `fileStorage`) append their own; in-database tiers
- * (`sqliteStorage`) keep the payload byte-identical for cross-tier hash/CID
- * comparison.
+ * convention (e.g. `fileKv`) append their own; in-database tiers (`sqliteKv`)
+ * keep the payload byte-identical for cross-tier hash/CID comparison.
  */
 declare function stableJsonString(data: unknown): string;
-/**
- * In-memory storage tier (process-local; useful for tests and hot tier).
- *
- * @returns Sync {@link StorageTier} with JSON-cloned isolation.
- *
- * @example
- * ```ts
- * import { memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * const hot = memoryStorage();
- * graph.attachStorage([hot]);
- * ```
- *
- * @category extra
- */
-declare function memoryStorage(): StorageTier;
-/**
- * Dict-backed storage tier — stores JSON-cloned values under caller keys in
- * a caller-owned plain object. Useful for embedding in a parent state shape.
- *
- * @param storage - Caller-owned object used as the backing store.
- * @returns Sync {@link StorageTier}.
- *
- * @example
- * ```ts
- * import { dictStorage } from "@graphrefly/graphrefly-ts";
- *
- * const state: Record<string, unknown> = {};
- * graph.attachStorage([dictStorage(state)]);
- * ```
- *
- * @category extra
- */
-declare function dictStorage(storage: Record<string, unknown>): StorageTier;
 
-export { type StorageHandle, type StorageTier, dictStorage, memoryStorage, sortJsonValue, stableJsonString };
+export { type StorageHandle, sortJsonValue, stableJsonString };

package/dist/extra/storage-core.d.ts

@@ -1,53 +1,18 @@
 /**
- * Storage tier primitive — browser-safe core (types + in-memory backends).
+ * Storage core — browser-safe shared helpers.
  *
- * Split out of `extra/storage.ts` so browser bundles can import the
- * {@link StorageTier} contract, {@link memoryStorage}, {@link dictStorage}
- * and shared JSON helpers without pulling `node:fs` / `node:sqlite` /
- * `node:crypto`. Node-only backends (`fileStorage`, `sqliteStorage`) live in
- * {@link ./storage-node}; browser-only ones (`indexedDbStorage`,
- * `fromIDBRequest`, `fromIDBTransaction`) live in {@link ./storage-browser}.
- * The legacy `extra/storage.ts` module re-exports all three for back-compat.
+ * This module exposes only the stable shared utilities (`StorageHandle`,
+ * `sortJsonValue`, `stableJsonString`). The old `StorageTier` interface and
+ * its in-memory factories (`memoryStorage`, `dictStorage`) have been removed
+ * — use `KvStorageTier` + `memoryKv` / `dictKv` from `./storage-tiers.js`
+ * instead (Audit 4, 2026-04-24).
+ *
+ * Node-only backends (`fileKv`, `sqliteKv`) live in `./storage-tiers-node.js`;
+ * browser-only ones (`indexedDbKv`) live in `./storage-tiers-browser.js`.
  *
  * @module
  */
-/**
- * Single persistence primitive — supports sync and async backends alike via
- * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
- * are per-tier cadence controls honored by `Graph.attachStorage`;
- * `cascadingCache` ignores them (it has its own eviction policy).
- */
-interface StorageTier {
-    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
-    load(key: string): unknown | Promise<unknown>;
-    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
-    save(key: string, data: unknown): void | Promise<void>;
-    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
-    clear?(key: string): void | Promise<void>;
-    /**
-     * Enumerate known keys. Optional — tiers that only address a single record
-     * (e.g. `indexedDbStorage`) or that can't cheaply enumerate (e.g. a remote
-     * write-only sink) may omit it. Callers that require enumeration (the
-     * surface `snapshot.list()` helper, MCP `graphrefly_snapshot_list`, CLI
-     * `graphrefly snapshot list`) should check before calling.
-     */
-    list?(): readonly string[] | Promise<readonly string[]>;
-    /**
-     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
-     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
-     * so cold flushes aren't penalized by hot flushes.
-     */
-    debounceMs?: number;
-    /**
-     * Every Nth record is a full snapshot; others are diffs against this
-     * tier's own baseline. Default `10`. Set `1` for always-full;
-     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
-     */
-    compactEvery?: number;
-    /** Pre-save filter — return `false` to skip this record on this tier. */
-    filter?: (key: string, record: unknown) => boolean;
-}
-/** Handle returned by `Graph.attachStorage` — dispose to stop observing. */
+/** Handle returned by `Graph.attachSnapshotStorage` — dispose to stop observing. */
 interface StorageHandle {
     dispose(): void;
 }
@@ -55,44 +20,9 @@ interface StorageHandle {
 declare function sortJsonValue(value: unknown): unknown;
 /**
  * Stable JSON encoding (no trailing newline). Tiers that want POSIX newline
- * convention (e.g. `fileStorage`) append their own; in-database tiers
- * (`sqliteStorage`) keep the payload byte-identical for cross-tier hash/CID
- * comparison.
+ * convention (e.g. `fileKv`) append their own; in-database tiers (`sqliteKv`)
+ * keep the payload byte-identical for cross-tier hash/CID comparison.
  */
 declare function stableJsonString(data: unknown): string;
-/**
- * In-memory storage tier (process-local; useful for tests and hot tier).
- *
- * @returns Sync {@link StorageTier} with JSON-cloned isolation.
- *
- * @example
- * ```ts
- * import { memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * const hot = memoryStorage();
- * graph.attachStorage([hot]);
- * ```
- *
- * @category extra
- */
-declare function memoryStorage(): StorageTier;
-/**
- * Dict-backed storage tier — stores JSON-cloned values under caller keys in
- * a caller-owned plain object. Useful for embedding in a parent state shape.
- *
- * @param storage - Caller-owned object used as the backing store.
- * @returns Sync {@link StorageTier}.
- *
- * @example
- * ```ts
- * import { dictStorage } from "@graphrefly/graphrefly-ts";
- *
- * const state: Record<string, unknown> = {};
- * graph.attachStorage([dictStorage(state)]);
- * ```
- *
- * @category extra
- */
-declare function dictStorage(storage: Record<string, unknown>): StorageTier;
 
-export { type StorageHandle, type StorageTier, dictStorage, memoryStorage, sortJsonValue, stableJsonString };
+export { type StorageHandle, sortJsonValue, stableJsonString };

package/dist/extra/storage-core.js

@@ -1 +1 @@
-import{a,b,c,d}from"../chunk-I6VIH3VA.js";import"../chunk-QYADASLV.js";export{d as dictStorage,c as memoryStorage,a as sortJsonValue,b as stableJsonString};
+import{a,b}from"../chunk-CE72X3WO.js";import"../chunk-QYADASLV.js";export{a as sortJsonValue,b as stableJsonString};

package/dist/extra/storage-node.cjs

@@ -1,2 +1 @@
-"use strict";var g=Object.defineProperty;var E=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var T=Object.prototype.hasOwnProperty;var N=(n,e)=>{for(var o in e)g(n,o,{get:e[o],enumerable:!0})},O=(n,e,o,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let a of w(e))!T.call(n,a)&&a!==o&&g(n,a,{get:()=>e[a],enumerable:!(r=E(e,a))||r.enumerable});return n};var b=n=>O(g({},"__esModule",{value:!0}),n);var J={};N(J,{fileStorage:()=>v,sqliteStorage:()=>x});module.exports=b(J);var k=require("node:crypto"),c=require("node:fs"),p=require("node:path"),h=require("node:sqlite");function y(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(y);let e=n,o=Object.keys(e).sort(),r={};for(let a of o)r[a]=y(e[a]);return r}function S(n){return JSON.stringify(y(n),void 0,0)}function v(n){let e=new TextEncoder,o=new TextDecoder("utf-8",{fatal:!0}),r=s=>{let t="";for(let i of s){if(i.length===1&&/[a-zA-Z0-9_-]/.test(i)){t+=i;continue}for(let d of e.encode(i))t+=`%${d.toString(16).padStart(2,"0")}`}return(0,p.join)(n,`${t}.json`)},a=s=>{if(!s.endsWith(".json"))return null;let t=s.slice(0,-5),i=[],d=f=>{for(let u=0;u<f.length;u++)i.push(f.charCodeAt(u))},l=0;for(;l<t.length;){let f=t[l];if(f==="%"&&l+2<t.length){let u=t.slice(l+1,l+3);if(/^[0-9a-f]{2}$/i.test(u)){i.push(Number.parseInt(u,16)),l+=3;continue}}d(f),l+=1}try{return o.decode(new Uint8Array(i))}catch{return null}};return{save(s,t){(0,c.mkdirSync)(n,{recursive:!0});let i=r(s),d=`${S(t)}
-`,l=(0,p.basename)(i),f=(0,p.dirname)(i),u=(0,p.join)(f,`.${l}.${(0,k.randomBytes)(8).toString("hex")}.tmp`);try{(0,c.writeFileSync)(u,d,"utf8"),(0,c.renameSync)(u,i)}catch(m){try{(0,c.unlinkSync)(u)}catch{}throw m}},load(s){try{let t=(0,c.readFileSync)(r(s),"utf8").trim();return t?JSON.parse(t):null}catch{return null}},clear(s){try{(0,c.unlinkSync)(r(s))}catch(t){if(t.code!=="ENOENT")throw t}},list(){try{let s=(0,c.readdirSync)(n),t=[];for(let i of s){if(i.startsWith("."))continue;let d=a(i);d!==null&&t.push(d)}return t.sort()}catch(s){if(s.code==="ENOENT")return[];throw s}}}}function x(n){let e=new h.DatabaseSync(n);return e.exec("CREATE TABLE IF NOT EXISTS graphrefly_checkpoint (k TEXT PRIMARY KEY, v TEXT NOT NULL)"),{save(o,r){let a=S(r);e.prepare("INSERT OR REPLACE INTO graphrefly_checkpoint (k, v) VALUES (?, ?)").run(o,a)},load(o){let r=e.prepare("SELECT v FROM graphrefly_checkpoint WHERE k = ?").get(o);return r===void 0||typeof r.v!="string"||r.v.trim()===""?null:JSON.parse(r.v)},clear(o){e.prepare("DELETE FROM graphrefly_checkpoint WHERE k = ?").run(o)},list(){return e.prepare("SELECT k FROM graphrefly_checkpoint ORDER BY k").all().map(r=>r.k)},close(){try{e.close()}catch{}}}}0&&(module.exports={fileStorage,sqliteStorage});
+"use strict";

package/dist/extra/storage-node.d.cts

@@ -1,60 +1,2 @@
-import { StorageTier } from './storage-core.cjs';
 
-/**
- * Node-only storage backends — `fileStorage` (atomic per-key JSON files) and
- * `sqliteStorage` (Node 22.5+ `node:sqlite`). Imports `node:fs`, `node:path`,
- * `node:crypto`, `node:sqlite`.
- *
- * Browser-safe consumers should import {@link ./storage-core} instead; the
- * legacy `extra/storage.ts` barrel re-exports this module for back-compat.
- *
- * @module
- */
-
-/**
- * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
- *
- * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
- * `load` returns `null` for missing files, empty files, or invalid JSON.
- *
- * @param dir - Directory where per-key JSON files are written.
- * @returns Sync {@link StorageTier}.
- *
- * @example
- * ```ts
- * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
- * ```
- *
- * @category extra
- */
-declare function fileStorage(dir: string): StorageTier;
-/**
- * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
- *
- * Returns a {@link StorageTier} extended with `close()` — the caller owns the
- * connection and should close it when discarding the tier.
- *
- * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
- *
- * @param path - SQLite database file path.
- * @returns Sync {@link StorageTier} with an idempotent `close()` method.
- *
- * @example
- * ```ts
- * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * const cold = sqliteStorage("./graphs.sqlite");
- * graph.attachStorage([memoryStorage(), cold]);
- * // ... later, on shutdown:
- * cold.close();
- * ```
- *
- * @category extra
- */
-declare function sqliteStorage(path: string): StorageTier & {
-    close(): void;
-};
-
-export { fileStorage, sqliteStorage };
+export {  }

package/dist/extra/storage-node.d.ts

@@ -1,60 +1,2 @@
-import { StorageTier } from './storage-core.js';
 
-/**
- * Node-only storage backends — `fileStorage` (atomic per-key JSON files) and
- * `sqliteStorage` (Node 22.5+ `node:sqlite`). Imports `node:fs`, `node:path`,
- * `node:crypto`, `node:sqlite`.
- *
- * Browser-safe consumers should import {@link ./storage-core} instead; the
- * legacy `extra/storage.ts` barrel re-exports this module for back-compat.
- *
- * @module
- */
-
-/**
- * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
- *
- * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
- * `load` returns `null` for missing files, empty files, or invalid JSON.
- *
- * @param dir - Directory where per-key JSON files are written.
- * @returns Sync {@link StorageTier}.
- *
- * @example
- * ```ts
- * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
- * ```
- *
- * @category extra
- */
-declare function fileStorage(dir: string): StorageTier;
-/**
- * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
- *
- * Returns a {@link StorageTier} extended with `close()` — the caller owns the
- * connection and should close it when discarding the tier.
- *
- * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
- *
- * @param path - SQLite database file path.
- * @returns Sync {@link StorageTier} with an idempotent `close()` method.
- *
- * @example
- * ```ts
- * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
- *
- * const cold = sqliteStorage("./graphs.sqlite");
- * graph.attachStorage([memoryStorage(), cold]);
- * // ... later, on shutdown:
- * cold.close();
- * ```
- *
- * @category extra
- */
-declare function sqliteStorage(path: string): StorageTier & {
-    close(): void;
-};
-
-export { fileStorage, sqliteStorage };
+export {  }

package/dist/extra/storage-node.js

@@ -1 +0,0 @@
-import{a,b}from"../chunk-3JXNEPCD.js";import"../chunk-I6VIH3VA.js";import"../chunk-QYADASLV.js";export{a as fileStorage,b as sqliteStorage};

package/dist/extra/storage-tiers-browser.cjs

@@ -0,0 +1 @@
+"use strict";var b=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var C=Object.prototype.hasOwnProperty;var E=(e,n)=>{for(var t in n)b(e,t,{get:n[t],enumerable:!0})},K=(e,n,t,o)=>{if(n&&typeof n=="object"||typeof n=="function")for(let r of N(n))!C.call(e,r)&&r!==t&&b(e,r,{get:()=>n[r],enumerable:!(o=M(n,r))||o.enumerable});return e};var U=e=>K(b({},"__esModule",{value:!0}),e);var W={};E(W,{indexedDbAppendLog:()=>J,indexedDbBackend:()=>v,indexedDbKv:()=>F,indexedDbSnapshot:()=>R});module.exports=U(W);function h(e){if(e===null||typeof e!="object")return e;if(Array.isArray(e))return e.map(h);let n=e,t=Object.keys(n).sort(),o={};for(let r of t)o[r]=h(n[r]);return o}function x(e){return JSON.stringify(h(e),void 0,0)}var L=new TextEncoder,j=new TextDecoder("utf-8",{fatal:!0}),k={name:"json",version:1,encode(e){return L.encode(x(e))},decode(e){return JSON.parse(j.decode(e))}};function P(e,n={}){let t=n.codec??k,o=n.name??e.name??"snapshot",r=n.keyOf??(l=>l.name??n.name??e.name??"snapshot"),d,u=0,p=n.compactEvery,s,i={name:o,debounceMs:n.debounceMs,compactEvery:p,filter:n.filter,keyOf:r,save(l){if(!(n.filter&&!n.filter(l))&&(d={snapshot:l},u+=1,p!==void 0&&u%p===0||!n.debounceMs))return a()},load(){let l=s??o,c=e.read(l);if(c!==void 0)return c instanceof Uint8Array?c.length===0?void 0:t.decode(c):Promise.resolve(c).then(f=>f===void 0||f.length===0?void 0:t.decode(f))},async flush(){await a()},async rollback(){d=void 0}};function a(){let l=d;if(!l)return;d=void 0;let c=r(l.snapshot),f=t.encode(l.snapshot),m=e.write(c,f);if(m instanceof Promise)return m.then(()=>{s=c});s=c}return i}function A(e,n={}){let t=n.codec??k,o=n.name??e.name??"append-log",r=n.keyOf??(c=>o),d=n.compactEvery,u=new Map,p=0,s,i={name:o,debounceMs:n.debounceMs,compactEvery:d,keyOf:r,appendEntries(c){if(c.length!==0){for(let f of c){let m=r(f),y=u.get(m);y||(y=[],u.set(m,y)),y.push(f)}if(p+=c.length,d!==void 0&&p%d===0||!n.debounceMs)return a()}},async loadEntries(c){let f=c?.keyFilter,m=e.list===void 0?f!==void 0?[f]:[o]:await Promise.resolve(e.list(f)),y=[];for(let S of m){let T=await Promise.resolve(e.read(S));if(T===void 0||T.length===0)continue;let g=t.decode(T);Array.isArray(g)&&y.push(...g)}return{entries:y,cursor:void 0}},async flush(){await a()},async rollback(){u=new Map}};function a(){if(u.size===0)return;let c=u;u=new Map;let f=(s??Promise.resolve()).then(()=>{let m=l(c);return m instanceof Promise?m:Promise.resolve()},()=>{let m=l(c);return m instanceof Promise?m:Promise.resolve()});return s=f.finally(()=>{s===f&&(s=void 0)}),s}function l(c){let f=[];for(let[m,y]of c){let S=e.read(m),T=g=>{let B=[...g===void 0||g.length===0?[]:t.decode(g)??[],...y],D=t.encode(B);return e.write(m,D)};if(S instanceof Promise)f.push(S.then(async g=>{let w=T(g);w instanceof Promise&&await w}));else{let g=T(S);g instanceof Promise&&f.push(g)}}if(f.length>0)return Promise.all(f).then(()=>{})}return i}function O(e,n={}){let t=n.codec??k,o=n.name??e.name??"kv",r=n.compactEvery,d=new Map,u=0,p={name:o,debounceMs:n.debounceMs,compactEvery:r,filter:n.filter,save(i,a){if(!(n.filter&&!n.filter(i,a))&&(d.set(i,a),u+=1,r!==void 0&&u%r===0||!n.debounceMs))return s()},load(i){let a=e.read(i);if(a!==void 0)return a instanceof Uint8Array?a.length===0?void 0:t.decode(a):Promise.resolve(a).then(l=>l===void 0||l.length===0?void 0:t.decode(l))},delete(i){if(d.delete(i),!!e.delete)return e.delete(i)},list(i){return e.list?e.list(i):[]},async flush(){await s()},async rollback(){d=new Map}};function s(){if(d.size===0)return;let i=d;d=new Map;let a=[];for(let[l,c]of i){let f=t.encode(c),m=e.write(l,f);m instanceof Promise&&a.push(m)}if(a.length>0)return Promise.all(a).then(()=>{})}return p}function I(e){return new Promise((n,t)=>{if(typeof indexedDB>"u"){t(new TypeError("indexedDB is not available in this environment"));return}let o=indexedDB.open(e.dbName,e.version??1);o.onupgradeneeded=()=>{let r=o.result;r.objectStoreNames.contains(e.storeName)||r.createObjectStore(e.storeName)},o.onsuccess=()=>n(o.result),o.onerror=()=>t(o.error??new Error(`indexedDbBackend: open(${e.dbName}) failed`))})}function v(e){let n=I(e);return{name:`idb:${e.dbName}/${e.storeName}`,async read(t){let o=await n;return new Promise((r,d)=>{let s=o.transaction(e.storeName,"readonly").objectStore(e.storeName).get(t);s.onsuccess=()=>{let i=s.result;i==null?r(void 0):i instanceof Uint8Array?r(i):i instanceof ArrayBuffer?r(new Uint8Array(i)):r(void 0)},s.onerror=()=>d(s.error)})},async write(t,o){let r=await n;await new Promise((d,u)=>{let p=r.transaction(e.storeName,"readwrite");p.objectStore(e.storeName).put(o,t),p.oncomplete=()=>d(),p.onerror=()=>u(p.error),p.onabort=()=>u(p.error??new Error("indexedDbBackend: write aborted"))})},async delete(t){let o=await n;await new Promise((r,d)=>{let u=o.transaction(e.storeName,"readwrite");u.objectStore(e.storeName).delete(t),u.oncomplete=()=>r(),u.onerror=()=>d(u.error)})},async list(t){let o=await n;return new Promise((r,d)=>{let s=o.transaction(e.storeName,"readonly").objectStore(e.storeName).getAllKeys();s.onsuccess=()=>{let i=s.result.map(a=>String(a));r(t===void 0?i.sort():i.filter(a=>a.startsWith(t)).sort())},s.onerror=()=>d(s.error)})}}}function R(e,n){return P(v(e),n)}function J(e,n){return A(v(e),n)}function F(e,n){return O(v(e),n)}0&&(module.exports={indexedDbAppendLog,indexedDbBackend,indexedDbKv,indexedDbSnapshot});

package/dist/extra/storage-tiers-browser.d.cts

@@ -0,0 +1,49 @@
+import { AppendLogStorageOptions, AppendLogStorageTier, StorageBackend, KvStorageOptions, KvStorageTier, SnapshotStorageOptions, SnapshotStorageTier } from './storage-tiers.cjs';
+
+/**
+ * Browser-only Audit 4 storage backend + convenience factories.
+ *
+ * Uses DOM `IndexedDB`. Browser-safe consumers should import from this module;
+ * Node consumers should not import here without the DOM lib in their tsconfig.
+ *
+ * @module
+ */
+
+type IndexedDbBackendSpec = {
+    dbName: string;
+    storeName: string;
+    version?: number;
+};
+/**
+ * IndexedDB backend. Async by nature — `read` / `write` / `delete` / `list`
+ * all return `Promise`.
+ *
+ * @category extra
+ */
+declare function indexedDbBackend(spec: IndexedDbBackendSpec): StorageBackend;
+/**
+ * IndexedDB snapshot tier — `snapshotStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbSnapshot<T>(spec: IndexedDbBackendSpec, opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
+    name?: string;
+}): SnapshotStorageTier<T>;
+/**
+ * IndexedDB append-log tier — `appendLogStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbAppendLog<T>(spec: IndexedDbBackendSpec, opts?: Omit<AppendLogStorageOptions<T>, "name"> & {
+    name?: string;
+}): AppendLogStorageTier<T>;
+/**
+ * IndexedDB kv tier — `kvStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbKv<T>(spec: IndexedDbBackendSpec, opts?: Omit<KvStorageOptions<T>, "name"> & {
+    name?: string;
+}): KvStorageTier<T>;
+
+export { type IndexedDbBackendSpec, indexedDbAppendLog, indexedDbBackend, indexedDbKv, indexedDbSnapshot };

package/dist/extra/storage-tiers-browser.d.ts

@@ -0,0 +1,49 @@
+import { AppendLogStorageOptions, AppendLogStorageTier, StorageBackend, KvStorageOptions, KvStorageTier, SnapshotStorageOptions, SnapshotStorageTier } from './storage-tiers.js';
+
+/**
+ * Browser-only Audit 4 storage backend + convenience factories.
+ *
+ * Uses DOM `IndexedDB`. Browser-safe consumers should import from this module;
+ * Node consumers should not import here without the DOM lib in their tsconfig.
+ *
+ * @module
+ */
+
+type IndexedDbBackendSpec = {
+    dbName: string;
+    storeName: string;
+    version?: number;
+};
+/**
+ * IndexedDB backend. Async by nature — `read` / `write` / `delete` / `list`
+ * all return `Promise`.
+ *
+ * @category extra
+ */
+declare function indexedDbBackend(spec: IndexedDbBackendSpec): StorageBackend;
+/**
+ * IndexedDB snapshot tier — `snapshotStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbSnapshot<T>(spec: IndexedDbBackendSpec, opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
+    name?: string;
+}): SnapshotStorageTier<T>;
+/**
+ * IndexedDB append-log tier — `appendLogStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbAppendLog<T>(spec: IndexedDbBackendSpec, opts?: Omit<AppendLogStorageOptions<T>, "name"> & {
+    name?: string;
+}): AppendLogStorageTier<T>;
+/**
+ * IndexedDB kv tier — `kvStorage(indexedDbBackend(spec), opts)`.
+ *
+ * @category extra
+ */
+declare function indexedDbKv<T>(spec: IndexedDbBackendSpec, opts?: Omit<KvStorageOptions<T>, "name"> & {
+    name?: string;
+}): KvStorageTier<T>;
+
+export { type IndexedDbBackendSpec, indexedDbAppendLog, indexedDbBackend, indexedDbKv, indexedDbSnapshot };

package/dist/extra/storage-tiers-browser.js

@@ -0,0 +1 @@
+import{a,b,c,d}from"../chunk-F672GV32.js";import"../chunk-D5RFJOZ2.js";import"../chunk-CE72X3WO.js";import"../chunk-QYADASLV.js";export{c as indexedDbAppendLog,a as indexedDbBackend,d as indexedDbKv,b as indexedDbSnapshot};

package/dist/extra/storage-tiers-node.cjs

@@ -0,0 +1 @@
+"use strict";var A=Object.defineProperty;var U=Object.getOwnPropertyDescriptor;var N=Object.getOwnPropertyNames;var F=Object.prototype.hasOwnProperty;var j=(n,e)=>{for(var t in e)A(n,t,{get:e[t],enumerable:!0})},_=(n,e,t,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let l of N(e))!F.call(n,l)&&l!==t&&A(n,l,{get:()=>e[l],enumerable:!(s=U(e,l))||s.enumerable});return n};var W=n=>_(A({},"__esModule",{value:!0}),n);var V={};j(V,{fileAppendLog:()=>J,fileBackend:()=>k,fileKv:()=>H,fileSnapshot:()=>I,sqliteAppendLog:()=>z,sqliteBackend:()=>w,sqliteKv:()=>Y,sqliteSnapshot:()=>q});module.exports=W(V);var C=require("node:crypto"),m=require("node:fs"),S=require("node:path"),R=require("node:sqlite");function E(n){if(n===null||typeof n!="object")return n;if(Array.isArray(n))return n.map(E);let e=n,t=Object.keys(e).sort(),s={};for(let l of t)s[l]=E(e[l]);return s}function M(n){return JSON.stringify(E(n),void 0,0)}var $=new TextEncoder,D=new TextDecoder("utf-8",{fatal:!0}),b={name:"json",version:1,encode(n){return $.encode(M(n))},decode(n){return JSON.parse(D.decode(n))}};function P(n,e={}){let t=e.codec??b,s=e.name??n.name??"snapshot",l=e.keyOf??(d=>d.name??e.name??n.name??"snapshot"),o,r=0,c=e.compactEvery,f,a={name:s,debounceMs:e.debounceMs,compactEvery:c,filter:e.filter,keyOf:l,save(d){if(!(e.filter&&!e.filter(d))&&(o={snapshot:d},r+=1,c!==void 0&&r%c===0||!e.debounceMs))return i()},load(){let d=f??s,u=n.read(d);if(u!==void 0)return u instanceof Uint8Array?u.length===0?void 0:t.decode(u):Promise.resolve(u).then(p=>p===void 0||p.length===0?void 0:t.decode(p))},async flush(){await i()},async rollback(){o=void 0}};function i(){let d=o;if(!d)return;o=void 0;let u=l(d.snapshot),p=t.encode(d.snapshot),g=n.write(u,p);if(g instanceof Promise)return g.then(()=>{f=u});f=u}return a}function x(n,e={}){let t=e.codec??b,s=e.name??n.name??"append-log",l=e.keyOf??(u=>s),o=e.compactEvery,r=new Map,c=0,f,a={name:s,debounceMs:e.debounceMs,compactEvery:o,keyOf:l,appendEntries(u){if(u.length!==0){for(let p of u){let g=l(p),y=r.get(g);y||(y=[],r.set(g,y)),y.push(p)}if(c+=u.length,o!==void 0&&c%o===0||!e.debounceMs)return i()}},async loadEntries(u){let p=u?.keyFilter,g=n.list===void 0?p!==void 0?[p]:[s]:await Promise.resolve(n.list(p)),y=[];for(let v of g){let h=await Promise.resolve(n.read(v));if(h===void 0||h.length===0)continue;let T=t.decode(h);Array.isArray(T)&&y.push(...T)}return{entries:y,cursor:void 0}},async flush(){await i()},async rollback(){r=new Map}};function i(){if(r.size===0)return;let u=r;r=new Map;let p=(f??Promise.resolve()).then(()=>{let g=d(u);return g instanceof Promise?g:Promise.resolve()},()=>{let g=d(u);return g instanceof Promise?g:Promise.resolve()});return f=p.finally(()=>{f===p&&(f=void 0)}),f}function d(u){let p=[];for(let[g,y]of u){let v=n.read(g),h=T=>{let B=[...T===void 0||T.length===0?[]:t.decode(T)??[],...y],K=t.encode(B);return n.write(g,K)};if(v instanceof Promise)p.push(v.then(async T=>{let O=h(T);O instanceof Promise&&await O}));else{let T=h(v);T instanceof Promise&&p.push(T)}}if(p.length>0)return Promise.all(p).then(()=>{})}return a}function L(n,e={}){let t=e.codec??b,s=e.name??n.name??"kv",l=e.compactEvery,o=new Map,r=0,c={name:s,debounceMs:e.debounceMs,compactEvery:l,filter:e.filter,save(a,i){if(!(e.filter&&!e.filter(a,i))&&(o.set(a,i),r+=1,l!==void 0&&r%l===0||!e.debounceMs))return f()},load(a){let i=n.read(a);if(i!==void 0)return i instanceof Uint8Array?i.length===0?void 0:t.decode(i):Promise.resolve(i).then(d=>d===void 0||d.length===0?void 0:t.decode(d))},delete(a){if(o.delete(a),!!n.delete)return n.delete(a)},list(a){return n.list?n.list(a):[]},async flush(){await f()},async rollback(){o=new Map}};function f(){if(o.size===0)return;let a=o;o=new Map;let i=[];for(let[d,u]of a){let p=t.encode(u),g=n.write(d,p);g instanceof Promise&&i.push(g)}if(i.length>0)return Promise.all(i).then(()=>{})}return c}function k(n){let e=new TextEncoder,t=new TextDecoder("utf-8",{fatal:!0}),s=o=>{let r="";for(let c of o){if(c.length===1&&/[a-zA-Z0-9_-]/.test(c)){r+=c;continue}for(let f of e.encode(c))r+=`%${f.toString(16).padStart(2,"0")}`}return(0,S.join)(n,`${r}.bin`)},l=o=>{if(!o.endsWith(".bin"))return null;let r=o.slice(0,-4),c=[],f=i=>{for(let d=0;d<i.length;d++)c.push(i.charCodeAt(d))},a=0;for(;a<r.length;){let i=r[a];if(i==="%"&&a+2<r.length){let d=r.slice(a+1,a+3);if(/^[0-9a-f]{2}$/i.test(d)){c.push(Number.parseInt(d,16)),a+=3;continue}}f(i),a+=1}try{return t.decode(new Uint8Array(c))}catch{return null}};return{name:`file:${n}`,read(o){try{let r=(0,m.readFileSync)(s(o));return new Uint8Array(r.buffer,r.byteOffset,r.byteLength)}catch{return}},write(o,r){(0,m.mkdirSync)(n,{recursive:!0});let c=s(o),f=(0,S.basename)(c),a=(0,S.dirname)(c),i=(0,S.join)(a,`.${f}.${(0,C.randomBytes)(8).toString("hex")}.tmp`);try{(0,m.writeFileSync)(i,r),(0,m.renameSync)(i,c)}catch(d){try{(0,m.unlinkSync)(i)}catch{}throw d}},delete(o){try{(0,m.unlinkSync)(s(o))}catch(r){if(r.code!=="ENOENT")throw r}},list(o){try{let r=(0,m.readdirSync)(n),c=[];for(let f of r){if(f.startsWith("."))continue;let a=l(f);a!==null&&(o!==void 0&&!a.startsWith(o)||c.push(a))}return c.sort()}catch(r){if(r.code==="ENOENT")return[];throw r}}}}function w(n){let e=new R.DatabaseSync(n);return e.exec("CREATE TABLE IF NOT EXISTS graphrefly_storage (k TEXT PRIMARY KEY, v BLOB NOT NULL)"),{name:`sqlite:${n}`,read(t){return e.prepare("SELECT v FROM graphrefly_storage WHERE k = ?").get(t)?.v},write(t,s){e.prepare("INSERT OR REPLACE INTO graphrefly_storage (k, v) VALUES (?, ?)").run(t,s)},delete(t){e.prepare("DELETE FROM graphrefly_storage WHERE k = ?").run(t)},list(t){if(t===void 0)return e.prepare("SELECT k FROM graphrefly_storage ORDER BY k").all().map(r=>r.k);let s=t.replace(/[\\%_]/g,"\\$&");return e.prepare("SELECT k FROM graphrefly_storage WHERE k LIKE ? ESCAPE '\\' ORDER BY k").all(`${s}%`).map(o=>o.k)},close(){try{e.close()}catch{}}}}function I(n,e){return P(k(n),e)}function J(n,e){return x(k(n),e)}function q(n,e){let t=w(n),s=P(t,e);return Object.assign(s,{close:()=>t.close()})}function z(n,e){let t=w(n),s=x(t,e);return Object.assign(s,{close:()=>t.close()})}function H(n,e){return L(k(n),e)}function Y(n,e){let t=w(n),s=L(t,e);return Object.assign(s,{close:()=>t.close()})}0&&(module.exports={fileAppendLog,fileBackend,fileKv,fileSnapshot,sqliteAppendLog,sqliteBackend,sqliteKv,sqliteSnapshot});