@framers/sql-storage-adapter 0.7.2 → 0.7.3

package/dist/cjs/adapters/indexedDbAdapter.d.ts

@@ -0,0 +1,490 @@
+/**
+ * @fileoverview IndexedDB Storage Adapter
+ * @description Browser-native SQL storage using sql.js (WASM) for SQL execution and IndexedDB for persistence.
+ *
+ * **Architecture:**
+ * - **SQL Execution**: Uses sql.js (SQLite compiled to WebAssembly) for full SQL support
+ * - **Persistence**: Stores the SQLite database file (as binary blob) in IndexedDB
+ * - **Workflow**: Load DB from IndexedDB → Execute SQL in memory (sql.js) → Save back to IndexedDB
+ *
+ * **Why this approach?**
+ * - IndexedDB is NOT SQL - it's a NoSQL key-value store
+ * - sql.js provides full SQLite compatibility (transactions, joins, etc.)
+ * - IndexedDB provides durable browser-native persistence
+ * - Together: Full SQL capabilities + browser persistence = best of both worlds
+ *
+ * **Use cases:**
+ * - Fully client-side applications (no backend needed)
+ * - Progressive Web Apps (PWAs)
+ * - Offline-capable web apps
+ * - Privacy-first applications (data never leaves browser)
+ *
+ * **Performance:**
+ * - Fast reads (in-memory SQL via sql.js)
+ * - Moderate writes (IndexedDB persistence adds ~10-50ms)
+ * - Auto-save batching reduces IDB overhead
+ *
+ * @example
+ * ```typescript
+ * import { IndexedDbAdapter } from '@framers/sql-storage-adapter';
+ *
+ * const adapter = new IndexedDbAdapter({
+ *   dbName: 'my-app-db',
+ *   durability: 'commit', // each write is in IndexedDB before it resolves
+ *   crossTab: true,       // two tabs of the site keep each other's writes
+ * });
+ *
+ * await adapter.open();
+ * await adapter.run('CREATE TABLE sessions (id TEXT PRIMARY KEY, data TEXT)');
+ * await adapter.run('INSERT INTO sessions VALUES (?, ?)', ['session-1', '{"events": []}']);
+ *
+ * const session = await adapter.get('SELECT * FROM sessions WHERE id = ?', ['session-1']);
+ * console.log(session);
+ * ```
+ */
+import type { StorageAdapter, StorageCapability, StorageOpenOptions, StorageParameters, StorageRunResult } from '../core/contracts/index.js';
+/**
+ * The part of the Web Locks API (`navigator.locks`) the adapter uses: an
+ * exclusive lock per name, granted to one holder at a time, in the order
+ * asked, and held until the callback's promise settles.
+ */
+export interface IndexedDbLockManager {
+    request<T>(name: string, options: {
+        mode: 'exclusive';
+    }, callback: () => Promise<T>): Promise<T>;
+}
+/** How tabs coordinate their saves. */
+export interface IndexedDbCrossTabOptions {
+    /**
+     * The lock manager: the browser's `navigator.locks` when left out. `null`
+     * coordinates by the version stamp alone, as the adapter does where the
+     * browser has no Web Locks.
+     */
+    locks?: IndexedDbLockManager | null;
+}
+/** When a write is stored in IndexedDB. */
+export type IndexedDbDurability = 'interval' | 'commit';
+/**
+ * Configuration for IndexedDB adapter.
+ */
+export interface IndexedDbAdapterOptions {
+    /** IndexedDB database name (default: 'app-db') */
+    dbName?: string;
+    /** IndexedDB object store name (default: 'sqliteDb') */
+    storeName?: string;
+    /** Auto-save to IndexedDB on a timer (default: true) */
+    autoSave?: boolean;
+    /** Save interval in milliseconds for batched writes (default: 5000) */
+    saveIntervalMs?: number;
+    /** sql.js configuration (e.g., locateFile for wasm) */
+    sqlJsConfig?: any;
+    /**
+     * When a write is stored in IndexedDB.
+     *
+     * - `'interval'`, the default: the auto-save tick stores the writes made
+     *   since the last save, every `saveIntervalMs`; `flush()` and `close()`
+     *   store them at once. A write can be lost when the page goes before the
+     *   next tick.
+     * - `'commit'`: `run()`, `exec()`, a write through `all()` or `get()`
+     *   (`INSERT ... RETURNING`) and `transaction()` resolve once their write is
+     *   in IndexedDB, and reject when IndexedDB refuses it (the write stays in
+     *   the database and the next save stores it). Each save writes the whole
+     *   database image, so batch many writes in one `transaction()`. While a
+     *   transaction a caller opened with `BEGIN` is open, nothing can be saved:
+     *   its statements resolve at once, and its rows are stored when its
+     *   `COMMIT` resolves.
+     */
+    durability?: IndexedDbDurability;
+    /**
+     * Keeps the writes of two tabs of the site that open the same database.
+     * Each tab holds the whole database in memory and writes it back whole, so
+     * without this the tab that saves last overwrites the other's writes.
+     *
+     * With `crossTab`, every statement and transaction runs under a Web Lock on
+     * the database, on the newest stored image (a tab reloads it when another
+     * has saved), and is stored before the lock is let go: `durability` is
+     * `'commit'` whatever it says. Where the browser has no Web Locks (Safari
+     * before 15.4, an insecure origin, Lockdown Mode), the version stamp stored
+     * beside the image keeps both tabs' writes alone: a statement that finds
+     * another tab saved first runs again on the newer image, and a
+     * `transaction()` is refused with `IndexedDbConflictError`, storing
+     * nothing, for its caller to run again. The adapter says once when it runs
+     * without Web Locks.
+     *
+     * A transaction begun with `BEGIN` through `run()` or `exec()` cannot be
+     * held across tabs: it is rolled back and refused. Use `transaction()`.
+     */
+    crossTab?: boolean | IndexedDbCrossTabOptions;
+    /**
+     * A database of its own: the segment is appended to `dbName`
+     * (`app-db` becomes `app-db-agentos`). Lower-case letters, digits and
+     * underscores.
+     */
+    segment?: string;
+}
+/**
+ * A `transaction()` another tab saved over: refused, with nothing of it
+ * stored. The adapter has loaded the other tab's image, so running the
+ * transaction again keeps both tabs' writes.
+ */
+export declare class IndexedDbConflictError extends Error {
+    constructor(message: string);
+}
+/**
+ * Storage adapter using IndexedDB + sql.js for client-side SQL persistence.
+ *
+ * **The Key Difference: Automatic Persistence**
+ *
+ * **sql.js adapter alone:**
+ * - In-memory SQLite database (lost on page refresh)
+ * - You must manually call `db.export()` and save it yourself
+ * - No automatic persistence in browsers
+ * - Good for: Edge functions, temporary calculations, prototyping
+ *
+ * **IndexedDB adapter (this):**
+ * - Same sql.js SQL engine, but automatically saves to IndexedDB
+ * - Data survives page refreshes automatically
+ * - Auto-save batching reduces overhead
+ * - Good for: Production PWAs, offline-first apps, persistent client-side storage
+ *
+ * **How It Works:**
+ * 1. IndexedDB stores the SQLite database file (binary blob) - this is just storage
+ * 2. sql.js (WASM) loads the database into memory and executes SQL - this provides SQL capabilities
+ * 3. After writes, the updated database is saved back to IndexedDB: on a timer
+ *    (the default), before each write resolves (`durability: 'commit'`), or
+ *    under a cross-tab lock (`crossTab`)
+ *
+ * **Capabilities:**
+ * - ✅ Transactions (via sql.js)
+ * - ✅ Persistence (via IndexedDB - automatic!)
+ * - ✅ Full SQL support (via sql.js)
+ * - ✅ Export/import
+ * - ✅ Several tabs on one database, with `crossTab`
+ * - ❌ Server-side (browser only)
+ *
+ * @example Client-side application
+ * ```typescript
+ * const adapter = new IndexedDbAdapter({ dbName: 'my-app-db' });
+ * await adapter.open();
+ * await adapter.run('CREATE TABLE sessions (id TEXT PRIMARY KEY, data TEXT)');
+ * ```
+ */
+export declare class IndexedDbAdapter implements StorageAdapter {
+    readonly kind = "indexeddb";
+    readonly capabilities: ReadonlySet<StorageCapability>;
+    private SQL;
+    private db;
+    /** Foreign-key enforcement as open() was asked for it (undefined: the engine default); sql.js forgets the PRAGMA when export() reopens the connection. */
+    private foreignKeys;
+    private idb;
+    private saveTimer;
+    /** Bumped by every statement that can change the database. */
+    private writeGeneration;
+    /** The generation the last completed save exported; the writes after it are unsaved. */
+    private savedGeneration;
+    /** The save in progress, if any. */
+    private saving;
+    /** The generation the save in progress exported. */
+    private savingGeneration;
+    /** Whether a failed auto-save has been reported since the last one that succeeded. */
+    private saveFailureReported;
+    /** The open() in progress, which a second call waits for. */
+    private opening;
+    /** Set while close() runs: no statement or transaction starts. */
+    private closing;
+    /** The close() in progress, which a second call waits for. */
+    private closeRun;
+    private longWaitReported;
+    private lockWaitReported;
+    /** The stamp of the image the database in memory was loaded from or last saved as. */
+    private loadedStamp;
+    /** How many stamps this adapter has made, which keeps two of its stamps apart. */
+    private stampCount;
+    /** The connection settings a fresh connection has, which a save need not set again. */
+    private pragmaDefaults;
+    /**
+     * With `crossTab`, the lock manager, or null for the version stamp alone;
+     * undefined without `crossTab`.
+     */
+    private locks;
+    /** Without Web Locks, this adapter's coordinated operations run one at a time. */
+    private readonly runCoordinatedInTurn;
+    /**
+     * The connection is shared, so transaction() runs one callback at a time.
+     */
+    private readonly runSerializedTransaction;
+    /**
+     * Holds statements from outside an open transaction until it ends, so they
+     * neither join it (and vanish in its rollback) nor read what it has not
+     * committed. Browsers have no async context to tell the callback's own
+     * statements apart, so the callback's handle is the only way into an open
+     * transaction: a statement through the adapter itself waits.
+     */
+    private readonly gate;
+    private readonly longWait;
+    private readonly dbName;
+    private readonly storeName;
+    private readonly autoSave;
+    private readonly saveIntervalMs;
+    private readonly durability;
+    private readonly crossTab;
+    private readonly sqlJsConfig;
+    /** @throws {Error} When `options.segment` is not a name a segment can take. */
+    constructor(options?: IndexedDbAdapterOptions);
+    /** The name of the Web Lock that coordinates the tabs on this database. */
+    private get lockName();
+    /**
+     * Opens IndexedDB and initializes sql.js database.
+     * Loads existing database from IndexedDB if present.
+     *
+     * Uses a global sql.js singleton to prevent race conditions when
+     * multiple adapters (e.g., fabric_codex_db and quarry-codex-local)
+     * are initialized simultaneously. Two calls at once open once.
+     */
+    open(options?: StorageOpenOptions): Promise<void>;
+    private openNow;
+    /** The lock manager crossTab uses, or null for the version stamp alone. */
+    private resolveLocks;
+    /**
+     * Executes a SQL statement that doesn't return rows (INSERT, UPDATE, DELETE, CREATE, etc.).
+     * @param statement SQL statement with ? or :name placeholders
+     * @param parameters Positional array or named object
+     * @returns Result with changes count and last insert row ID
+     */
+    run(statement: string, parameters?: StorageParameters): Promise<StorageRunResult>;
+    private runNow;
+    /**
+     * Executes a SQL query and returns the first row.
+     * @param statement SELECT statement
+     * @param parameters Query parameters
+     * @returns First row as object or null if no results
+     */
+    get<T>(statement: string, parameters?: StorageParameters): Promise<T | null>;
+    /**
+     * Executes a SQL query and returns all matching rows. A statement that
+     * writes (`INSERT ... RETURNING`) is saved like a `run()`.
+     * @param statement SELECT statement
+     * @param parameters Query parameters
+     * @returns Array of result rows as objects
+     */
+    all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    private allNow;
+    /** The rows changed on this connection since it opened. */
+    private totalChanges;
+    /**
+     * Executes a script containing multiple SQL statements.
+     */
+    exec(script: string): Promise<void>;
+    private execNow;
+    /**
+     * With `durability: 'commit'`, resolves with `result` once the write that
+     * produced it is stored; otherwise with `result` at once.
+     */
+    private stored;
+    /**
+     * Executes a callback within a database transaction.
+     *
+     * Callbacks run one at a time, since every transaction shares the one
+     * connection. The callback's statements go through the handle it receives;
+     * a statement issued through the adapter itself while the callback runs
+     * waits until the transaction ends, so a callback must not await one. The
+     * auto-save tick does not save while a transaction is open. With
+     * `durability: 'commit'` the transaction resolves once it is stored.
+     */
+    transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
+    /** Runs one transaction: BEGIN, the callback through its handle, COMMIT or ROLLBACK. */
+    private transactionNow;
+    /**
+     * The statements of one transaction's handle: they carry the transaction's
+     * token, so the gate admits them while the transaction is open.
+     */
+    private handleStatements;
+    /** Rolls back the open transaction; one that already ended (a failed statement, close()) is left alone. */
+    private rollbackQuietly;
+    /**
+     * Begins a transaction the caller ends with commit() or rollback(). It is not
+     * the callback form: other callers' statements are not held out of it. With
+     * `crossTab` it is refused: use transaction().
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commits the current transaction.
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the current transaction.
+     */
+    rollback(): Promise<void>;
+    /**
+     * Stores every write made so far in IndexedDB. A `transaction()` that is
+     * open is waited for and stored with the rest; a transaction a caller began
+     * with `BEGIN` cannot be stored without ending it, so flush() rejects while
+     * one is open. Resolves at once when nothing is waiting to be saved.
+     */
+    flush(): Promise<void>;
+    /**
+     * Closes the database and saves its committed state to IndexedDB.
+     *
+     * A transaction still open is rolled back, as closing a SQLite connection
+     * does, before the save; the save then holds committed writes only. A call
+     * made while a close is running waits for that close.
+     */
+    close(): Promise<void>;
+    private closeNow;
+    /**
+     * Exports the database as a Uint8Array (SQLite file format).
+     * Can be downloaded or stored externally. With `crossTab` it is this tab's
+     * image, which another tab's save can have overtaken.
+     *
+     * Throws while a transaction is open: sql.js's export closes and reopens the
+     * connection, which would end the transaction.
+     * @returns SQLite database file as binary
+     */
+    exportDatabase(): Uint8Array;
+    /**
+     * Applies the connection settings open() was asked for. sql.js loses them
+     * whenever export() reopens the connection; a save, an export, an import
+     * and a reload set them again with the other settings a caller changed
+     * (exportImage, replaceDatabase).
+     */
+    private applyConnectionSettings;
+    /**
+     * Imports a database from a Uint8Array (SQLite file).
+     * Replaces the current database once any open transaction() has ended, and
+     * saves it to IndexedDB before it resolves; with `crossTab`, in place of
+     * what every tab stored. Bytes that are not a SQLite database are refused,
+     * and the adapter keeps its database.
+     * @param data SQLite database file
+     */
+    importDatabase(data: Uint8Array): Promise<void>;
+    /** Replaces the database with an image, once sql.js has read it as a SQLite database. */
+    private swapIn;
+    /** Puts `next` in place of the database, with the connection settings the current one has. */
+    private replaceDatabase;
+    /**
+     * Runs `work` with this tab holding the database: under the Web Lock, or,
+     * without Web Locks, after this adapter's earlier coordinated work.
+     */
+    private withCoordination;
+    /**
+     * One statement across tabs: on the newest stored image, and stored before
+     * it resolves. Without Web Locks another tab can save between the load and
+     * the save; the statement then runs again on that tab's image.
+     */
+    private coordinatedStatement;
+    /**
+     * One transaction across tabs: on the newest stored image, and stored before
+     * it resolves. Without Web Locks another tab can save while the callback
+     * runs; the transaction is then refused, nothing of it is stored, and the
+     * other tab's image is loaded for the caller to run it again.
+     */
+    private coordinatedTransaction;
+    /** Loads the stored image when another tab (or adapter) has saved since this one loaded or saved. */
+    private syncFromStore;
+    /** Reads the stored stamp, and the image with it when the stamp is not `known`; null when it is. */
+    private readIfChanged;
+    /**
+     * Stores the image when the stored stamp is still `expected`, in one
+     * IndexedDB transaction, so no other tab's save lands between the check and
+     * the write. `undefined` stores it whatever the stamp is. Resolves with
+     * whether it stored the image.
+     */
+    private saveIfStampIs;
+    /** A stamp no other save of this or another tab writes. */
+    private nextStamp;
+    /**
+     * Exports the database for a save, keeping the connection settings a
+     * caller made: sql.js's export() closes the connection and opens it again.
+     */
+    private exportImage;
+    /** The connection settings that differ from a fresh connection's. */
+    private changedPragmas;
+    /** Sets connection settings on the database, after a save or a reload. */
+    private applyPragmas;
+    /**
+     * Opens or creates the IndexedDB database.
+     */
+    private openIndexedDb;
+    /**
+     * Opens IndexedDB with retry logic and exponential backoff.
+     * Handles race conditions when multiple adapters initialize simultaneously.
+     *
+     * The "NotFoundError" for object stores typically occurs when:
+     * 1. Two adapters try to open/upgrade simultaneously
+     * 2. One adapter opens the DB while another is still upgrading
+     * 3. Schema version mismatch during concurrent initialization
+     *
+     * @param maxRetries Maximum number of retry attempts (default: 3)
+     * @param baseDelayMs Base delay in milliseconds (default: 100)
+     */
+    private openIndexedDbWithRetry;
+    /**
+     * Loads the SQLite database and its stamp from IndexedDB, in one
+     * transaction, so the two belong together.
+     */
+    private loadFromIndexedDb;
+    /**
+     * Writes the current image to IndexedDB, with a new stamp. Never called
+     * while a transaction is open (see saveIfIdle): sql.js's export() closes and
+     * reopens the connection, which ends an open transaction.
+     *
+     * Settles when the IndexedDB transaction completes, not when its put request
+     * succeeds: the transaction can still abort after that (a quota error at
+     * commit), and the image is then not stored. On abort the writes stay
+     * unsaved, so the next save writes them. A write made after the export stays
+     * unsaved too.
+     */
+    private saveToIndexedDb;
+    /** Whether writes were made since the image the last completed save exported. */
+    private hasUnsavedWrites;
+    /**
+     * Whether a transaction is open on the connection: one transaction() is
+     * running, or one the caller began with BEGIN or SAVEPOINT. sql.js does not
+     * export sqlite3_get_autocommit, so the adapter asks SQLite: BEGIN fails
+     * inside a transaction, and outside one it is rolled back at once. A probe
+     * that fails for any reason counts as open, so the adapter does not export.
+     */
+    private inTransaction;
+    /**
+     * Starts a save of the unsaved writes, unless a save is running or a
+     * transaction is open; the auto-save tick tries again later.
+     */
+    private saveIfIdle;
+    /**
+     * Resolves once the writes up to `generation` are stored. A save in
+     * progress that holds them is waited for; an open transaction() is waited
+     * for, since its own save holds them; while a transaction a caller began
+     * with BEGIN is open, nothing can be stored, and its COMMIT stores them.
+     * Rejects when the save that held them failed.
+     */
+    private saveThrough;
+    /**
+     * Starts a save at once and keeps it as the save in progress. The caller has
+     * made sure no transaction is open: the export would end it.
+     */
+    private startSave;
+    /** Waits for a save in progress to settle, whether it succeeded or not. */
+    private settleSave;
+    private reportLongWait;
+    private reportLockWait;
+    /**
+     * Wraps a transaction operation with retry logic.
+     * Handles "NotFoundError" by reopening IndexedDB connection.
+     */
+    private withTransactionRetry;
+    /**
+     * Starts auto-save interval.
+     */
+    private startAutoSave;
+    /** One auto-save tick: a failed save is reported once and tried again on the next tick. */
+    private autoSaveTick;
+    /**
+     * Ensures the database is open.
+     */
+    private ensureOpen;
+    /**
+     * Normalizes last insert row ID to string or number.
+     */
+    private normaliseRowId;
+}
+//# sourceMappingURL=indexedDbAdapter.d.ts.map