@framers/sql-storage-adapter 0.6.16 → 0.7.0

package/dist/adapters/indexedDbAdapter.js

@@ -26,12 +26,12 @@
  *
  * @example
  * ```typescript
- * import { IndexedDbAdapter } from '@framers/sql-storage-adapter/adapters/indexedDbAdapter';
+ * import { IndexedDbAdapter } from '@framers/sql-storage-adapter';
  *
  * const adapter = new IndexedDbAdapter({
  *   dbName: 'my-app-db',
- *   autoSave: true,
- *   saveIntervalMs: 5000,
+ *   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();
@@ -47,8 +47,41 @@ import { expandNamedParameters, normaliseParameters } from '../shared/parameterU
 import { toSqliteStatement } from '../shared/sqlPlaceholders.js';
 import { createSerializedTransactionRunner, createSharedConnectionTransactionAdapter, } from '../shared/serializedTransaction.js';
 import { createConnectionGate, whenAdmitted } from '../shared/connectionGate.js';
-/** How long a statement waits for an open transaction before the adapter warns. */
+import { segmentName } from '../shared/segment.js';
+/** How long a statement waits for an open transaction or the cross-tab lock before the adapter warns. */
 const LONG_WAIT_MS = 10000;
+/** The object store's key of the database image. */
+const IMAGE_KEY = 'db';
+/**
+ * The object store's key of the image's version stamp: every save writes a
+ * new one beside the image, in the same IndexedDB transaction, so a tab can
+ * tell that another has saved since it loaded.
+ */
+const STAMP_KEY = 'db:stamp';
+/** How often a statement runs again after another tab saved first, without Web Locks. */
+const MAX_CONFLICT_RETRIES = 50;
+/**
+ * Connection settings sql.js's export drops: `export()` closes the
+ * connection and opens it again, which resets every per-connection PRAGMA. A
+ * save reads these before it exports and sets again the ones a caller changed.
+ */
+const CONNECTION_PRAGMAS = [
+    'foreign_keys',
+    'recursive_triggers',
+    'automatic_index',
+    'cache_size',
+    'cache_spill',
+    'cell_size_check',
+    'ignore_check_constraints',
+    'legacy_alter_table',
+    'query_only',
+    'reverse_unordered_selects',
+    'secure_delete',
+    'synchronous',
+    'temp_store',
+    'trusted_schema',
+    'busy_timeout',
+];
 // ============================================================================
 // GLOBAL SQL.JS SINGLETON
 // ============================================================================
@@ -74,7 +107,23 @@ async function getGlobalSQL(config) {
     });
     return globalSQLPromise;
 }
+/**
+ * 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 class IndexedDbConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IndexedDbConflictError';
+    }
+}
 const DB_VERSION = 1;
+/** The first keyword of a statement, past its leading comments and whitespace. */
+const firstKeyword = (statement) => {
+    const rest = statement.replace(/^(?:\s+|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/, '');
+    return (/^[A-Za-z]+/.exec(rest)?.[0] ?? '').toUpperCase();
+};
 /**
  * Storage adapter using IndexedDB + sql.js for client-side SQL persistence.
  *
@@ -92,51 +141,21 @@ const DB_VERSION = 1;
  * - Auto-save batching reduces overhead
  * - Good for: Production PWAs, offline-first apps, persistent client-side storage
  *
- * **Is This Necessary?**
- *
- * **✅ YES** if you need:
- * - Data to survive page refreshes (production apps)
- * - Offline-first functionality (PWAs)
- * - Privacy-first apps (data never leaves browser)
- * - Zero manual save logic (just works)
- *
- * **❌ NO** if you:
- * - Only need temporary/in-memory data (edge functions)
- * - Are prototyping and don't care about persistence
- * - Want to manually control when data is saved
- * - Don't need data to survive refreshes
- *
- * **Alternative:** You could use sql.js directly and manually save to IndexedDB yourself, but you'd lose:
- * - Automatic batched saves (performance optimization)
- * - Reliable persistence (easy to forget manual saves = data loss)
- * - Consistent API across platforms
- * - Production-ready defaults
- *
- * **Bottom line:** This adapter is **necessary for production web apps** that need persistence. For prototypes or edge functions, sql.js alone is fine.
- *
  * **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 automatically saved back to IndexedDB
- *
- * **Why IndexedDB + sql.js?**
- * - IndexedDB alone: NoSQL key-value store, no SQL support
- * - sql.js alone: In-memory SQL, but **no automatic persistence** (you must manually save)
- * - Combined: Full SQL + **automatic browser-native persistence** = production-ready solution
+ * 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
- * - ❌ Concurrent writes (single-threaded)
+ * - ✅ Several tabs on one database, with `crossTab`
  * - ❌ Server-side (browser only)
  *
- * **Performance:**
- * - Fast reads (in-memory SQL)
- * - Moderate writes (IndexedDB persistence)
- * - Auto-save batching reduces IDB overhead
- *
  * @example Client-side application
  * ```typescript
  * const adapter = new IndexedDbAdapter({ dbName: 'my-app-db' });
@@ -145,6 +164,7 @@ const DB_VERSION = 1;
  * ```
  */
 export class IndexedDbAdapter {
+    /** @throws {Error} When `options.segment` is not a name a segment can take. */
     constructor(options = {}) {
         this.kind = 'indexeddb';
         this.capabilities = new Set(['transactions', 'persistence', 'json', 'prepared']);
@@ -158,13 +178,31 @@ export class IndexedDbAdapter {
         this.savedGeneration = 0;
         /** The save in progress, if any. */
         this.saving = null;
+        /** The generation the save in progress exported. */
+        this.savingGeneration = 0;
         /** Whether a failed auto-save has been reported since the last one that succeeded. */
         this.saveFailureReported = false;
+        /** The open() in progress, which a second call waits for. */
+        this.opening = null;
         /** Set while close() runs: no statement or transaction starts. */
         this.closing = false;
         /** The close() in progress, which a second call waits for. */
         this.closeRun = null;
         this.longWaitReported = false;
+        this.lockWaitReported = false;
+        /** The stamp of the image the database in memory was loaded from or last saved as. */
+        this.loadedStamp = null;
+        /** How many stamps this adapter has made, which keeps two of its stamps apart. */
+        this.stampCount = 0;
+        /** The connection settings a fresh connection has, which a save need not set again. */
+        this.pragmaDefaults = new Map();
+        /**
+         * With `crossTab`, the lock manager, or null for the version stamp alone;
+         * undefined without `crossTab`.
+         */
+        this.locks = undefined;
+        /** Without Web Locks, this adapter's coordinated operations run one at a time. */
+        this.runCoordinatedInTurn = createSerializedTransactionRunner();
         /**
          * The connection is shared, so transaction() runs one callback at a time.
          */
@@ -181,11 +219,18 @@ export class IndexedDbAdapter {
             afterMs: LONG_WAIT_MS,
             onLongWait: () => this.reportLongWait(),
         };
-        this.dbName = options.dbName || 'app-db';
+        this.dbName = segmentName(options.dbName || 'app-db', options.segment);
         this.storeName = options.storeName || 'sqliteDb';
         this.autoSave = options.autoSave ?? true;
         this.saveIntervalMs = options.saveIntervalMs || 5000;
         this.sqlJsConfig = options.sqlJsConfig || {};
+        this.crossTab =
+            options.crossTab === true ? {} : typeof options.crossTab === 'object' && options.crossTab !== null ? options.crossTab : null;
+        this.durability = this.crossTab ? 'commit' : options.durability ?? 'interval';
+    }
+    /** The name of the Web Lock that coordinates the tabs on this database. */
+    get lockName() {
+        return `@framers/sql-storage-adapter:indexeddb:${this.dbName}:${this.storeName}`;
     }
     /**
      * Opens IndexedDB and initializes sql.js database.
@@ -193,31 +238,57 @@ export class IndexedDbAdapter {
      *
      * 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.
+     * are initialized simultaneously. Two calls at once open once.
      */
-    async open(options) {
+    open(options) {
         if (this.db) {
-            return; // Already open
+            return Promise.resolve(); // Already open
+        }
+        if (!this.opening) {
+            this.foreignKeys = options?.foreignKeys;
+            this.opening = this.openNow().finally(() => {
+                this.opening = null;
+            });
         }
-        this.foreignKeys = options?.foreignKeys;
+        return this.opening;
+    }
+    async openNow() {
         // Initialize sql.js using global singleton (prevents race conditions)
         this.SQL = await getGlobalSQL(this.sqlJsConfig);
         // Open IndexedDB with retry logic for race conditions
         this.idb = await this.openIndexedDbWithRetry();
         // Load existing database from IndexedDB or create new
-        const existingData = await this.loadFromIndexedDb();
-        if (existingData) {
-            this.db = new this.SQL.Database(existingData);
-        }
-        else {
-            this.db = new this.SQL.Database();
-        }
+        const stored = await this.loadFromIndexedDb();
+        const db = stored.image ? new this.SQL.Database(stored.image) : new this.SQL.Database();
+        // What a fresh connection has, and export() returns to. Read before the
+        // settings open() was asked for, so a save carries those like any other a
+        // caller made.
+        this.pragmaDefaults = readPragmas(db);
+        this.db = db;
+        this.loadedStamp = stored.stamp;
         this.applyConnectionSettings();
-        // Start auto-save interval
-        if (this.autoSave) {
+        if (this.crossTab) {
+            this.locks = this.resolveLocks(this.crossTab);
+        }
+        else if (this.autoSave) {
+            // Start auto-save interval; with crossTab every write is saved under the lock.
             this.startAutoSave();
         }
     }
+    /** The lock manager crossTab uses, or null for the version stamp alone. */
+    resolveLocks(options) {
+        if (options.locks !== undefined) {
+            return options.locks;
+        }
+        const scope = globalThis;
+        const locks = scope.navigator?.locks;
+        if (locks && typeof locks.request === 'function') {
+            return locks;
+        }
+        console.warn(`[IndexedDbAdapter] Web Locks are not available here, so "${this.dbName}" coordinates tabs by its version stamp alone: ` +
+            'a statement another tab saved over runs again, and a transaction() another tab saved over fails with IndexedDbConflictError.');
+        return null;
+    }
     /**
      * Executes a SQL statement that doesn't return rows (INSERT, UPDATE, DELETE, CREATE, etc.).
      * @param statement SQL statement with ? or :name placeholders
@@ -225,7 +296,10 @@ export class IndexedDbAdapter {
      * @returns Result with changes count and last insert row ID
      */
     async run(statement, parameters) {
-        return whenAdmitted(this.gate, () => this.runNow(statement, parameters), undefined, this.longWait);
+        if (this.crossTab) {
+            return this.coordinatedStatement(() => this.runNow(statement, parameters));
+        }
+        return whenAdmitted(this.gate, () => this.stored(this.runNow(statement, parameters)), undefined, this.longWait);
     }
     runNow(statement, parameters) {
         ({ statement, parameters } = toSqliteStatement(statement, parameters));
@@ -264,17 +338,32 @@ export class IndexedDbAdapter {
         return rows.length > 0 ? rows[0] : null;
     }
     /**
-     * Executes a SQL query and returns all matching rows.
+     * 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
      */
     async all(statement, parameters) {
-        return whenAdmitted(this.gate, () => this.allNow(statement, parameters), undefined, this.longWait);
+        if (this.crossTab) {
+            return this.coordinatedStatement(() => this.allNow(statement, parameters));
+        }
+        return whenAdmitted(this.gate, () => {
+            const before = this.writeGeneration;
+            const rows = this.allNow(statement, parameters);
+            return this.writeGeneration === before ? rows : this.stored(rows);
+        }, undefined, this.longWait);
     }
     allNow(statement, parameters) {
         ({ statement, parameters } = toSqliteStatement(statement, parameters));
         this.ensureOpen();
+        // A statement that is not a plain read can write (INSERT ... RETURNING,
+        // WITH ... DELETE): it marks the database unsaved when it changed rows,
+        // and a statement that can only write marks it whatever it changed.
+        const keyword = firstKeyword(statement);
+        const reads = keyword === 'SELECT' || keyword === 'EXPLAIN' || keyword === 'VALUES';
+        const mayWrite = keyword === 'WITH' || keyword === 'PRAGMA';
+        const changesBefore = mayWrite ? this.totalChanges() : 0;
         const stmt = this.db.prepare(statement);
         try {
             const { named, positional } = normaliseParameters(parameters);
@@ -295,17 +384,27 @@ export class IndexedDbAdapter {
                 });
                 results.push(obj);
             }
+            if (!reads && (!mayWrite || this.totalChanges() !== changesBefore)) {
+                this.writeGeneration += 1;
+            }
             return results;
         }
         finally {
             stmt.free();
         }
     }
+    /** The rows changed on this connection since it opened. */
+    totalChanges() {
+        return Number(this.db.exec('SELECT total_changes()')[0]?.values?.[0]?.[0] ?? 0);
+    }
     /**
      * Executes a script containing multiple SQL statements.
      */
     async exec(script) {
-        return whenAdmitted(this.gate, () => this.execNow(script), undefined, this.longWait);
+        if (this.crossTab) {
+            return this.coordinatedStatement(() => this.execNow(script));
+        }
+        return whenAdmitted(this.gate, () => this.stored(this.execNow(script)), undefined, this.longWait);
     }
     execNow(script) {
         this.ensureOpen();
@@ -317,6 +416,16 @@ export class IndexedDbAdapter {
             this.writeGeneration += 1;
         }
     }
+    /**
+     * With `durability: 'commit'`, resolves with `result` once the write that
+     * produced it is stored; otherwise with `result` at once.
+     */
+    stored(result) {
+        if (this.durability !== 'commit') {
+            return result;
+        }
+        return this.saveThrough(this.writeGeneration).then(() => result);
+    }
     /**
      * Executes a callback within a database transaction.
      *
@@ -324,33 +433,46 @@ export class IndexedDbAdapter {
      * 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.
+     * auto-save tick does not save while a transaction is open. With
+     * `durability: 'commit'` the transaction resolves once it is stored.
      */
     async transaction(fn) {
         this.ensureOpen();
+        if (this.crossTab) {
+            return this.coordinatedTransaction(fn);
+        }
         const queued = setTimeout(() => this.reportLongWait(), LONG_WAIT_MS);
-        return this.runSerializedTransaction(() => {
+        return this.runSerializedTransaction(async () => {
             clearTimeout(queued);
-            return this.gate.hold(async (token) => {
+            const result = await this.transactionNow(fn);
+            if (this.durability === 'commit') {
+                // The gate is open again, and the next transaction waits for this save.
+                await this.saveThrough(this.writeGeneration);
+            }
+            return result;
+        });
+    }
+    /** Runs one transaction: BEGIN, the callback through its handle, COMMIT or ROLLBACK. */
+    transactionNow(fn) {
+        return this.gate.hold(async (token) => {
+            this.ensureOpen();
+            // Outside the try: when BEGIN fails, the transaction that is open
+            // (a caller's own BEGIN) is not this one to roll back.
+            this.db.run('BEGIN TRANSACTION');
+            const transactionAdapter = createSharedConnectionTransactionAdapter(this.handleStatements(token));
+            try {
+                const result = await fn(transactionAdapter);
                 this.ensureOpen();
-                // Outside the try: when BEGIN fails, the transaction that is open
-                // (a caller's own BEGIN) is not this one to roll back.
-                this.db.run('BEGIN TRANSACTION');
-                const transactionAdapter = createSharedConnectionTransactionAdapter(this.handleStatements(token));
-                try {
-                    const result = await fn(transactionAdapter);
-                    this.ensureOpen();
-                    this.db.run('COMMIT');
-                    // The callback may have written through all() or get() (INSERT ...
-                    // RETURNING), which mark nothing unsaved; the commit does.
-                    this.writeGeneration += 1;
-                    return result;
-                }
-                catch (error) {
-                    this.rollbackQuietly();
-                    throw error;
-                }
-            });
+                this.db.run('COMMIT');
+                // The callback may have written through all() or get() (INSERT ...
+                // RETURNING); the commit marks the database unsaved in any case.
+                this.writeGeneration += 1;
+                return result;
+            }
+            catch (error) {
+                this.rollbackQuietly();
+                throw error;
+            }
         });
     }
     /**
@@ -387,7 +509,8 @@ export class IndexedDbAdapter {
     }
     /**
      * 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.
+     * the callback form: other callers' statements are not held out of it. With
+     * `crossTab` it is refused: use transaction().
      */
     async beginTransaction() {
         await this.run('BEGIN');
@@ -404,6 +527,44 @@ export class IndexedDbAdapter {
     async rollback() {
         await this.run('ROLLBACK');
     }
+    /**
+     * 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.
+     */
+    async flush() {
+        this.ensureOpen();
+        if (this.crossTab) {
+            // Every write is stored before it resolves; this stores one whose save
+            // failed, unless another tab has saved since.
+            await this.coordinatedStatement(() => undefined);
+            return;
+        }
+        const target = this.writeGeneration;
+        while (this.savedGeneration < target && this.db && this.idb) {
+            if (this.saving) {
+                const covering = this.savingGeneration >= target;
+                try {
+                    await this.saving;
+                }
+                catch (error) {
+                    if (covering)
+                        throw error;
+                }
+                continue;
+            }
+            if (this.gate.openToken() !== null) {
+                await this.gate.ended();
+                continue;
+            }
+            if (this.inTransaction()) {
+                throw new Error(`IndexedDbAdapter: flush() cannot store "${this.dbName}" while a transaction begun with BEGIN is open: ` +
+                    "sql.js's export would end it. COMMIT or ROLLBACK it first.");
+            }
+            await this.startSave();
+        }
+    }
     /**
      * Closes the database and saves its committed state to IndexedDB.
      *
@@ -420,6 +581,9 @@ export class IndexedDbAdapter {
         return this.closeRun;
     }
     async closeNow() {
+        if (this.opening) {
+            await this.opening.catch(() => undefined);
+        }
         if (this.saveTimer) {
             clearInterval(this.saveTimer);
             this.saveTimer = null;
@@ -433,9 +597,20 @@ export class IndexedDbAdapter {
                 if (this.inTransaction()) {
                     this.rollbackQuietly();
                 }
-                await this.settleSave();
-                if (this.hasUnsavedWrites()) {
-                    await this.startSave();
+                if (this.crossTab) {
+                    // Under the lock, once the transaction that holds it has failed: a
+                    // write whose save failed is stored, unless another tab saved since.
+                    await this.withCoordination(async () => {
+                        if (this.db && this.hasUnsavedWrites()) {
+                            await this.saveIfStampIs(this.loadedStamp);
+                        }
+                    });
+                }
+                else {
+                    await this.settleSave();
+                    if (this.hasUnsavedWrites()) {
+                        await this.startSave();
+                    }
                 }
                 this.db?.close();
                 this.db = null;
@@ -451,7 +626,8 @@ export class IndexedDbAdapter {
     }
     /**
      * Exports the database as a Uint8Array (SQLite file format).
-     * Can be downloaded or stored externally.
+     * 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.
@@ -462,12 +638,14 @@ export class IndexedDbAdapter {
         if (this.inTransaction()) {
             throw new Error("IndexedDbAdapter: cannot export the database while a transaction is open; sql.js's export would end it.");
         }
-        const image = this.db.export();
-        // export() closed and reopened the connection, which reset its PRAGMAs.
-        this.applyConnectionSettings();
-        return image;
+        return this.exportImage();
     }
-    /** Applies the connection settings open() was asked for: sql.js loses them whenever export() reopens the connection. */
+    /**
+     * 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).
+     */
     applyConnectionSettings() {
         if (this.foreignKeys !== undefined) {
             this.db.run(`PRAGMA foreign_keys = ${this.foreignKeys ? 'ON' : 'OFF'};`);
@@ -476,25 +654,228 @@ export class IndexedDbAdapter {
     /**
      * 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.
+     * 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
      */
     async importDatabase(data) {
         this.ensureOpen();
+        if (this.crossTab) {
+            await this.withCoordination(async () => {
+                this.swapIn(data);
+                await this.saveIfStampIs(undefined);
+            });
+            return;
+        }
         await whenAdmitted(this.gate, () => {
-            this.ensureOpen();
-            // Opened before the current database closes: an image sql.js refuses
-            // leaves the adapter on the database it had.
-            const imported = new this.SQL.Database(data);
-            this.db.close();
-            this.db = imported;
-            this.applyConnectionSettings();
-            this.writeGeneration += 1;
+            this.swapIn(data);
             // The save exports in this turn, so no transaction can open between
             // the swap and the export and hold the save back.
             return this.startSave();
         }, undefined, this.longWait);
     }
+    /** Replaces the database with an image, once sql.js has read it as a SQLite database. */
+    swapIn(data) {
+        this.ensureOpen();
+        const imported = new this.SQL.Database(data);
+        try {
+            // sqlite3_open reads nothing; the first statement reads the header.
+            imported.exec('SELECT count(*) FROM sqlite_master');
+        }
+        catch (error) {
+            imported.close();
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`IndexedDbAdapter: the image to import is not a SQLite database that sql.js can read (${reason}).`);
+        }
+        this.replaceDatabase(imported);
+        this.writeGeneration += 1;
+    }
+    /** Puts `next` in place of the database, with the connection settings the current one has. */
+    replaceDatabase(next) {
+        const settings = this.changedPragmas();
+        this.db.close();
+        this.db = next;
+        this.applyPragmas(settings);
+    }
+    // ==========================================================================
+    // Across tabs
+    // ==========================================================================
+    /**
+     * Runs `work` with this tab holding the database: under the Web Lock, or,
+     * without Web Locks, after this adapter's earlier coordinated work.
+     */
+    withCoordination(work) {
+        const waiting = setTimeout(() => this.reportLockWait(), LONG_WAIT_MS);
+        const start = () => {
+            clearTimeout(waiting);
+            return work();
+        };
+        const locks = this.locks;
+        const held = locks ? locks.request(this.lockName, { mode: 'exclusive' }, start) : this.runCoordinatedInTurn(start);
+        return held.finally(() => clearTimeout(waiting));
+    }
+    /**
+     * 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.
+     */
+    coordinatedStatement(statement) {
+        return this.withCoordination(async () => {
+            for (let attempt = 1;; attempt += 1) {
+                this.ensureOpen();
+                await this.syncFromStore();
+                const result = statement();
+                if (this.inTransaction()) {
+                    // A BEGIN cannot hold the database across tabs between two calls.
+                    this.rollbackQuietly();
+                    throw new Error(`IndexedDbAdapter: "${this.dbName}" coordinates tabs, so a transaction begun with BEGIN through run() or exec() ` +
+                        'cannot be held open; it was rolled back. Use transaction().');
+                }
+                if (!this.hasUnsavedWrites() || (await this.saveIfStampIs(this.loadedStamp))) {
+                    return result;
+                }
+                if (attempt >= MAX_CONFLICT_RETRIES) {
+                    await this.syncFromStore();
+                    throw new IndexedDbConflictError(`IndexedDbAdapter: other tabs saved "${this.dbName}" before each of ${attempt} attempts to store a statement; nothing of it is stored.`);
+                }
+                // Another tab saved first: load its image, and run the statement on it.
+                await this.syncFromStore();
+                await new Promise((resolve) => setTimeout(resolve, Math.random() * 4 * attempt));
+            }
+        });
+    }
+    /**
+     * 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.
+     */
+    coordinatedTransaction(fn) {
+        return this.withCoordination(async () => {
+            this.ensureOpen();
+            await this.syncFromStore();
+            const result = await this.runSerializedTransaction(() => this.transactionNow(fn));
+            if (this.hasUnsavedWrites() && !(await this.saveIfStampIs(this.loadedStamp))) {
+                await this.syncFromStore();
+                throw new IndexedDbConflictError(`IndexedDbAdapter: another tab saved "${this.dbName}" while this transaction ran, so nothing of it is stored. ` +
+                    "That tab's writes are loaded; run the transaction again.");
+            }
+            return result;
+        });
+    }
+    /** Loads the stored image when another tab (or adapter) has saved since this one loaded or saved. */
+    async syncFromStore() {
+        const stored = await this.readIfChanged(this.loadedStamp);
+        if (!stored || !this.db) {
+            return;
+        }
+        // The image in memory gives way: what it held that was not stored was
+        // refused to its callers when its save failed.
+        this.replaceDatabase(stored.image ? new this.SQL.Database(stored.image) : new this.SQL.Database());
+        this.loadedStamp = stored.stamp;
+        this.savedGeneration = this.writeGeneration;
+    }
+    /** Reads the stored stamp, and the image with it when the stamp is not `known`; null when it is. */
+    readIfChanged(known) {
+        return this.withTransactionRetry(() => new Promise((resolve, reject) => {
+            const tx = this.idb.transaction(this.storeName, 'readonly');
+            const store = tx.objectStore(this.storeName);
+            let answer = null;
+            const stampRequest = store.get(STAMP_KEY);
+            stampRequest.onsuccess = () => {
+                const stamp = typeof stampRequest.result === 'string' ? stampRequest.result : null;
+                if (stamp === known)
+                    return;
+                const imageRequest = store.get(IMAGE_KEY);
+                imageRequest.onsuccess = () => {
+                    answer = { image: imageRequest.result ?? null, stamp };
+                };
+            };
+            tx.oncomplete = () => resolve(answer);
+            tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: reading "${this.dbName}" was aborted.`));
+        }));
+    }
+    /**
+     * 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.
+     */
+    async saveIfStampIs(expected) {
+        const generation = this.writeGeneration;
+        const image = this.exportImage();
+        const stamp = this.nextStamp();
+        const stored = await this.withTransactionRetry(() => new Promise((resolve, reject) => {
+            const tx = this.idb.transaction(this.storeName, 'readwrite');
+            const store = tx.objectStore(this.storeName);
+            let wrote = false;
+            const write = () => {
+                store.put(image, IMAGE_KEY);
+                store.put(stamp, STAMP_KEY);
+                wrote = true;
+            };
+            if (expected === undefined) {
+                write();
+            }
+            else {
+                const current = store.get(STAMP_KEY);
+                current.onsuccess = () => {
+                    const found = typeof current.result === 'string' ? current.result : null;
+                    if (found === expected)
+                        write();
+                };
+            }
+            tx.oncomplete = () => resolve(wrote);
+            tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: saving "${this.dbName}" to IndexedDB was aborted.`));
+        }));
+        if (stored) {
+            this.loadedStamp = stamp;
+            this.savedGeneration = Math.max(this.savedGeneration, generation);
+        }
+        return stored;
+    }
+    /** A stamp no other save of this or another tab writes. */
+    nextStamp() {
+        this.stampCount += 1;
+        return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}-${this.stampCount}`;
+    }
+    // ==========================================================================
+    // Saving
+    // ==========================================================================
+    /**
+     * Exports the database for a save, keeping the connection settings a
+     * caller made: sql.js's export() closes the connection and opens it again.
+     */
+    exportImage() {
+        const settings = this.changedPragmas();
+        const image = this.db.export();
+        this.applyPragmas(settings);
+        return image;
+    }
+    /** The connection settings that differ from a fresh connection's. */
+    changedPragmas() {
+        const changed = new Map();
+        if (!this.db)
+            return changed;
+        for (const [name, value] of readPragmas(this.db)) {
+            if (this.pragmaDefaults.get(name) !== value)
+                changed.set(name, value);
+        }
+        return changed;
+    }
+    /** Sets connection settings on the database, after a save or a reload. */
+    applyPragmas(settings) {
+        for (const [name, value] of settings) {
+            const literal = typeof value === 'number' ? String(value) : `'${String(value).replace(/'/g, "''")}'`;
+            try {
+                this.db.exec(`PRAGMA ${name} = ${literal}`);
+            }
+            catch {
+                // A setting this build of SQLite does not take is left as it is.
+            }
+        }
+    }
     /**
      * Opens or creates the IndexedDB database.
      */
@@ -548,26 +929,28 @@ export class IndexedDbAdapter {
         throw lastError;
     }
     /**
-     * Loads the SQLite database from IndexedDB.
-     * @returns Binary database or null if not found
+     * Loads the SQLite database and its stamp from IndexedDB, in one
+     * transaction, so the two belong together.
      */
     async loadFromIndexedDb() {
         if (!this.idb)
-            return null;
-        return this.withTransactionRetry(async () => {
-            return new Promise((resolve, reject) => {
-                const tx = this.idb.transaction(this.storeName, 'readonly');
-                const store = tx.objectStore(this.storeName);
-                const req = store.get('db');
-                req.onsuccess = () => resolve(req.result || null);
-                req.onerror = () => reject(req.error);
+            return { image: null, stamp: null };
+        return this.withTransactionRetry(() => new Promise((resolve, reject) => {
+            const tx = this.idb.transaction(this.storeName, 'readonly');
+            const store = tx.objectStore(this.storeName);
+            const image = store.get(IMAGE_KEY);
+            const stamp = store.get(STAMP_KEY);
+            tx.oncomplete = () => resolve({
+                image: image.result ?? null,
+                stamp: typeof stamp.result === 'string' ? stamp.result : null,
             });
-        });
+            tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: reading "${this.dbName}" was aborted.`));
+        }));
     }
     /**
-     * Writes the current image to IndexedDB. Never called while a transaction is
-     * open (see saveIfIdle): sql.js's export() closes and reopens the connection,
-     * which ends an open transaction.
+     * 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
@@ -578,18 +961,8 @@ export class IndexedDbAdapter {
     async saveToIndexedDb() {
         if (!this.idb || !this.db)
             return;
-        const generation = this.writeGeneration;
-        const data = this.db.export();
-        // export() closed and reopened the connection, which reset its PRAGMAs.
-        this.applyConnectionSettings();
-        await this.withTransactionRetry(() => new Promise((resolve, reject) => {
-            const tx = this.idb.transaction(this.storeName, 'readwrite');
-            tx.objectStore(this.storeName).put(data, 'db');
-            tx.oncomplete = () => resolve();
-            // A failed request aborts the transaction, so abort covers both.
-            tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: saving "${this.dbName}" to IndexedDB was aborted.`));
-        }));
-        this.savedGeneration = Math.max(this.savedGeneration, generation);
+        // exportImage() sets the connection settings again after the export.
+        await this.saveIfStampIs(undefined);
     }
     /** Whether writes were made since the image the last completed save exported. */
     hasUnsavedWrites() {
@@ -634,11 +1007,42 @@ export class IndexedDbAdapter {
         }
         return this.startSave();
     }
+    /**
+     * 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.
+     */
+    async saveThrough(generation) {
+        while (this.savedGeneration < generation && this.db && this.idb) {
+            if (this.saving) {
+                const covering = this.savingGeneration >= generation;
+                try {
+                    await this.saving;
+                }
+                catch (error) {
+                    if (covering)
+                        throw error;
+                }
+                continue;
+            }
+            if (this.gate.openToken() !== null) {
+                await this.gate.ended();
+                continue;
+            }
+            if (this.inTransaction()) {
+                return;
+            }
+            await this.startSave();
+        }
+    }
     /**
      * 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.
      */
     startSave() {
+        this.savingGeneration = this.writeGeneration;
         const saving = this.saveToIndexedDb().finally(() => {
             if (this.saving === saving)
                 this.saving = null;
@@ -660,6 +1064,14 @@ export class IndexedDbAdapter {
             "Inside a transaction() callback, run statements through the callback's handle: one run through the adapter " +
             'itself waits for the transaction, and the transaction waits for it.');
     }
+    reportLockWait() {
+        if (this.lockWaitReported)
+            return;
+        this.lockWaitReported = true;
+        console.warn(`[IndexedDbAdapter] A statement on "${this.dbName}" has waited ${LONG_WAIT_MS / 1000} s for its turn across tabs: ` +
+            "another tab's transaction holds the lock, or a transaction() of this tab whose callback runs a statement through " +
+            "the adapter itself instead of the callback's handle waits on itself.");
+    }
     /**
      * Wraps a transaction operation with retry logic.
      * Handles "NotFoundError" by reopening IndexedDB connection.
@@ -735,12 +1147,20 @@ export class IndexedDbAdapter {
         }
         return null;
     }
-    /**
-     * Prepares a SQL statement for execution.
-     */
-    prepareInternal(statement) {
-        this.ensureOpen();
-        return this.db.prepare(statement);
-    }
 }
+/** The connection settings of `db`, by name. A setting this build does not have is left out. */
+const readPragmas = (db) => {
+    const values = new Map();
+    for (const name of CONNECTION_PRAGMAS) {
+        try {
+            const value = db.exec(`PRAGMA ${name}`)[0]?.values?.[0]?.[0];
+            if (value !== undefined)
+                values.set(name, value);
+        }
+        catch {
+            // Not in this build of SQLite.
+        }
+    }
+    return values;
+};
 //# sourceMappingURL=indexedDbAdapter.js.map