@graphrefly/graphrefly 0.44.0 → 0.45.0

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

@@ -1,412 +1 @@
-/**
- * Storage tier architecture (Audit 4 — locked 2026-04-24).
- *
- * Three-layer design:
- *
- * - **Layer 1 — {@link StorageBackend}:** generic bytes-level kv I/O. One
- *   `read(key) → Uint8Array | undefined`, `write(key, bytes)`, optional
- *   `delete(key)` / `list(prefix)`. No tier-level concerns (debounce, codec).
- * - **Layer 2 — Tier specializations** layered over a backend, parametric over
- *   `T`: {@link SnapshotStorageTier} (one snapshot under one key) and
- *   {@link AppendLogStorageTier} (sequential entries, optional partition via
- *   `keyOf`). Both extend {@link BaseStorageTier} which carries
- *   `flush?` / `rollback?` for the wave-as-transaction model.
- * - **Layer 3 — High-level wiring:** `Graph.attachSnapshotStorage(tiers)`,
- *   `reactiveLog.attachStorage(tiers)`, `cqrsGraph.attachEventStorage(tiers)`,
- *   `jobQueueGraph.attachEventStorage(tiers)`. These layers consume tier
- *   specializations directly — they don't see the backend.
- *
- * Browser-safe by default. {@link memoryBackend} + the in-memory factories
- * live here; Node-only (`fileBackend` / `sqliteBackend`) lives in
- * `extra/storage-node.ts`; browser-only (`indexedDbBackend`) lives in
- * `extra/storage-browser.ts`.
- *
- * @module
- */
-/**
- * Bytes-level kv backend. One responsibility: read/write byte ranges under
- * string keys. Tier specializations layer on top.
- *
- * @category extra
- */
-interface StorageBackend {
-    /** Diagnostic name (e.g., `"memory"`, `"file:./checkpoints"`). */
-    readonly name: string;
-    /** Read raw bytes; returns `undefined` on miss. */
-    read(key: string): Uint8Array | undefined | Promise<Uint8Array | undefined>;
-    /** Write raw bytes. Sync backends return `void`; async return `Promise<void>`. */
-    write(key: string, bytes: Uint8Array): void | Promise<void>;
-    /** Optional delete-by-key. */
-    delete?(key: string): void | Promise<void>;
-    /** Optional enumeration; `prefix` filters keys. */
-    list?(prefix?: string): readonly string[] | Promise<readonly string[]>;
-    /** Optional drain hook — adapter authors implement when buffering writes. */
-    flush?(): Promise<void>;
-}
-/**
- * Codec for tier serialization. Tiers call `encode(value) → bytes` before
- * `backend.write` and `decode(bytes) → value` after `backend.read`.
- *
- * @category extra
- */
-interface Codec<T = unknown> {
-    readonly name: string;
-    readonly version: number;
-    encode(value: T): Uint8Array;
-    decode(bytes: Uint8Array): T;
-}
-/**
- * Default JSON codec — UTF-8 text, stable key order (via `stableJsonString`).
- * Any value JSON-serializable is supported.
- *
- * @category extra
- */
-declare const jsonCodec: Codec<unknown>;
-/**
- * Returns the default `jsonCodec` cast to `Codec<T>`.
- *
- * Pure typing helper — no runtime overhead. Use when a generic API requires a
- * `Codec<T>` and the value is known to be JSON-serializable.
- *
- * @returns `Codec<T>` backed by the shared `jsonCodec` (UTF-8 JSON, stable key order).
- *
- * @example
- * ```ts
- * import { memoryBackend, snapshotStorage, jsonCodecFor } from "@graphrefly/graphrefly/extra";
- *
- * type MyState = { count: number; label: string };
- * const tier = snapshotStorage<MyState>(memoryBackend(), {
- *   codec: jsonCodecFor<MyState>(),
- * });
- * ```
- *
- * @category extra
- */
-declare function jsonCodecFor<T>(): Codec<T>;
-/**
- * Common tier surface: name + cadence knobs + transaction lifecycle.
- *
- * Lifecycle hooks (`flush` / `rollback`) implement Audit 4's "one wave = one
- * transaction" model. Framework integration:
- *  - After every wave (and on `batch()` close), framework iterates attached
- *    tiers and calls `tier.flush()` if exposed.
- *  - On wave-throw (per C.2 F rollback policy), framework calls
- *    `tier.rollback()` if exposed — pending writes discarded.
- *  - Cross-tier atomicity is best-effort. Each tier is its own transaction.
- *
- * @category extra
- */
-interface BaseStorageTier {
-    readonly name: string;
-    /** Debounce window (ms). `0` = sync-through; >0 batches across waves. */
-    readonly debounceMs?: number;
-    /** Force flush every Nth write regardless of debounce. */
-    readonly compactEvery?: number;
-    /** Commit pending; framework calls at wave-close / debounce-fire. */
-    flush?(): Promise<void>;
-    /** Discard pending; framework calls on wave-throw. */
-    rollback?(): Promise<void>;
-}
-/**
- * Snapshot tier — writes a single record per `save(snapshot)` call.
- *
- * The tier maps the snapshot to a backend key via `keyOf(snapshot)` (default
- * `() => name ?? "snapshot"`). For `Graph.attachSnapshotStorage`, the framework
- * supplies a closure that pulls the graph name out of the record envelope.
- *
- * @category extra
- */
-interface SnapshotStorageTier<T = unknown> extends BaseStorageTier {
-    save(snapshot: T): void | Promise<void>;
-    load?(): T | Promise<T | undefined> | undefined;
-    /** Skip-save policy — return `false` to skip persisting this snapshot. */
-    filter?: (snapshot: T) => boolean;
-    /** Extract the backend key per-snapshot; default `() => name ?? "snapshot"`. */
-    keyOf?: (snapshot: T) => string;
-}
-/**
- * Append-log tier — bulk-friendly entry persistence with optional partitioning.
- *
- * Entries are appended to a logical stream; `keyOf?` partitions across backend
- * keys (e.g., `(e) => `${e.type}::${e.aggregateId}`` for CQRS).
- *
- * @category extra
- */
-interface AppendLogStorageTier<T = unknown> extends BaseStorageTier {
-    appendEntries(entries: readonly T[]): void | Promise<void>;
-    loadEntries?(opts?: {
-        cursor?: AppendCursor;
-        pageSize?: number;
-        keyFilter?: string;
-    }): AppendLoadResult<T> | Promise<AppendLoadResult<T>>;
-    /** Partition key per-entry (default `() => name ?? "append-log"`). */
-    keyOf?: (entry: T) => string;
-}
-/** Opaque cursor for windowed `loadEntries` pagination. */
-type AppendCursor = Readonly<{
-    position: number;
-    tag?: string;
-}> & {
-    readonly __brand: "AppendCursor";
-};
-type AppendLoadResult<T> = {
-    entries: readonly T[];
-    cursor: AppendCursor | undefined;
-};
-/**
- * Creates an in-process bytes backend backed by `Map<string, Uint8Array>`.
- *
- * Useful for tests, hot tiers, and as the default backend for the convenience
- * factories in this module. All operations are synchronous.
- *
- * @returns `StorageBackend` instance backed by an in-memory `Map`.
- *
- * @example
- * ```ts
- * import { memoryBackend, snapshotStorage } from "@graphrefly/graphrefly/extra";
- *
- * const backend = memoryBackend();
- * const tier = snapshotStorage(backend, { name: "my-graph" });
- * await tier.save({ name: "my-graph", data: { count: 1 } });
- * ```
- *
- * @category extra
- */
-declare function memoryBackend(): StorageBackend;
-type SnapshotStorageOptions<T> = {
-    name?: string;
-    codec?: Codec<T>;
-    debounceMs?: number;
-    compactEvery?: number;
-    filter?: (snapshot: T) => boolean;
-    keyOf?: (snapshot: T) => string;
-};
-/**
- * Wraps a `StorageBackend` as a typed snapshot tier.
- *
- * Buffer model: `save(snapshot)` accumulates one pending snapshot in memory.
- * `flush()` encodes via codec and writes to the backend under
- * `keyOf(snapshot)` (default `name ?? "snapshot"`). `rollback()` discards
- * the pending write.
- *
- * @param backend - Bytes-level backend to persist snapshots into.
- * @param opts - Optional name, codec, debounce window, compaction interval, pre-save filter, and key extractor.
- * @returns `SnapshotStorageTier<T>` that buffers one pending snapshot and flushes on wave-close.
- *
- * @example
- * ```ts
- * import { memoryBackend, snapshotStorage } from "@graphrefly/graphrefly/extra";
- *
- * const backend = memoryBackend();
- * const tier = snapshotStorage<{ count: number }>(backend, { name: "counter" });
- * await tier.save({ count: 42 });
- * // Load back:
- * const loaded = await tier.load?.();
- * ```
- *
- * @category extra
- */
-declare function snapshotStorage<T>(backend: StorageBackend, opts?: SnapshotStorageOptions<T>): SnapshotStorageTier<T>;
-type AppendLogStorageOptions<T> = {
-    name?: string;
-    codec?: Codec<readonly T[]>;
-    keyOf?: (entry: T) => string;
-    debounceMs?: number;
-    compactEvery?: number;
-};
-/**
- * Wraps a `StorageBackend` as a typed append-log tier.
- *
- * Buffer model: `appendEntries(entries)` accumulates per-key buckets in
- * memory. `flush()` encodes each bucket as a JSON array via codec and writes
- * under that bucket key. `rollback()` discards pending appends.
- *
- * Storage shape: each backend key holds a JSON array of all entries for that
- * partition, growing on every flush. Adapters that need true append semantics
- * (versus rewrite) should layer their own tier impl over the same backend.
- *
- * @param backend - Bytes-level backend to persist log entries into.
- * @param opts - Optional name, codec, per-entry key extractor, debounce window, and compaction interval.
- * @returns `AppendLogStorageTier<T>` that buffers pending entries and flushes per-key buckets on wave-close.
- *
- * @example
- * ```ts
- * import { memoryBackend, appendLogStorage } from "@graphrefly/graphrefly/extra";
- *
- * const backend = memoryBackend();
- * const tier = appendLogStorage<{ type: string; payload: unknown }>(backend, { name: "events" });
- * await tier.appendEntries([{ type: "created", payload: { id: 1 } }]);
- * const result = await tier.loadEntries?.();
- * ```
- *
- * @category extra
- */
-declare function appendLogStorage<T>(backend: StorageBackend, opts?: AppendLogStorageOptions<T>): AppendLogStorageTier<T>;
-/**
- * Key-value tier — typed records under arbitrary string keys with codec
- * serialization at the storage-tier boundary. Use for content-addressed
- * caches (replay), multi-record archives (snapshot index, AI memory), and
- * fixture stores. Snapshot tier is "one record"; append-log is "sequential
- * entries"; kv is "many records, addressable by key".
- *
- * @category extra
- */
-interface KvStorageTier<T = unknown> extends BaseStorageTier {
-    load(key: string): T | undefined | Promise<T | undefined>;
-    save(key: string, value: T): void | Promise<void>;
-    delete?(key: string): void | Promise<void>;
-    list?(prefix?: string): readonly string[] | Promise<readonly string[]>;
-    /** Pre-save filter — return `false` to skip persisting this record. */
-    filter?: (key: string, value: T) => boolean;
-}
-type KvStorageOptions<T> = {
-    name?: string;
-    codec?: Codec<T>;
-    debounceMs?: number;
-    compactEvery?: number;
-    filter?: (key: string, value: T) => boolean;
-};
-/**
- * Wraps a `StorageBackend` as a typed key-value tier.
- *
- * Buffer model: `save(k, v)` encodes via codec and writes to the backend
- * unless debounced. Pending writes are committed on `flush()` and discarded
- * on `rollback()` — the wave-as-transaction model.
- *
- * @param backend - Bytes-level backend to persist records into.
- * @param opts - Optional name, codec, debounce window, compaction interval, and pre-save filter.
- * @returns `KvStorageTier<T>` that supports `save`, `load`, `delete`, and `list` operations.
- *
- * @example
- * ```ts
- * import { memoryBackend, kvStorage } from "@graphrefly/graphrefly/extra";
- *
- * const backend = memoryBackend();
- * const kv = kvStorage<{ score: number }>(backend, { name: "scores" });
- * await kv.save("player1", { score: 100 });
- * const val = await kv.load("player1");
- * ```
- *
- * @category extra
- */
-declare function kvStorage<T>(backend: StorageBackend, opts?: KvStorageOptions<T>): KvStorageTier<T>;
-/**
- * Creates an in-memory snapshot tier backed by a fresh `memoryBackend`.
- *
- * Convenience wrapper for `snapshotStorage(memoryBackend(), opts)`. All writes
- * are synchronous and in-process — useful for tests and hot-path caching.
- *
- * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
- * @returns `SnapshotStorageTier<T>` backed by an in-memory store.
- *
- * @example
- * ```ts
- * import { memorySnapshot } from "@graphrefly/graphrefly/extra";
- *
- * const tier = memorySnapshot<{ count: number }>({ name: "counter" });
- * await tier.save({ count: 1 });
- * ```
- *
- * @category extra
- */
-declare function memorySnapshot<T>(opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
-    name?: string;
-}): SnapshotStorageTier<T>;
-/**
- * Creates an in-memory append-log tier backed by a fresh `memoryBackend`.
- *
- * Convenience wrapper for `appendLogStorage(memoryBackend(), opts)`. All writes
- * are synchronous and in-process — useful for tests and hot-path event buffering.
- *
- * @param opts - Optional append-log storage options (name, codec, keyOf, debounce, compactEvery).
- * @returns `AppendLogStorageTier<T>` backed by an in-memory store.
- *
- * @example
- * ```ts
- * import { memoryAppendLog } from "@graphrefly/graphrefly/extra";
- *
- * const tier = memoryAppendLog<{ type: string }>({ name: "events" });
- * await tier.appendEntries([{ type: "init" }]);
- * ```
- *
- * @category extra
- */
-declare function memoryAppendLog<T>(opts?: Omit<AppendLogStorageOptions<T>, "name"> & {
-    name?: string;
-}): AppendLogStorageTier<T>;
-/**
- * Creates an in-memory key-value tier backed by a fresh `memoryBackend`.
- *
- * Convenience wrapper for `kvStorage(memoryBackend(), opts)`. All writes are
- * synchronous and in-process — useful for tests and ephemeral record caches.
- *
- * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
- * @returns `KvStorageTier<T>` backed by an in-memory store.
- *
- * @example
- * ```ts
- * import { memoryKv } from "@graphrefly/graphrefly/extra";
- *
- * const kv = memoryKv<{ value: number }>();
- * await kv.save("key1", { value: 42 });
- * const loaded = await kv.load("key1");
- * ```
- *
- * @category extra
- */
-declare function memoryKv<T>(opts?: Omit<KvStorageOptions<T>, "name"> & {
-    name?: string;
-}): KvStorageTier<T>;
-/**
- * Creates a kv tier backed by a caller-owned plain object (`Record<string, Uint8Array>`).
- *
- * Useful for embedding storage inside a parent state shape or for tests that
- * need direct access to the raw bytes. The dict stores raw encoded bytes as
- * `Uint8Array`. Use `opts.name` to control the tier's diagnostic name
- * (defaults to `"dict-kv"`).
- *
- * @param storage - Caller-owned `Record<string, Uint8Array>` to use as the backing store.
- * @param opts - Optional kv storage options (name, codec, filter, debounce, compactEvery).
- * @returns `KvStorageTier<T>` backed by the provided dict object.
- *
- * @example
- * ```ts
- * import { dictKv } from "@graphrefly/graphrefly/extra";
- *
- * const store: Record<string, Uint8Array> = {};
- * const tier = dictKv<{ score: number }>(store);
- * await tier.save("player1", { score: 100 });
- * ```
- *
- * @category extra
- */
-declare function dictKv<T>(storage: Record<string, Uint8Array>, opts?: Omit<KvStorageOptions<T>, "name"> & {
-    name?: string;
-}): KvStorageTier<T>;
-/**
- * Creates a snapshot tier backed by a caller-owned plain object (`Record<string, Uint8Array>`).
- *
- * Useful for embedding checkpoints inside a parent state shape or for tests
- * that need direct access to the raw bytes. The dict stores raw JSON bytes as
- * `Uint8Array`. Use `opts.name` to control the storage key (defaults to
- * `"snapshot"`).
- *
- * @param storage - Caller-owned `Record<string, Uint8Array>` to use as the backing store.
- * @param opts - Optional snapshot storage options (name, codec, filter, keyOf, debounce, compactEvery).
- * @returns `SnapshotStorageTier<T>` backed by the provided dict object.
- *
- * @example
- * ```ts
- * import { dictSnapshot } from "@graphrefly/graphrefly/extra";
- *
- * const store: Record<string, Uint8Array> = {};
- * graph.attachSnapshotStorage([dictSnapshot(store, { name: graph.name })]);
- * ```
- *
- * @category extra
- */
-declare function dictSnapshot<T>(storage: Record<string, Uint8Array>, opts?: Omit<SnapshotStorageOptions<T>, "name"> & {
-    name?: string;
-}): SnapshotStorageTier<T>;
-
-export { type AppendCursor, type AppendLoadResult, type AppendLogStorageOptions, type AppendLogStorageTier, type BaseStorageTier, type Codec, type KvStorageOptions, type KvStorageTier, type SnapshotStorageOptions, type SnapshotStorageTier, type StorageBackend, appendLogStorage, dictKv, dictSnapshot, jsonCodec, jsonCodecFor, kvStorage, memoryAppendLog, memoryBackend, memoryKv, memorySnapshot, snapshotStorage };
+export * from '@graphrefly/pure-ts/extra/storage-tiers';