indexeddbshim 17.2.1 → 17.3.0

package/src/IDBFactory.js

@@ -1,6 +1,6 @@
 /* eslint-disable sonarjs/no-invariant-returns -- Convenient here */
 // eslint-disable-next-line no-restricted-imports -- Can be polyfilled
-import path from 'path';
+import path from 'node:path';
 import SyncPromise from 'sync-promise-expanded';
 
 import {createEvent} from './Event.js';
@@ -18,6 +18,18 @@ import CFG from './CFG.js';
  * @typedef {number} Integer
  */
 
+/**
+ * @typedef {import('websql-configurable/lib/websql/WebSQLTransaction.js').default} WebSQLTransaction
+ */
+
+/**
+ * @typedef {import('websql-configurable/lib/websql/WebSQLTransaction.js').SqlErrorCallback} SqlErrorCallback
+ */
+
+/**
+ * @typedef {import('websql-configurable/lib/websql/WebSQLResultSet.js').default} WebSQLResultSet
+ */
+
 /**
  * @callback DatabaseDeleted
  * @returns {void}
@@ -52,7 +64,7 @@ const hasNullOrigin = () => CFG.checkOrigin !== false && (getOrigin() === 'null'
  *   [key: string]: {
  *     [key: string]: {
  *       req: import('./IDBRequest.js').IDBOpenDBRequestFull,
- *       cb: (req: import('./IDBRequest.js').IDBRequestFull) => void,
+ *       cb: (req: import('./IDBRequest.js').IDBOpenDBRequestFull) => void,
  *     }[]
  *   }
  * }}
@@ -78,9 +90,13 @@ function processNextInConnectionQueue (name, origin = getOrigin()) {
         queueItems.shift();
         processNextInConnectionQueue(name, origin);
     }
+    // Only a terminal (`success`/`error`) event advances the queue --
+    //   `blocked` means this request is still pending (waiting on other
+    //   connections to close), so later requests for the same database must
+    //   keep waiting behind it rather than starting concurrently, per
+    //   https://w3c.github.io/IndexedDB/#request-connection-queue.
     req.addEventListener('success', removeFromQueue);
     req.addEventListener('error', removeFromQueue);
-    req.addEventListener('blocked', removeFromQueue);
     cb(req);
 }
 
@@ -117,7 +133,7 @@ function triggerAnyVersionChangeAndBlockedEvents (openConnections, req, oldVersi
     //    auto-close if unloading
 
     /**
-     * @param {IDBDatabase} connection
+     * @param {import('./IDBDatabase.js').IDBDatabaseFull} connection
      * @returns {boolean|undefined}
      */
     const connectionIsClosed = (connection) => connection.__closePending;
@@ -134,6 +150,7 @@ function triggerAnyVersionChangeAndBlockedEvents (openConnections, req, oldVersi
                 return undefined;
             }
             const e = /** @type {Event & IDBVersionChangeEvent} */ (
+                // @ts-ignore It's ok; needed under some TS versions
                 new IDBVersionChangeEvent('versionchange', {oldVersion, newVersion})
             );
             return new SyncPromise(function (resolve) {
@@ -156,6 +173,7 @@ function triggerAnyVersionChangeAndBlockedEvents (openConnections, req, oldVersi
                 }
             };
             const e = /** @type {Event & IDBVersionChangeEvent} */ (
+                // @ts-ignore It's ok; needed under some TS versions
                 new IDBVersionChangeEvent('blocked', {oldVersion, newVersion})
             );
             setTimeout(() => {
@@ -163,7 +181,10 @@ function triggerAnyVersionChangeAndBlockedEvents (openConnections, req, oldVersi
                 if (!connectionsClosed()) {
                     openConnections.forEach((connection) => {
                         if (!connectionIsClosed(connection)) {
-                            connection.__unblocking = unblocking;
+                            // Several concurrently-blocked requests can each be
+                            //   waiting on this same connection, so append
+                            //   rather than overwrite -- see `IDBDatabase.close`.
+                            connection.__unblocking.push(unblocking);
                         }
                     });
                 } else {
@@ -219,12 +240,63 @@ function getLatestCachedWebSQLDB (name) {
     ];
 }
 
+/**
+ * A cached WebSQL connection (e.g., from a prior `open()`) can keep the
+ *  underlying SQLite file handle open even after `IDBDatabase#close()`
+ *  (which only flags the connection for closing without releasing the
+ *  handle, to allow instance reuse). On Windows, deleting a file while a
+ *  handle to it is still open fails with `EBUSY`, so any cached connections
+ *  for `name` must be actually closed (and evicted, since they're no longer
+ *  usable) before attempting to remove the file.
+ * @param {string} name
+ * @param {() => void} cb
+ * @returns {void}
+ */
+function closeCachedWebSQLConnections (name, cb) {
+    if (!Object.hasOwn(websqlDBCache, name)) {
+        cb();
+        return;
+    }
+    const dbs = Object.values(websqlDBCache[name]);
+    delete websqlDBCache[name];
+    let remaining = dbs.length;
+    if (remaining === 0) {
+        cb();
+        return;
+    }
+    dbs.forEach((db) => {
+        const sqliteDB = db._db && db._db._db;
+        if (!sqliteDB || !sqliteDB.close) {
+            remaining--;
+            if (remaining === 0) {
+                cb();
+            }
+            return;
+        }
+        sqliteDB.close(
+            /**
+             * @param {Error} err
+             * @returns {void}
+             */
+            (err) => {
+                if (err) {
+                    console.warn('Error closing database connection prior to file removal: ' + err);
+                }
+                remaining--;
+                if (remaining === 0) {
+                    cb();
+                }
+            }
+        );
+    });
+}
+
 /**
  * @param {OpenDatabase} __openDatabase
  * @param {string} name
  * @param {string} escapedDatabaseName
  * @param {DatabaseDeleted} databaseDeleted
- * @param {(tx: SQLTransaction|Error|SQLError, err?: SQLError) => boolean} dbError
+ * @param {(tx: WebSQLTransaction|Error|(Error & {code?: number}), err?: (Error & {code?: number})) => boolean} dbError
  * @returns {void}
  */
 function cleanupDatabaseResources (__openDatabase, name, escapedDatabaseName, databaseDeleted, dbError) {
@@ -257,15 +329,18 @@ function cleanupDatabaseResources (__openDatabase, name, escapedDatabaseName, da
         return;
     }
     if (fs && CFG.deleteDatabaseFiles !== false) {
-        fs.unlink(path.join(CFG.databaseBasePath || '', escapedDatabaseName), (err) => {
-            if (err && err.code !== 'ENOENT') { // Ignore if file is already deleted
-                dbError({
-                    code: 0,
-                    message: 'Error removing database file: ' + escapedDatabaseName + ' ' + err
-                });
-                return;
-            }
-            databaseDeleted();
+        closeCachedWebSQLConnections(name, () => {
+            fs.unlink(path.join(CFG.databaseBasePath || '', escapedDatabaseName), (err) => {
+                if (err && err.code !== 'ENOENT') { // Ignore if file is already deleted
+                    const removalError = /** @type {Error & {code?: number}} */ (
+                        new Error('Error removing database file: ' + escapedDatabaseName + ' ' + err)
+                    );
+                    removalError.code = 0;
+                    dbError(removalError);
+                    return;
+                }
+                databaseDeleted();
+            });
         });
         return;
     }
@@ -289,7 +364,7 @@ function cleanupDatabaseResources (__openDatabase, name, escapedDatabaseName, da
                     // Delete all tables in this database, maintained in the sys table
                     tx.executeSql('DROP TABLE ' + util.escapeStoreNameForSQL(
                         util.unescapeSQLiteResponse( // Avoid double-escaping
-                            tables.item(i).name
+                            /** @type {{name: string}} */ (tables.item(i)).name
                         )
                     ), [], function () {
                         deleteTables(i + 1);
@@ -316,18 +391,18 @@ function cleanupDatabaseResources (__openDatabase, name, escapedDatabaseName, da
  * Creates the sysDB to keep track of version numbers for databases.
  * @param {OpenDatabase} __openDatabase
  * @param {CreateSysDBSuccessCallback} success
- * @param {(tx: SQLTransaction|SQLError|Error, err?: SQLError) => void} failure
+ * @param {(tx: WebSQLTransaction|(Error & {code?: number})|Error, err?: (Error & {code?: number})) => void} failure
  * @returns {void}
  */
 function createSysDB (__openDatabase, success, failure) {
     /**
      *
-     * @param {boolean|SQLTransaction|SQLError} tx
-     * @param {SQLError} [err]
+     * @param {boolean|WebSQLTransaction|(Error & {code?: number})} tx
+     * @param {(Error & {code?: number})} [err]
      * @returns {void}
      */
     function sysDbCreateError (tx, err) {
-        const er = webSQLErrback(/** @type {SQLError} */ (err) || tx);
+        const er = webSQLErrback(/** @type {(Error & {code?: number})} */ (err) || tx);
         if (CFG.DEBUG) { console.log('Error in sysdb transaction - when creating dbVersions', err); }
         failure(er);
     }
@@ -359,9 +434,9 @@ function createSysDB (__openDatabase, success, failure) {
                     'CREATE INDEX IF NOT EXISTS dbvname ON dbVersions(name)',
                     [],
                     success,
-                    /** @type {SQLStatementErrorCallback} */ (sysDbCreateError)
+                    /** @type {SqlErrorCallback} */ (sysDbCreateError)
                 );
-            }, /** @type {SQLStatementErrorCallback} */ (sysDbCreateError));
+            }, /** @type {SqlErrorCallback} */ (sysDbCreateError));
         }, sysDbCreateError);
     }
 }
@@ -387,7 +462,9 @@ function IDBFactory () {
  *   __openDatabase: OpenDatabase,
  *   __connections: {
  *     [key: string]: import('./IDBDatabase.js').IDBDatabaseFull[]
- *   }
+ *   },
+ *   __forceClose: (dbName: string, connIdx: Integer, msg: string) => void,
+ *   __setConnectionQueueOrigin: (origin?: string) => void
  * }} IDBFactoryFull
  */
 
@@ -398,8 +475,10 @@ const IDBFactoryAlias = IDBFactory;
 IDBFactory.__createInstance = function () {
     /**
      * @class
+     * @this {IDBFactoryFull}
      */
     function IDBFactory () {
+        // @ts-expect-error It's ok
         this[Symbol.toStringTag] = 'IDBFactory';
         this.__connections = {};
     }
@@ -462,8 +541,8 @@ IDBFactory.prototype.open = function (name /* , version */) {
 
     /**
      *
-     * @param {SQLTransaction|Error|SQLError} tx
-     * @param {SQLError} [err]
+     * @param {WebSQLTransaction|Error|(Error & {code?: number})} tx
+     * @param {(Error & {code?: number})} [err]
      * @returns {boolean}
      */
     function dbCreateError (tx, err) {
@@ -483,7 +562,7 @@ IDBFactory.prototype.open = function (name /* , version */) {
 
     /**
      *
-     * @param {SQLTransaction} tx
+     * @param {WebSQLTransaction} tx
      * @param {DatabaseFull} db
      * @param {Integer} oldVersion
      * @returns {void}
@@ -509,9 +588,9 @@ IDBFactory.prototype.open = function (name /* , version */) {
                     // DB Upgrade in progress
                     /**
                      *
-                     * @param {SQLTransaction} systx
-                     * @param {boolean|SQLError|DOMException|Error} err
-                     * @param {(tx?: SQLTransaction|SQLError, err?: SQLError|SQLResultSet) => boolean} cb
+                     * @param {WebSQLTransaction} systx
+                     * @param {boolean|(Error & {code?: number})|DOMException|Error} err
+                     * @param {(tx?: WebSQLTransaction|(Error & {code?: number}), err?: (Error & {code?: number})|WebSQLResultSet) => boolean} cb
                      * @returns {void}
                      */
                     let sysdbFinishedCb = function (systx, err, cb) {
@@ -569,37 +648,56 @@ IDBFactory.prototype.open = function (name /* , version */) {
                          */
                         function versionSet () {
                             const e = /** @type {import('eventtargeter').EventWithProps & Event & IDBVersionChangeEvent} */ (
+                                // @ts-ignore It's ok; needed under some TS versions
                                 new IDBVersionChangeEvent('upgradeneeded', {oldVersion, newVersion: version})
                             );
                             req.__result = connection;
                             connection.__upgradeTransaction = req.__transaction = req.__result.__versionTransaction = IDBTransaction.__createInstance(req.__result, req.__result.objectStoreNames, 'versionchange');
                             req.__done = true;
 
-                            req.transaction.__addNonRequestToTransactionQueue(function onupgradeneeded (tx, args, finished /* , error */) {
-                                req.dispatchEvent(e);
-
-                                if (e.__legacyOutputDidListenersThrowError) {
-                                    logError('Error', 'An error occurred in an upgradeneeded handler attached to request chain', /** @type {Error} */ (e.__legacyOutputDidListenersThrowError)); // We do nothing else with this error as per spec
-                                    req.transaction.__abortTransaction(createDOMException('AbortError', 'A request was aborted.'));
-                                    return;
+                            req.transaction.__addNonRequestToTransactionQueue(
+                                /**
+                                 * @param {import('websql-configurable/lib/websql/WebSQLTransaction.js').default} tx
+                                 * @param {ObjectArray} args
+                                 * @param {(result?: any, req?: import('./IDBRequest.js').IDBRequestFull) => void} finished
+                                 * @returns {void}
+                                 */
+                                function onupgradeneeded (tx, args, finished /* , error */) {
+                                    // Unlike ordinary requests, this dispatch doesn't go through
+                                    //   `IDBTransaction`'s own `success`/`error` closures, so it must
+                                    //   open/close the transaction's active-handler window itself.
+                                    req.transaction.__handlerActive = true;
+                                    req.dispatchEvent(e);
+                                    req.transaction.__handlerActive = false;
+
+                                    if (e.__legacyOutputDidListenersThrowError) {
+                                        logError('Error', 'An error occurred in an upgradeneeded handler attached to request chain', /** @type {Error} */ (e.__legacyOutputDidListenersThrowError)); // We do nothing else with this error as per spec
+                                        req.transaction.__abortTransaction(createDOMException('AbortError', 'A request was aborted.'));
+                                        return;
+                                    }
+                                    finished();
                                 }
-                                finished();
-                            });
+                            );
 
                             // eslint-disable-next-line camelcase -- Clear API
-                            req.transaction.on__beforecomplete = function (ev) {
-                                connection.__upgradeTransaction = null;
-                                /** @type {import('./IDBDatabase.js').IDBDatabaseFull} */ (
-                                    req.__result
-                                ).__versionTransaction = null;
-                                sysdbFinishedCb(systx, false, function () {
-                                    req.transaction.__callTransFinishedCb(false, function () {
-                                        ev.complete();
-                                        req.__transaction = null;
+                            req.transaction.on__beforecomplete =
+                                /**
+                                 * @param {Event & {complete: () => void}} ev
+                                 * @returns {void}
+                                 */
+                                function (ev) {
+                                    connection.__upgradeTransaction = null;
+                                    /** @type {import('./IDBDatabase.js').IDBDatabaseFull} */ (
+                                        req.__result
+                                    ).__versionTransaction = null;
+                                    sysdbFinishedCb(systx, false, function () {
+                                        req.transaction.__callTransFinishedCb(false, function () {
+                                            ev.complete();
+                                            req.__transaction = null;
+                                        });
+                                        return false;
                                     });
-                                    return false;
-                                });
-                            };
+                                };
 
                             // eslint-disable-next-line camelcase -- Clear API
                             req.transaction.on__preabort = function () {
@@ -726,12 +824,12 @@ IDBFactory.prototype.open = function (name /* , version */) {
         if ((useMemoryDatabase || useDatabaseCache) && Object.hasOwn(websqlDBCache, name) && Object.hasOwn(websqlDBCache[name], version)) {
             db = websqlDBCache[name][version];
         } else {
-            db = me.__openDatabase(
+            db = /** @type {DatabaseFull} */ (me.__openDatabase(
                 useMemoryDatabase ? CFG.memoryDatabase : path.join(CFG.databaseBasePath || '', escapedDatabaseName),
                 '1',
                 name,
                 CFG.DEFAULT_DB_SIZE
-            );
+            ));
             if (useDatabaseCache) {
                 if (!(Object.hasOwn(websqlDBCache, name))) {
                     websqlDBCache[name] = {};
@@ -765,7 +863,7 @@ IDBFactory.prototype.open = function (name /* , version */) {
                     return;
                 }
                 tx.executeSql('CREATE INDEX IF NOT EXISTS sysname ON __sys__(name)', [], setup, dbCreateError);
-            }, /** @type {SQLStatementErrorCallback} */ (dbCreateError));
+            }, /** @type {SqlErrorCallback} */ (dbCreateError));
         }, dbCreateError);
     }
 
@@ -787,7 +885,7 @@ IDBFactory.prototype.open = function (name /* , version */) {
                             // Database with this name does not exist
                             openDB(0);
                         } else {
-                            openDB(data.rows.item(0).version);
+                            openDB(/** @type {{version: Integer}} */ (data.rows.item(0)).version);
                         }
                     }, dbCreateError);
                 }, dbCreateError);
@@ -851,8 +949,8 @@ IDBFactory.prototype.deleteDatabase = function (name) {
     //  `UnknownError` as we may require upon a SQL deletion error
     /**
      *
-     * @param {SQLTransaction|SQLError|Error} tx
-     * @param {SQLError|boolean} [err]
+     * @param {WebSQLTransaction|(Error & {code?: number})|Error} tx
+     * @param {(Error & {code?: number})|boolean} [err]
      * @returns {boolean}
      */
     function dbError (tx, err) {
@@ -867,7 +965,7 @@ IDBFactory.prototype.deleteDatabase = function (name) {
         //  transaction, corrupting that connection's task queue (see issue with unrelated `open()` calls
         //  failing/crashing after a `deleteDatabase` file-removal error).
         calledDBError = true;
-        const er = webSQLErrback(/** @type {SQLError} */ (err || tx));
+        const er = webSQLErrback(/** @type {(Error & {code?: number})} */ (err || tx));
         sysdbFinishedCbDelete(true, function () {
             req.__done = true;
             req.__error = er;
@@ -891,6 +989,7 @@ IDBFactory.prototype.deleteDatabase = function (name) {
                 req.__result = undefined;
                 req.__done = true;
                 const e = /** @type {Event & IDBVersionChangeEvent} */ (
+                    // @ts-ignore It's ok; needed under some TS versions
                     new IDBVersionChangeEvent('success', {oldVersion: version, newVersion: null})
                 );
                 req.dispatchEvent(e);
@@ -913,7 +1012,7 @@ IDBFactory.prototype.deleteDatabase = function (name) {
                         completeDatabaseDelete();
                         return undefined;
                     }
-                    ({version} = data.rows.item(0));
+                    ({version} = /** @type {{version: Integer}} */ (data.rows.item(0)));
 
                     const openConnections = me.__connections[name] || [];
                     triggerAnyVersionChangeAndBlockedEvents(openConnections, req, version, null).then(function () {
@@ -997,15 +1096,15 @@ IDBFactory.prototype.databases = function () {
         }
         /**
          *
-         * @param {true|SQLTransaction|SQLError|DOMException|Error} tx
-         * @param {SQLError|DOMException|Error} [err]
+         * @param {true|WebSQLTransaction|(Error & {code?: number})|DOMException|Error} tx
+         * @param {(Error & {code?: number})|DOMException|Error} [err]
          * @returns {boolean}
          */
         function dbGetDatabaseNamesError (tx, err) {
             if (calledDbCreateError) {
                 return false;
             }
-            const er = err ? webSQLErrback(/** @type {SQLError} */ (err)) : tx;
+            const er = err ? webSQLErrback(/** @type {(Error & {code?: number})} */ (err)) : tx;
             calledDbCreateError = true;
             reject(er);
             return false;
@@ -1015,7 +1114,7 @@ IDBFactory.prototype.databases = function () {
                 sysReadTx.executeSql('SELECT "name", "version" FROM dbVersions', [], function (sysReadTx, data) {
                     const dbNames = [];
                     for (let i = 0; i < data.rows.length; i++) {
-                        const {name, version} = data.rows.item(i);
+                        const {name, version} = /** @type {{name: string, version: Integer}} */ (data.rows.item(i));
                         dbNames.push({
                             name: util.unescapeSQLiteResponse(name),
                             version
@@ -1085,6 +1184,7 @@ IDBFactory.prototype.__setConnectionQueueOrigin = function (origin = getOrigin()
 IDBFactory.prototype[Symbol.toStringTag] = 'IDBFactoryPrototype';
 
 /* eslint-disable unicorn/no-top-level-side-effects -- Would be good */
+util.setOperationNames(IDBFactory.prototype);
 Object.defineProperty(IDBFactory, 'prototype', {
     writable: false
 });