@framers/sql-storage-adapter 0.6.13 → 0.6.15

package/dist/adapters/indexedDbAdapter.d.ts

@@ -134,7 +134,32 @@ export declare class IndexedDbAdapter implements StorageAdapter {
     private db;
     private idb;
     private saveTimer;
-    private dirty;
+    /** 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;
+    /** Whether a failed auto-save has been reported since the last one that succeeded. */
+    private saveFailureReported;
+    /** 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;
+    /**
+     * 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;
@@ -157,6 +182,7 @@ export declare class IndexedDbAdapter implements StorageAdapter {
      * @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
@@ -171,17 +197,32 @@ export declare class IndexedDbAdapter implements StorageAdapter {
      * @returns Array of result rows as objects
      */
     all<T>(statement: string, parameters?: StorageParameters): Promise<T[]>;
+    private allNow;
     /**
      * Executes a script containing multiple SQL statements.
      */
     exec(script: string): Promise<void>;
+    private execNow;
     /**
      * 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.
      */
     transaction<T>(fn: (trx: StorageAdapter) => Promise<T>): Promise<T>;
     /**
-     * Begins a transaction. sql.js executes all statements in implicit transactions,
-     * so this is a no-op for compatibility.
+     * 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.
      */
     beginTransaction(): Promise<void>;
     /**
@@ -193,18 +234,27 @@ export declare class IndexedDbAdapter implements StorageAdapter {
      */
     rollback(): Promise<void>;
     /**
-     * Closes the database and persists final state to IndexedDB.
+     * 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.
+     *
+     * 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;
     /**
      * Imports a database from a Uint8Array (SQLite file).
-     * Replaces the current database.
+     * Replaces the current database once any open transaction() has ended, and
+     * saves it to IndexedDB before it resolves.
      * @param data SQLite database file
      */
     importDatabase(data: Uint8Array): Promise<void>;
@@ -231,22 +281,51 @@ export declare class IndexedDbAdapter implements StorageAdapter {
      */
     private loadFromIndexedDb;
     /**
-     * Saves the SQLite database to IndexedDB.
+     * 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.
+     *
+     * 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;
+    /**
+     * 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;
     /**
      * Wraps a transaction operation with retry logic.
      * Handles "NotFoundError" by reopening IndexedDB connection.
      */
     private withTransactionRetry;
-    /**
-     * Persists to IndexedDB if auto-save is enabled.
-     */
-    private persistIfNeeded;
     /**
      * 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.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"indexedDbAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/indexedDbAdapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"indexedDbAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/indexedDbAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/indexedDbAdapter.js

@@ -44,6 +44,10 @@
  */
 import initSqlJs from 'sql.js';
 import { normaliseParameters } from '../shared/parameterUtils.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. */
+const LONG_WAIT_MS = 10000;
 // ============================================================================
 // GLOBAL SQL.JS SINGLETON
 // ============================================================================
@@ -147,7 +151,35 @@ export class IndexedDbAdapter {
         this.db = null;
         this.idb = null;
         this.saveTimer = null;
-        this.dirty = false;
+        /** Bumped by every statement that can change the database. */
+        this.writeGeneration = 0;
+        /** The generation the last completed save exported; the writes after it are unsaved. */
+        this.savedGeneration = 0;
+        /** The save in progress, if any. */
+        this.saving = null;
+        /** Whether a failed auto-save has been reported since the last one that succeeded. */
+        this.saveFailureReported = false;
+        /** 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;
+        /**
+         * The connection is shared, so transaction() runs one callback at a time.
+         */
+        this.runSerializedTransaction = createSerializedTransactionRunner();
+        /**
+         * 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.
+         */
+        this.gate = createConnectionGate(null, { withoutContext: 'wait' });
+        this.longWait = {
+            afterMs: LONG_WAIT_MS,
+            onLongWait: () => this.reportLongWait(),
+        };
         this.dbName = options.dbName || 'app-db';
         this.storeName = options.storeName || 'sqliteDb';
         this.autoSave = options.autoSave ?? true;
@@ -190,6 +222,9 @@ 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);
+    }
+    runNow(statement, parameters) {
         this.ensureOpen();
         const stmt = this.db.prepare(statement);
         try {
@@ -204,8 +239,7 @@ export class IndexedDbAdapter {
             const rowIdResult = this.db.exec('SELECT last_insert_rowid() AS id');
             const rawRowId = rowIdResult[0]?.values?.[0]?.[0];
             const lastInsertRowid = this.normaliseRowId(rawRowId);
-            this.dirty = true;
-            await this.persistIfNeeded();
+            this.writeGeneration += 1;
             return {
                 changes: this.db.getRowsModified(),
                 lastInsertRowid,
@@ -232,6 +266,9 @@ export class IndexedDbAdapter {
      * @returns Array of result rows as objects
      */
     async all(statement, parameters) {
+        return whenAdmitted(this.gate, () => this.allNow(statement, parameters), undefined, this.longWait);
+    }
+    allNow(statement, parameters) {
         this.ensureOpen();
         const stmt = this.db.prepare(statement);
         try {
@@ -263,35 +300,91 @@ export class IndexedDbAdapter {
      * Executes a script containing multiple SQL statements.
      */
     async exec(script) {
+        return whenAdmitted(this.gate, () => this.execNow(script), undefined, this.longWait);
+    }
+    execNow(script) {
         this.ensureOpen();
-        this.db.exec(script);
-        this.dirty = true;
-        await this.persistIfNeeded();
+        try {
+            this.db.exec(script);
+        }
+        finally {
+            // A script that fails part way keeps the statements before the failure.
+            this.writeGeneration += 1;
+        }
     }
     /**
      * 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.
      */
     async transaction(fn) {
         this.ensureOpen();
-        await this.run('BEGIN TRANSACTION');
+        const queued = setTimeout(() => this.reportLongWait(), LONG_WAIT_MS);
+        return this.runSerializedTransaction(() => {
+            clearTimeout(queued);
+            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();
+                    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;
+                }
+            });
+        });
+    }
+    /**
+     * The statements of one transaction's handle: they carry the transaction's
+     * token, so the gate admits them while the transaction is open.
+     */
+    handleStatements(token) {
+        return {
+            kind: this.kind,
+            capabilities: this.capabilities,
+            open: async () => { },
+            close: async () => { },
+            run: (statement, parameters) => whenAdmitted(this.gate, () => this.runNow(statement, parameters), token),
+            get: async (statement, parameters) => {
+                const rows = await whenAdmitted(this.gate, () => this.allNow(statement, parameters), token);
+                return rows.length > 0 ? rows[0] : null;
+            },
+            all: (statement, parameters) => whenAdmitted(this.gate, () => this.allNow(statement, parameters), token),
+            exec: (script) => whenAdmitted(this.gate, () => this.execNow(script), token),
+            // The handle answers a nested transaction() itself and never calls this.
+            transaction: (fn) => fn(this),
+        };
+    }
+    /** Rolls back the open transaction; one that already ended (a failed statement, close()) is left alone. */
+    rollbackQuietly() {
+        if (!this.db)
+            return;
         try {
-            const result = await fn(this);
-            await this.run('COMMIT');
-            this.dirty = true;
-            await this.persistIfNeeded();
-            return result;
+            this.db.run('ROLLBACK');
         }
-        catch (error) {
-            await this.run('ROLLBACK');
-            throw error;
+        catch {
+            // No transaction is open.
         }
     }
     /**
-     * Begins a transaction. sql.js executes all statements in implicit transactions,
-     * so this is a no-op for compatibility.
+     * 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.
      */
     async beginTransaction() {
-        // sql.js uses auto-commit; explicit BEGIN is optional
         await this.run('BEGIN');
     }
     /**
@@ -299,8 +392,6 @@ export class IndexedDbAdapter {
      */
     async commit() {
         await this.run('COMMIT');
-        this.dirty = true;
-        await this.persistIfNeeded();
     }
     /**
      * Rolls back the current transaction.
@@ -309,19 +400,44 @@ export class IndexedDbAdapter {
         await this.run('ROLLBACK');
     }
     /**
-     * Closes the database and persists final state to IndexedDB.
+     * 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.
      */
-    async close() {
+    close() {
+        if (!this.closeRun) {
+            this.closeRun = this.closeNow().finally(() => {
+                this.closeRun = null;
+            });
+        }
+        return this.closeRun;
+    }
+    async closeNow() {
         if (this.saveTimer) {
             clearInterval(this.saveTimer);
             this.saveTimer = null;
         }
-        if (this.dirty) {
-            await this.saveToIndexedDb();
-        }
         if (this.db) {
-            this.db.close();
-            this.db = null;
+            // From here no statement or transaction starts: a transaction() still
+            // running fails at its next statement, and one queued behind it fails
+            // when it starts.
+            this.closing = true;
+            try {
+                if (this.inTransaction()) {
+                    this.rollbackQuietly();
+                }
+                await this.settleSave();
+                if (this.hasUnsavedWrites()) {
+                    await this.startSave();
+                }
+                this.db?.close();
+                this.db = null;
+            }
+            finally {
+                this.closing = false;
+            }
         }
         if (this.idb) {
             this.idb.close();
@@ -331,23 +447,38 @@ export class IndexedDbAdapter {
     /**
      * Exports the database as a Uint8Array (SQLite file format).
      * Can be downloaded or stored externally.
+     *
+     * 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() {
         this.ensureOpen();
+        if (this.inTransaction()) {
+            throw new Error("IndexedDbAdapter: cannot export the database while a transaction is open; sql.js's export would end it.");
+        }
         return this.db.export();
     }
     /**
      * Imports a database from a Uint8Array (SQLite file).
-     * Replaces the current database.
+     * Replaces the current database once any open transaction() has ended, and
+     * saves it to IndexedDB before it resolves.
      * @param data SQLite database file
      */
     async importDatabase(data) {
         this.ensureOpen();
-        this.db.close();
-        this.db = new this.SQL.Database(data);
-        this.dirty = true;
-        await this.saveToIndexedDb();
+        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.writeGeneration += 1;
+            // 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);
     }
     /**
      * Opens or creates the IndexedDB database.
@@ -419,24 +550,98 @@ export class IndexedDbAdapter {
         });
     }
     /**
-     * Saves the SQLite database to IndexedDB.
+     * 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.
+     *
+     * 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.
      */
     async saveToIndexedDb() {
         if (!this.idb || !this.db)
             return;
+        const generation = this.writeGeneration;
         const data = this.db.export();
-        return this.withTransactionRetry(async () => {
-            return new Promise((resolve, reject) => {
-                const tx = this.idb.transaction(this.storeName, 'readwrite');
-                const store = tx.objectStore(this.storeName);
-                const req = store.put(data, 'db');
-                req.onsuccess = () => {
-                    this.dirty = false;
-                    resolve();
-                };
-                req.onerror = () => reject(req.error);
-            });
+        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);
+    }
+    /** Whether writes were made since the image the last completed save exported. */
+    hasUnsavedWrites() {
+        return this.writeGeneration !== this.savedGeneration;
+    }
+    /**
+     * 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.
+     */
+    inTransaction() {
+        if (this.gate.openToken() !== null)
+            return true;
+        if (!this.db)
+            return false;
+        try {
+            this.db.run('BEGIN');
+        }
+        catch {
+            return true;
+        }
+        try {
+            this.db.run('ROLLBACK');
+        }
+        catch {
+            // The probe's own transaction did not roll back; it is open.
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Starts a save of the unsaved writes, unless a save is running or a
+     * transaction is open; the auto-save tick tries again later.
+     */
+    saveIfIdle() {
+        if (this.saving)
+            return this.saving;
+        if (!this.db || !this.idb || !this.hasUnsavedWrites() || this.inTransaction()) {
+            return Promise.resolve();
+        }
+        return 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() {
+        const saving = this.saveToIndexedDb().finally(() => {
+            if (this.saving === saving)
+                this.saving = null;
         });
+        this.saving = saving;
+        return saving;
+    }
+    /** Waits for a save in progress to settle, whether it succeeded or not. */
+    async settleSave() {
+        if (this.saving) {
+            await this.saving.catch(() => undefined);
+        }
+    }
+    reportLongWait() {
+        if (this.longWaitReported)
+            return;
+        this.longWaitReported = true;
+        console.warn(`[IndexedDbAdapter] A statement on "${this.dbName}" has waited ${LONG_WAIT_MS / 1000} s for an open transaction to end. ` +
+            "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.');
     }
     /**
      * Wraps a transaction operation with retry logic.
@@ -472,30 +677,32 @@ export class IndexedDbAdapter {
         }
         throw lastError;
     }
-    /**
-     * Persists to IndexedDB if auto-save is enabled.
-     */
-    async persistIfNeeded() {
-        if (this.autoSave && !this.saveTimer) {
-            // Immediate save on first write, then batched
-            await this.saveToIndexedDb();
-        }
-    }
     /**
      * Starts auto-save interval.
      */
     startAutoSave() {
-        this.saveTimer = setInterval(async () => {
-            if (this.dirty) {
-                await this.saveToIndexedDb();
-            }
+        this.saveTimer = setInterval(() => {
+            void this.autoSaveTick();
         }, this.saveIntervalMs);
     }
+    /** One auto-save tick: a failed save is reported once and tried again on the next tick. */
+    async autoSaveTick() {
+        try {
+            await this.saveIfIdle();
+            this.saveFailureReported = false;
+        }
+        catch (error) {
+            if (!this.saveFailureReported) {
+                this.saveFailureReported = true;
+                console.warn(`[IndexedDbAdapter] Saving "${this.dbName}" to IndexedDB failed; the next tick tries again.`, error);
+            }
+        }
+    }
     /**
      * Ensures the database is open.
      */
     ensureOpen() {
-        if (!this.db) {
+        if (!this.db || this.closing) {
             throw new Error('IndexedDbAdapter: Database not open. Call open() first.');
         }
     }