arrowbase 0.1.1

package/dist/idb.d.ts

@@ -0,0 +1,146 @@
+import { C as Collection, a as CompiledSchema } from './collection-DGlKgOGi.js';
+
+/**
+ * IndexedDB persistence adapter for ArrowBase.
+ *
+ * Optional subpath (`arrowbase/idb`). Stores a single snapshot per
+ * collection under a caller-supplied key in one object store. Writes
+ * are debounced so bursts of mutations cause at most one IDB round-trip
+ * per window.
+ *
+ * ### Usage
+ *
+ * ```ts
+ * import { Collection, defineSchema } from 'arrowbase';
+ * import { IdbPersistence } from 'arrowbase/idb';
+ *
+ * const schema = defineSchema({ ... });
+ *
+ * // 1. Try to restore the last snapshot. Falls back to a fresh
+ * //    collection when the key is empty.
+ * const persist = await IdbPersistence.open(schema, {
+ *   dbName: 'my-app',
+ *   key: 'features',
+ *   capacity: 10_000,
+ * });
+ * const collection = persist.collection;
+ *
+ * // 2. Subscribe to mutations and auto-snapshot with a debounce.
+ * persist.start({ debounceMs: 500 });
+ *
+ * // 3. Force an immediate flush before unload, etc.
+ * window.addEventListener('beforeunload', () => { persist.flush(); });
+ *
+ * // 4. Tear down on shutdown.
+ * await persist.close();
+ * ```
+ *
+ * ### Formats
+ *
+ * - `'arbs'` (default) — ArrowBase's native binary snapshot. Fast,
+ *   preserves ranged offsets, round-trips soft-deletes exactly.
+ * - `'arrow-ipc'` — standard Apache Arrow IPC file. Portable across
+ *   the Arrow ecosystem at the cost of a rebuild on restore. Requires
+ *   the optional `apache-arrow` peer dependency.
+ *
+ * ### Storage layout
+ *
+ * One IDB object store. Keys are caller-supplied strings (typically the
+ * collection name). Values are `{ format, bytes, version, savedAt }`
+ * records. Storing metadata alongside the bytes keeps the schema
+ * self-describing and lets us detect format changes cheaply.
+ */
+
+type IdbPersistenceFormat = 'arbs' | 'arrow-ipc';
+interface IdbPersistenceOpenOptions {
+    /** Name of the IDB database. Defaults to `"arrowbase"`. */
+    dbName?: string;
+    /** Name of the object store inside the database. Defaults to `"snapshots"`. */
+    storeName?: string;
+    /** Key under which this collection's snapshot is stored. Required. */
+    key: string;
+    /**
+     * Snapshot format. Defaults to `'arbs'`. `'arrow-ipc'` requires
+     * `apache-arrow` to be installed.
+     */
+    format?: IdbPersistenceFormat;
+    /** Passed through to `Collection.create` when no snapshot exists. */
+    capacity?: number;
+    /** Optional callback for async errors during save (debounced writes). */
+    onError?: (err: unknown) => void;
+    /**
+     * Inject a custom `IDBFactory` (e.g., `fake-indexeddb` for tests).
+     * Defaults to `globalThis.indexedDB`.
+     */
+    indexedDB?: IDBFactory;
+}
+interface IdbPersistenceStartOptions {
+    /**
+     * Coalesce change events inside this many ms, then write once.
+     * Defaults to 250ms.
+     */
+    debounceMs?: number;
+    /**
+     * If true, write an initial snapshot immediately on start() even
+     * when no change has occurred yet. Defaults to false — we assume
+     * the caller already restored the state or intentionally started
+     * with an empty collection.
+     */
+    saveImmediately?: boolean;
+}
+declare class IdbPersistence {
+    /** The live collection, either freshly created or restored. */
+    readonly collection: Collection;
+    private readonly db;
+    private readonly storeName;
+    private readonly key;
+    private format;
+    private readonly onError?;
+    /**
+     * Open the adapter and restore any existing snapshot.
+     *
+     * If the key is empty, a fresh collection is created using the
+     * supplied schema + capacity (default 1024). The caller can then
+     * call `start()` to begin auto-persisting future mutations.
+     */
+    static open(schema: CompiledSchema, options: IdbPersistenceOpenOptions): Promise<IdbPersistence>;
+    private saveTimer;
+    private unsubscribe;
+    private closed;
+    private dirtyDuringSave;
+    private savingPromise;
+    private debounceMs;
+    private constructor();
+    /**
+     * Subscribe to collection mutations and begin debounced auto-saving.
+     * Safe to call multiple times — only the first has effect.
+     */
+    start(options?: IdbPersistenceStartOptions): void;
+    /**
+     * Stop subscribing. Any pending debounced write is cancelled; call
+     * `flush()` first if you need to persist the current state.
+     */
+    stop(): void;
+    /**
+     * Write the current collection state immediately, bypassing debounce.
+     * Resolves after the IDB transaction completes.
+     */
+    flush(): Promise<void>;
+    /** Stop + close the underlying IDB connection. Idempotent. */
+    close(): Promise<void>;
+    /** Switch between snapshot formats. Takes effect on the next save. */
+    setFormat(format: IdbPersistenceFormat): void;
+    private scheduleSave;
+    private doSave;
+}
+/**
+ * Remove a stored snapshot. Mostly useful for tests and for "wipe
+ * local cache" UX.
+ */
+declare function deleteStoredSnapshot(key: string, options?: {
+    dbName?: string;
+    storeName?: string;
+    indexedDB?: IDBFactory;
+}): Promise<void>;
+
+export { IdbPersistence, type IdbPersistenceFormat, type IdbPersistenceOpenOptions, type IdbPersistenceStartOptions, deleteStoredSnapshot };