@graphrefly/graphrefly 0.37.0 → 0.38.0

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

@@ -15,14 +15,48 @@ type IndexedDbBackendSpec = {
     version?: number;
 };
 /**
- * IndexedDB backend. Async by nature — `read` / `write` / `delete` / `list`
- * all return `Promise`.
+ * Creates an IndexedDB backend for browser-based persistent storage.
+ *
+ * All operations (`read`, `write`, `delete`, `list`) are async and return
+ * `Promise`. The backing object store is created automatically on first open
+ * if it does not already exist.
+ *
+ * @param spec - Database name, object store name, and optional schema version.
+ * @returns `StorageBackend` backed by an IndexedDB object store.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbBackend, snapshotStorage } from "@graphrefly/graphrefly/extra/browser";
+ *
+ * const backend = indexedDbBackend({ dbName: "my-app", storeName: "snapshots" });
+ * const tier = snapshotStorage(backend, { name: "graph1" });
+ * await tier.save({ name: "graph1", state: {} });
+ * ```
  *
  * @category extra
  */
 declare function indexedDbBackend(spec: IndexedDbBackendSpec): StorageBackend;
 /**
- * IndexedDB snapshot tier — `snapshotStorage(indexedDbBackend(spec), opts)`.
+ * Creates an IndexedDB snapshot tier backed by an `indexedDbBackend`.
+ *
+ * Convenience wrapper for `snapshotStorage(indexedDbBackend(spec), opts)`.
+ * All reads and writes are async via IndexedDB. Requires a browser or
+ * browser-compatible environment.
+ *
+ * @param spec - Database name, object store name, and optional schema version.
+ * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
+ * @returns `SnapshotStorageTier<T>` backed by IndexedDB.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbSnapshot } from "@graphrefly/graphrefly/extra/browser";
+ *
+ * const tier = indexedDbSnapshot<{ count: number }>(
+ *   { dbName: "my-app", storeName: "snapshots" },
+ *   { name: "counter" },
+ * );
+ * await tier.save({ count: 1 });
+ * ```
  *
  * @category extra
  */
@@ -30,7 +64,25 @@ declare function indexedDbSnapshot<T>(spec: IndexedDbBackendSpec, opts?: Omit<Sn
     name?: string;
 }): SnapshotStorageTier<T>;
 /**
- * IndexedDB append-log tier — `appendLogStorage(indexedDbBackend(spec), opts)`.
+ * Creates an IndexedDB append-log tier backed by an `indexedDbBackend`.
+ *
+ * Convenience wrapper for `appendLogStorage(indexedDbBackend(spec), opts)`.
+ * All reads and writes are async via IndexedDB. Requires a browser or
+ * browser-compatible environment.
+ *
+ * @param spec - Database name, object store name, and optional schema version.
+ * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
+ * @returns `AppendLogStorageTier<T>` backed by IndexedDB.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbAppendLog } from "@graphrefly/graphrefly/extra/browser";
+ *
+ * const tier = indexedDbAppendLog<{ type: string }>(
+ *   { dbName: "my-app", storeName: "events" },
+ * );
+ * await tier.appendEntries([{ type: "init" }]);
+ * ```
  *
  * @category extra
  */
@@ -38,7 +90,26 @@ declare function indexedDbAppendLog<T>(spec: IndexedDbBackendSpec, opts?: Omit<A
     name?: string;
 }): AppendLogStorageTier<T>;
 /**
- * IndexedDB kv tier — `kvStorage(indexedDbBackend(spec), opts)`.
+ * Creates an IndexedDB key-value tier backed by an `indexedDbBackend`.
+ *
+ * Convenience wrapper for `kvStorage(indexedDbBackend(spec), opts)`.
+ * All reads and writes are async via IndexedDB. Requires a browser or
+ * browser-compatible environment.
+ *
+ * @param spec - Database name, object store name, and optional schema version.
+ * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
+ * @returns `KvStorageTier<T>` backed by IndexedDB.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbKv } from "@graphrefly/graphrefly/extra/browser";
+ *
+ * const kv = indexedDbKv<{ score: number }>(
+ *   { dbName: "my-app", storeName: "scores" },
+ * );
+ * await kv.save("player1", { score: 100 });
+ * const val = await kv.load("player1");
+ * ```
  *
  * @category extra
  */

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

@@ -10,15 +10,45 @@ import { AppendLogStorageOptions, AppendLogStorageTier, StorageBackend, KvStorag
  */
 
 /**
- * Filesystem backend. Each key becomes a file under `dir`; values are written
- * via temp + rename for atomic replace.
+ * Creates a filesystem backend that maps each key to a file under `dir`.
+ *
+ * Writes are atomic via temp + rename. Keys are percent-encoded to safe
+ * filenames; `list(prefix)` enumerates `.bin` files in the directory.
+ *
+ * @param dir - Directory path where key files are stored (created on first write).
+ * @returns `StorageBackend` backed by the filesystem under `dir`.
+ *
+ * @example
+ * ```ts
+ * import { fileBackend, snapshotStorage } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const backend = fileBackend("./checkpoints");
+ * const tier = snapshotStorage(backend, { name: "my-graph" });
+ * await tier.save({ name: "my-graph", state: { count: 1 } });
+ * ```
  *
  * @category extra
  */
 declare function fileBackend(dir: string): StorageBackend;
 /**
- * SQLite backend (Node 22.5+ `node:sqlite`). Stores byte values under string
- * keys in a single table; caller owns the connection lifetime via `close()`.
+ * Creates a SQLite backend using Node 22.5+ `node:sqlite`.
+ *
+ * Stores byte values under string keys in a single `graphrefly_storage` table.
+ * The caller owns the connection lifetime — call `.close()` for explicit teardown.
+ * Requires Node 22.5 or later for `node:sqlite`.
+ *
+ * @param path - Filesystem path to the SQLite database file (created if absent).
+ * @returns `StorageBackend` with an extra `close()` method for explicit teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteBackend, snapshotStorage } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const backend = sqliteBackend("./state.db");
+ * const tier = snapshotStorage(backend, { name: "my-graph" });
+ * await tier.save({ name: "my-graph", state: { count: 1 } });
+ * backend.close();
+ * ```
  *
  * @category extra
  */
@@ -26,7 +56,22 @@ declare function sqliteBackend(path: string): StorageBackend & {
     close(): void;
 };
 /**
- * Filesystem snapshot tier — `snapshotStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem snapshot tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `snapshotStorage(fileBackend(dir), opts)`.
+ * Writes are atomic (temp + rename). Requires Node.js with filesystem access.
+ *
+ * @param dir - Directory path where snapshot files are stored.
+ * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
+ * @returns `SnapshotStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileSnapshot } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = fileSnapshot<{ count: number }>("./checkpoints", { name: "counter" });
+ * await tier.save({ count: 1 });
+ * ```
  *
  * @category extra
  */
@@ -34,7 +79,22 @@ declare function fileSnapshot<T>(dir: string, opts?: Omit<SnapshotStorageOptions
     name?: string;
 }): SnapshotStorageTier<T>;
 /**
- * Filesystem append-log tier — `appendLogStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem append-log tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `appendLogStorage(fileBackend(dir), opts)`.
+ * Writes are atomic (temp + rename). Requires Node.js with filesystem access.
+ *
+ * @param dir - Directory path where append-log files are stored.
+ * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
+ * @returns `AppendLogStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileAppendLog } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = fileAppendLog<{ type: string; id: number }>("./events");
+ * await tier.appendEntries([{ type: "created", id: 1 }]);
+ * ```
  *
  * @category extra
  */
@@ -42,8 +102,24 @@ declare function fileAppendLog<T>(dir: string, opts?: Omit<AppendLogStorageOptio
     name?: string;
 }): AppendLogStorageTier<T>;
 /**
- * SQLite snapshot tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite snapshot tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `snapshotStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
+ * @returns `SnapshotStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteSnapshot } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = sqliteSnapshot<{ count: number }>("./state.db", { name: "counter" });
+ * await tier.save({ count: 42 });
+ * tier.close();
+ * ```
  *
  * @category extra
  */
@@ -53,8 +129,24 @@ declare function sqliteSnapshot<T>(path: string, opts?: Omit<SnapshotStorageOpti
     close(): void;
 };
 /**
- * SQLite append-log tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite append-log tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `appendLogStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
+ * @returns `AppendLogStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteAppendLog } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = sqliteAppendLog<{ type: string }>("./events.db", { name: "events" });
+ * await tier.appendEntries([{ type: "created" }]);
+ * tier.close();
+ * ```
  *
  * @category extra
  */
@@ -64,7 +156,23 @@ declare function sqliteAppendLog<T>(path: string, opts?: Omit<AppendLogStorageOp
     close(): void;
 };
 /**
- * Filesystem kv tier — `kvStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem key-value tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `kvStorage(fileBackend(dir), opts)`.
+ * Each key is stored as a separate file; writes are atomic (temp + rename).
+ *
+ * @param dir - Directory path where key files are stored.
+ * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
+ * @returns `KvStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileKv } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const kv = fileKv<{ score: number }>("./scores");
+ * await kv.save("player1", { score: 100 });
+ * const val = await kv.load("player1");
+ * ```
  *
  * @category extra
  */
@@ -72,8 +180,24 @@ declare function fileKv<T>(dir: string, opts?: Omit<KvStorageOptions<T>, "name">
     name?: string;
 }): KvStorageTier<T>;
 /**
- * SQLite kv tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite key-value tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `kvStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
+ * @returns `KvStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteKv } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const kv = sqliteKv<{ score: number }>("./scores.db");
+ * await kv.save("player1", { score: 100 });
+ * kv.close();
+ * ```
  *
  * @category extra
  */

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

@@ -10,15 +10,45 @@ import { AppendLogStorageOptions, AppendLogStorageTier, StorageBackend, KvStorag
  */
 
 /**
- * Filesystem backend. Each key becomes a file under `dir`; values are written
- * via temp + rename for atomic replace.
+ * Creates a filesystem backend that maps each key to a file under `dir`.
+ *
+ * Writes are atomic via temp + rename. Keys are percent-encoded to safe
+ * filenames; `list(prefix)` enumerates `.bin` files in the directory.
+ *
+ * @param dir - Directory path where key files are stored (created on first write).
+ * @returns `StorageBackend` backed by the filesystem under `dir`.
+ *
+ * @example
+ * ```ts
+ * import { fileBackend, snapshotStorage } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const backend = fileBackend("./checkpoints");
+ * const tier = snapshotStorage(backend, { name: "my-graph" });
+ * await tier.save({ name: "my-graph", state: { count: 1 } });
+ * ```
  *
  * @category extra
  */
 declare function fileBackend(dir: string): StorageBackend;
 /**
- * SQLite backend (Node 22.5+ `node:sqlite`). Stores byte values under string
- * keys in a single table; caller owns the connection lifetime via `close()`.
+ * Creates a SQLite backend using Node 22.5+ `node:sqlite`.
+ *
+ * Stores byte values under string keys in a single `graphrefly_storage` table.
+ * The caller owns the connection lifetime — call `.close()` for explicit teardown.
+ * Requires Node 22.5 or later for `node:sqlite`.
+ *
+ * @param path - Filesystem path to the SQLite database file (created if absent).
+ * @returns `StorageBackend` with an extra `close()` method for explicit teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteBackend, snapshotStorage } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const backend = sqliteBackend("./state.db");
+ * const tier = snapshotStorage(backend, { name: "my-graph" });
+ * await tier.save({ name: "my-graph", state: { count: 1 } });
+ * backend.close();
+ * ```
  *
  * @category extra
  */
@@ -26,7 +56,22 @@ declare function sqliteBackend(path: string): StorageBackend & {
     close(): void;
 };
 /**
- * Filesystem snapshot tier — `snapshotStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem snapshot tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `snapshotStorage(fileBackend(dir), opts)`.
+ * Writes are atomic (temp + rename). Requires Node.js with filesystem access.
+ *
+ * @param dir - Directory path where snapshot files are stored.
+ * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
+ * @returns `SnapshotStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileSnapshot } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = fileSnapshot<{ count: number }>("./checkpoints", { name: "counter" });
+ * await tier.save({ count: 1 });
+ * ```
  *
  * @category extra
  */
@@ -34,7 +79,22 @@ declare function fileSnapshot<T>(dir: string, opts?: Omit<SnapshotStorageOptions
     name?: string;
 }): SnapshotStorageTier<T>;
 /**
- * Filesystem append-log tier — `appendLogStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem append-log tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `appendLogStorage(fileBackend(dir), opts)`.
+ * Writes are atomic (temp + rename). Requires Node.js with filesystem access.
+ *
+ * @param dir - Directory path where append-log files are stored.
+ * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
+ * @returns `AppendLogStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileAppendLog } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = fileAppendLog<{ type: string; id: number }>("./events");
+ * await tier.appendEntries([{ type: "created", id: 1 }]);
+ * ```
  *
  * @category extra
  */
@@ -42,8 +102,24 @@ declare function fileAppendLog<T>(dir: string, opts?: Omit<AppendLogStorageOptio
     name?: string;
 }): AppendLogStorageTier<T>;
 /**
- * SQLite snapshot tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite snapshot tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `snapshotStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
+ * @returns `SnapshotStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteSnapshot } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = sqliteSnapshot<{ count: number }>("./state.db", { name: "counter" });
+ * await tier.save({ count: 42 });
+ * tier.close();
+ * ```
  *
  * @category extra
  */
@@ -53,8 +129,24 @@ declare function sqliteSnapshot<T>(path: string, opts?: Omit<SnapshotStorageOpti
     close(): void;
 };
 /**
- * SQLite append-log tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite append-log tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `appendLogStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
+ * @returns `AppendLogStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteAppendLog } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const tier = sqliteAppendLog<{ type: string }>("./events.db", { name: "events" });
+ * await tier.appendEntries([{ type: "created" }]);
+ * tier.close();
+ * ```
  *
  * @category extra
  */
@@ -64,7 +156,23 @@ declare function sqliteAppendLog<T>(path: string, opts?: Omit<AppendLogStorageOp
     close(): void;
 };
 /**
- * Filesystem kv tier — `kvStorage(fileBackend(dir), opts)`.
+ * Creates a filesystem key-value tier backed by a `fileBackend` under `dir`.
+ *
+ * Convenience wrapper for `kvStorage(fileBackend(dir), opts)`.
+ * Each key is stored as a separate file; writes are atomic (temp + rename).
+ *
+ * @param dir - Directory path where key files are stored.
+ * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
+ * @returns `KvStorageTier<T>` backed by the filesystem.
+ *
+ * @example
+ * ```ts
+ * import { fileKv } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const kv = fileKv<{ score: number }>("./scores");
+ * await kv.save("player1", { score: 100 });
+ * const val = await kv.load("player1");
+ * ```
  *
  * @category extra
  */
@@ -72,8 +180,24 @@ declare function fileKv<T>(dir: string, opts?: Omit<KvStorageOptions<T>, "name">
     name?: string;
 }): KvStorageTier<T>;
 /**
- * SQLite kv tier — caller owns the connection. Use the underlying
- * backend's `close()` for explicit teardown.
+ * Creates a SQLite key-value tier; caller owns the connection lifetime.
+ *
+ * Convenience wrapper for `kvStorage(sqliteBackend(path), opts)`.
+ * The returned tier exposes an extra `close()` method — call it for explicit
+ * teardown of the underlying SQLite connection.
+ *
+ * @param path - Filesystem path to the SQLite database file.
+ * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
+ * @returns `KvStorageTier<T>` with a `close()` method for connection teardown.
+ *
+ * @example
+ * ```ts
+ * import { sqliteKv } from "@graphrefly/graphrefly/extra/node";
+ *
+ * const kv = sqliteKv<{ score: number }>("./scores.db");
+ * await kv.save("player1", { score: 100 });
+ * kv.close();
+ * ```
  *
  * @category extra
  */