indexeddbshim 17.0.0 → 17.2.0

package/src/IDBFactory.js

@@ -388,7 +388,7 @@ function IDBFactory () {
  *   __connections: {
  *     [key: string]: import('./IDBDatabase.js').IDBDatabaseFull[]
  *   }
-* }} IDBFactoryFull
+ * }} IDBFactoryFull
  */
 
 const IDBFactoryAlias = IDBFactory;
@@ -593,7 +593,7 @@ IDBFactory.prototype.open = function (name /* , version */) {
                                     req.__result
                                 ).__versionTransaction = null;
                                 sysdbFinishedCb(systx, false, function () {
-                                    req.transaction.__transFinishedCb(false, function () {
+                                    req.transaction.__callTransFinishedCb(false, function () {
                                         ev.complete();
                                         req.__transaction = null;
                                     });
@@ -716,6 +716,13 @@ IDBFactory.prototype.open = function (name /* , version */) {
     function openDB (oldVersion) {
         /** @type {DatabaseFull} */
         let db;
+        if (version === undefined) {
+            // Resolve before use as a cache key below, or a `open(name)` call
+            //  (no explicit version) would cache/look up under `undefined`
+            //  instead of the actual version, causing a second, separate
+            //  connection to be opened for the same database on reopen.
+            version = oldVersion || 1;
+        }
         if ((useMemoryDatabase || useDatabaseCache) && Object.hasOwn(websqlDBCache, name) && Object.hasOwn(websqlDBCache[name], version)) {
             db = websqlDBCache[name][version];
         } else {
@@ -733,9 +740,6 @@ IDBFactory.prototype.open = function (name /* , version */) {
             }
         }
 
-        if (version === undefined) {
-            version = oldVersion || 1;
-        }
         if (oldVersion > version) {
             const err = createDOMException('VersionError', 'An attempt was made to open a database using a lower version than the existing version.', version);
             if (useDatabaseCache) {
@@ -905,7 +909,7 @@ IDBFactory.prototype.deleteDatabase = function (name) {
                     ({version} = data.rows.item(0));
 
                     const openConnections = me.__connections[name] || [];
-                    triggerAnyVersionChangeAndBlockedEvents(openConnections, req, version, null).then(function () { // eslint-disable-line promise/catch-or-return -- Sync promise
+                    triggerAnyVersionChangeAndBlockedEvents(openConnections, req, version, null).then(function () {
                         // Since we need two databases which can't be in a single transaction, we
                         //  do this deleting from `dbVersions` first since the `__sys__` deleting
                         //  only impacts file memory whereas this one is critical for avoiding it
@@ -934,7 +938,7 @@ IDBFactory.prototype.deleteDatabase = function (name) {
                         });
                         return undefined;
                     // @ts-expect-error It's ok
-                    }, dbError);
+                    }).catch(dbError);
                     return undefined;
                 }, dbError);
             });
@@ -966,14 +970,14 @@ IDBFactory.prototype.cmp = function (key1, key2) {
 };
 
 /**
-* May return outdated information if a database has since been deleted.
-* @see https://github.com/w3c/IndexedDB/pull/240/files
-* @this {IDBFactoryFull}
-* @returns {Promise<{
-*   name: string,
-*   version: Integer
-* }[]>}
-*/
+ * May return outdated information if a database has since been deleted.
+ * @see https://github.com/w3c/IndexedDB/pull/240/files
+ * @this {IDBFactoryFull}
+ * @returns {Promise<{
+ *   name: string,
+ *   version: Integer
+ * }[]>}
+ */
 IDBFactory.prototype.databases = function () {
     const me = this;
     let calledDbCreateError = false;
@@ -1018,17 +1022,17 @@ IDBFactory.prototype.databases = function () {
 };
 
 /**
-* @todo forceClose: Test
-* This is provided to facilitate unit-testing of the
-*  closing of a database connection with a forced flag:
-* <https://w3c.github.io/IndexedDB/#steps-for-closing-a-database-connection>
-* @param {string} dbName
-* @param {Integer} connIdx
-* @param {string} msg
-* @throws {TypeError}
-* @this {IDBFactoryFull}
-* @returns {void}
-*/
+ * @todo forceClose: Test
+ * This is provided to facilitate unit-testing of the
+ *  closing of a database connection with a forced flag:
+ * <https://w3c.github.io/IndexedDB/#steps-for-closing-a-database-connection>
+ * @param {string} dbName
+ * @param {Integer} connIdx
+ * @param {string} msg
+ * @throws {TypeError}
+ * @this {IDBFactoryFull}
+ * @returns {void}
+ */
 IDBFactory.prototype.__forceClose = function (dbName, connIdx, msg) {
     const me = this;
     /**

package/src/IDBIndex.js

@@ -733,8 +733,7 @@ IDBIndex.prototype.__renameIndex = function (store, oldName, newName, colInfoToP
                                 );
                             })
                         );
-                        SyncPromise.all(indexCreations).then(
-                            finish,
+                        SyncPromise.all(indexCreations).then(finish).catch(
                             /** @type {(reason: any) => PromiseLike<never>} */
                             (error)
                         ).catch((err) => {

package/src/IDBKeyRange.js

@@ -6,11 +6,11 @@ const readonlyProperties = /** @type {const} */ (['lower', 'upper', 'lowerOpen',
 
 /**
  * @typedef {globalThis.IDBKeyRange & {
-*   __lowerCached: string|null|false,
-*   __upperCached: string|null|false,
-*   __lowerOpen: boolean,
-* }} IDBKeyRangeFull
-*/
+ *   __lowerCached: string|null|false,
+ *   __upperCached: string|null|false,
+ *   __lowerOpen: boolean,
+ * }} IDBKeyRangeFull
+ */
 
 /**
  * The IndexedDB KeyRange object.

package/src/IDBTransaction.js

@@ -50,6 +50,7 @@ const readonlyProperties = ['objectStoreNames', 'mode', 'db', 'error'];
  *   },
  *   __requestsFinished: boolean,
  *   __transFinishedCb: (err: boolean, cb: ((bool?: boolean) => void)) => void,
+ *   __callTransFinishedCb: (err: boolean, cb: ((bool?: boolean) => void)) => void,
  *   __transactionEndCallback: () => void,
  *   __transactionFinished: boolean,
  *   __completed: boolean,
@@ -157,6 +158,35 @@ IDBTransaction.prototype = EventTargetFactory.createInstance({
 IDBTransaction.prototype.__transFinishedCb = function (err, cb) {
     cb(Boolean(err));
 };
+
+/**
+ * In Node, the real (SQL-commit-capable) `__transFinishedCb` is only
+ * installed once the underlying WebSQL driver's own SQL-queue-idle check
+ * has fired at least once for this transaction (asynchronously, via the
+ * `nonstandardTransCb` passed to `db.transaction`/`.readTransaction`).
+ * Since our own request processing can now finish synchronously (e.g., a
+ * trivial upgrade using a synchronous SQL driver), it is possible to reach
+ * transaction completion here before that has happened, in which case
+ * `__transFinishedCb` is still the non-committing default above. Calling
+ * that default directly would silently skip the actual SQL commit and
+ * leave the underlying WebSQL transaction "running" forever, hanging any
+ * later transaction on that same database connection. So, if the real
+ * callback isn't installed yet, defer and retry until it is.
+ * @this {IDBTransactionFull}
+ * @param {boolean} err
+ * @param {(bool?: boolean) => void} cb
+ * @returns {void}
+ */
+IDBTransaction.prototype.__callTransFinishedCb = function (err, cb) {
+    const me = this;
+    if (me.__transFinishedCb === IDBTransaction.prototype.__transFinishedCb) {
+        setTimeout(() => {
+            me.__callTransFinishedCb(err, cb);
+        }, 0);
+        return;
+    }
+    me.__transFinishedCb(err, cb);
+};
 /**
  * @this {IDBTransactionFull}
  * @returns {void}
@@ -214,7 +244,7 @@ IDBTransaction.prototype.__executeRequests = function () {
                     me.__abortTransaction(createDOMException('AbortError', 'A request was aborted (in user handler after success).'));
                     return;
                 }
-                executeNextRequest();
+                util.runContinuationSafely(executeNextRequest);
             }
 
             /**
@@ -282,7 +312,7 @@ IDBTransaction.prototype.__executeRequests = function () {
                     try {
                         q = me.__requests[i];
                         if (!q.req) {
-                            q.op(tx, q.args, executeNextRequest, error);
+                            q.op(tx, q.args, () => util.runContinuationSafely(executeNextRequest), error);
                             return;
                         }
                         if (q.req.__done) { // Avoid continuing with aborted requests
@@ -746,10 +776,10 @@ IDBTransaction.__assertActive = function (tx) {
 };
 
 /**
-* Used by our `EventTarget.prototype` library to implement bubbling/capturing.
+ * Used by our `EventTarget.prototype` library to implement bubbling/capturing.
  * @this {IDBTransactionFull}
-* @returns {import('./IDBDatabase.js').IDBDatabaseFull}
-*/
+ * @returns {import('./IDBDatabase.js').IDBDatabaseFull}
+ */
 IDBTransaction.prototype.__getParent = function () {
     return this.db;
 };

package/src/Key.js

@@ -32,14 +32,14 @@ import CFG from './CFG.js';
  */
 
 /**
-* @typedef {object} KeyValueObject
-* @property {KeyType|"NaN"|"null"|"undefined"|"boolean"|"object"|"symbol"|
-*   "function"|"bigint"} type If not `KeyType`, indicates invalid value
-* @property {Value} [value]
-* @property {boolean} [invalid]
-* @property {string} [message]
-* @todo Specify acceptable `value` more precisely
-*/
+ * @typedef {object} KeyValueObject
+ * @property {KeyType|"NaN"|"null"|"undefined"|"boolean"|"object"|"symbol"|
+ *   "function"|"bigint"} type If not `KeyType`, indicates invalid value
+ * @property {Value} [value]
+ * @property {boolean} [invalid]
+ * @property {string} [message]
+ * @todo Specify acceptable `value` more precisely
+ */
 
 /**
  * @typedef {number|string|Date|ArrayBuffer} ValueTypePrimitive
@@ -283,14 +283,22 @@ const types = {
                 encoded[i] = encodedItem;
             }
             encoded.push(keyTypeToEncodedChar.invalid + '-'); // append an extra item, so empty arrays sort correctly
-            return keyTypeToEncodedChar.array + '-' + JSON.stringify(encoded);
+            let encodedKey = JSON.stringify(encoded);
+            if (CFG.escapeNULForSQLiteStatements === false) {
+                encodedKey = encodedKey.replaceAll(String.raw`\u0000`, '\0');
+            }
+            return keyTypeToEncodedChar.array + '-' + encodedKey;
         },
         /**
          * @param {string} key
          * @returns {ValueTypeArray}
          */
         decode (key) {
-            const decoded = JSON.parse(key.slice(2));
+            let decodedKey = key.slice(2);
+            if (CFG.escapeNULForSQLiteStatements === false) {
+                decodedKey = decodedKey.replaceAll('\0', String.raw`\u0000`);
+            }
+            const decoded = JSON.parse(decodedKey);
             decoded.pop(); // remove the extra item
             for (let i = 0; i < decoded.length; i++) {
                 const item = decoded[i];
@@ -466,10 +474,10 @@ function convertValueToKey (input, seen) {
 }
 
 /**
-* Currently not in use.
-* @param {Value} input
-* @returns {KeyValueObject}
-*/
+ * Currently not in use.
+ * @param {Value} input
+ * @returns {KeyValueObject}
+ */
 function convertValueToMultiEntryKey (input) {
     return convertValueToKeyValueDecoded(input, null, true, true);
 }
@@ -508,17 +516,17 @@ function getCopyBytesHeldByBufferSource (O) {
 }
 
 /**
-* Shortcut utility to avoid returning full keys from `convertValueToKey`
-*   and subsequent need to process in calling code unless `fullKeys` is
-*   set; may throw.
-* @param {Value} input
-* @param {Value[]|null} [seen]
-* @param {boolean} [multiEntry]
-* @param {boolean} [fullKeys]
-* @throws {TypeError} See `getCopyBytesHeldByBufferSource`
-* @todo Document other allowable `input`
-* @returns {KeyValueObject}
-*/
+ * Shortcut utility to avoid returning full keys from `convertValueToKey`
+ *   and subsequent need to process in calling code unless `fullKeys` is
+ *   set; may throw.
+ * @param {Value} input
+ * @param {Value[]|null} [seen]
+ * @param {boolean} [multiEntry]
+ * @param {boolean} [fullKeys]
+ * @throws {TypeError} See `getCopyBytesHeldByBufferSource`
+ * @todo Document other allowable `input`
+ * @returns {KeyValueObject}
+ */
 function convertValueToKeyValueDecoded (input, seen, multiEntry, fullKeys) {
     seen ||= [];
     if (seen.includes(input)) {
@@ -615,12 +623,12 @@ function convertValueToMultiEntryKeyDecoded (key, fullKeys) {
 }
 
 /**
-* An internal utility.
-* @param {Value} input
-* @param {Value[]|null|undefined} [seen]
-* @throws {DOMException} `DataError`
-* @returns {KeyValueObject}
-*/
+ * An internal utility.
+ * @param {Value} input
+ * @param {Value[]|null|undefined} [seen]
+ * @throws {DOMException} `DataError`
+ * @returns {KeyValueObject}
+ */
 function convertValueToKeyRethrowingAndIfInvalid (input, seen) {
     const key = convertValueToKey(input, seen);
     if (key.invalid) {
@@ -641,26 +649,26 @@ function extractKeyFromValueUsingKeyPath (value, keyPath, multiEntry) {
     return extractKeyValueDecodedFromValueUsingKeyPath(value, keyPath, multiEntry, true);
 }
 /**
-* Not currently in use.
-* @param {Value} value
-* @param {KeyPath} keyPath
-* @param {boolean} multiEntry
-* @returns {KeyPathEvaluateValue}
-*/
+ * Not currently in use.
+ * @param {Value} value
+ * @param {KeyPath} keyPath
+ * @param {boolean} multiEntry
+ * @returns {KeyPathEvaluateValue}
+ */
 function evaluateKeyPathOnValue (value, keyPath, multiEntry) {
     return evaluateKeyPathOnValueToDecodedValue(value, keyPath, multiEntry, true);
 }
 
 /**
-* May throw, return `{failure: true}` (e.g., non-object on keyPath resolution)
-*    or `{invalid: true}` (e.g., `NaN`).
-* @param {Value} value
-* @param {KeyPath} keyPath
-* @param {boolean} [multiEntry]
-* @param {boolean} [fullKeys]
-* @returns {KeyValueObject|KeyPathEvaluateValue}
-* @todo Document other possible return?
-*/
+ * May throw, return `{failure: true}` (e.g., non-object on keyPath resolution)
+ *    or `{invalid: true}` (e.g., `NaN`).
+ * @param {Value} value
+ * @param {KeyPath} keyPath
+ * @param {boolean} [multiEntry]
+ * @param {boolean} [fullKeys]
+ * @returns {KeyValueObject|KeyPathEvaluateValue}
+ * @todo Document other possible return?
+ */
 function extractKeyValueDecodedFromValueUsingKeyPath (value, keyPath, multiEntry, fullKeys) {
     const r = evaluateKeyPathOnValueToDecodedValue(value, keyPath, multiEntry, fullKeys);
     if (r.failure) {
@@ -891,11 +899,11 @@ function findMultiEntryMatches (keyEntry, range) {
 }
 
 /**
-* Not currently in use but keeping for spec parity.
-* @param {Key} key
-* @throws {Error} Upon a "bad key"
-* @returns {ValueType}
-*/
+ * Not currently in use but keeping for spec parity.
+ * @param {Key} key
+ * @throws {Error} Upon a "bad key"
+ * @returns {ValueType}
+ */
 function convertKeyToValue (key) {
     const {type, value} = key;
     switch (type) {
@@ -977,10 +985,10 @@ const MAX_ALLOWED_CURRENT_NUMBER = 9007199254740992; // 2 ^ 53 (Also equal to `N
  */
 
 /**
-* @callback SQLFailureCallback
-* @param {DOMException|Error} exception
-* @returns {void}
-*/
+ * @callback SQLFailureCallback
+ * @param {DOMException|Error} exception
+ * @returns {void}
+ */
 
 /**
  *

package/src/node-UnicodeIdentifiers.js

@@ -13,7 +13,11 @@ CFG.win = {openDatabase: nodeWebSQL};
  * @returns {import('./setGlobalVars.js').ShimmedObject|Window}
  */
 const __setGlobalVars = function (idb, initialConfig = {}) {
-    const obj = setGlobalVars(idb, {fs, ...initialConfig});
+    const obj = setGlobalVars(idb, {
+        fs,
+        escapeNULForSQLiteStatements: false,
+        ...initialConfig
+    });
     /* istanbul ignore next -- TS guard */
     if (!obj.shimIndexedDB) {
         return obj;

package/src/node.js

@@ -12,7 +12,11 @@ CFG.win = {openDatabase: nodeWebSQL};
  * @returns {import('./setGlobalVars.js').ShimmedObject|Window}
  */
 const __setGlobalVars = function (idb, initialConfig = {}) {
-    return setGlobalVars(idb, {fs, ...initialConfig});
+    return setGlobalVars(idb, {
+        fs,
+        escapeNULForSQLiteStatements: false,
+        ...initialConfig
+    });
 };
 
 export default __setGlobalVars;

package/src/nodeSQLiteDatabase.js

@@ -0,0 +1,174 @@
+import Database from 'better-sqlite3';
+
+/**
+ *
+ */
+class SQLiteResult {
+    /**
+     * @param {Error|null|undefined} error
+     * @param {number|undefined} [insertId]
+     * @param {number} [rowsAffected]
+     * @param {object[]} [rows]
+     */
+    constructor (error, insertId, rowsAffected, rows) {
+        this.error = error;
+        this.insertId = insertId;
+        this.rowsAffected = rowsAffected;
+        this.rows = rows;
+    }
+}
+
+const READ_ONLY_ERROR = new Error(
+    'could not prepare statement (23 not authorized)'
+);
+
+/**
+ * @typedef {(sql: string, duration: number) => void} SQLProfileCallback
+ */
+
+/**
+ * @typedef {((sql: string) => void)|undefined} SQLTraceCallback
+ */
+
+/**
+ * @param {string} name
+ * @param {{busyTimeout?: number, trace?: (sql: string) => void, profile?: SQLProfileCallback}} [opts]
+ * @returns {void}
+ */
+function SQLiteDatabase (name, opts = {}) {
+    /** @type {import('better-sqlite3').Database} */
+    const db = new Database(name);
+
+    /** @type {SQLTraceCallback} */
+    // eslint-disable-next-line prefer-destructuring -- TS
+    let trace = opts.trace;
+    /** @type {SQLProfileCallback|undefined} */
+    // eslint-disable-next-line prefer-destructuring -- TS
+    let profile = opts.profile;
+
+    if (opts.busyTimeout) {
+        db.pragma('busy_timeout = ' + Number(opts.busyTimeout));
+    }
+
+    // Kept untyped (rather than the better-sqlite3 `Database` type) since that
+    //  type is internal to `@types/better-sqlite3` and can't be named in this
+    //  file's emitted declaration.
+    this._db = /** @type {any} */ ({
+        _db: db,
+        /**
+         * Compatibility with node-sqlite3's configure API.
+         * @param {'busyTimeout'|'trace'|'profile'} option
+         * @param {number|((sql: string, duration?: number) => void)} value
+         * @returns {void}
+         */
+        configure (option, value) {
+            if (option === 'busyTimeout') {
+                db.pragma('busy_timeout = ' + Number(/** @type {number} */ (value)));
+                return;
+            }
+            if (option === 'trace') {
+                trace = /** @type {(sql: string) => void} */ (value);
+                return;
+            }
+            if (option === 'profile') {
+                profile = /** @type {SQLProfileCallback} */ (value);
+            }
+        },
+        /**
+         * Compatibility with callback-oriented close semantics.
+         * @param {(err?: Error|null) => void} [cb]
+         * @returns {void}
+         */
+        close (cb) {
+            try {
+                db.close();
+                if (cb) {
+                    return cb(null);
+                }
+            } catch (err) {
+                if (cb) {
+                    return cb(/** @type {Error} */ (err));
+                }
+            }
+            return undefined;
+        },
+        getTrace () {
+            return trace;
+        },
+        getProfile () {
+            return profile;
+        }
+    });
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} sql
+ * @param {unknown[]} args
+ * @returns {object[]}
+ */
+function runSelect (db, sql, args) {
+    const stmt = db.prepare(sql);
+    return stmt.reader ? /** @type {object[]} */ (stmt.all(...args)) : [];
+}
+
+/**
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} sql
+ * @param {unknown[]} args
+ * @returns {import('better-sqlite3').RunResult}
+ */
+function runNonSelect (db, sql, args) {
+    const stmt = db.prepare(sql);
+    return stmt.run(...args);
+}
+
+/**
+ * @param {{sql: string, args: unknown[]}[]} queries
+ * @param {boolean} readOnly
+ * @param {(err: Error|null, results?: SQLiteResult[]) => void} callback
+ * @returns {void}
+ */
+SQLiteDatabase.prototype.exec = function exec (queries, readOnly, callback) {
+    const db = this._db._db;
+    const len = queries.length;
+    const results = Array.from({length: len});
+
+    for (let i = 0; i < len; i++) {
+        const query = queries[i];
+        const {sql, args} = query;
+        const isSelect = (/^\s*SELECT\b/iu).test(sql);
+        if (readOnly && !isSelect) {
+            results[i] = new SQLiteResult(READ_ONLY_ERROR);
+            continue;
+        }
+        const trace = this._db.getTrace();
+        const profile = this._db.getProfile();
+        // eslint-disable-next-line unicorn/prefer-bigint-literals -- `0n` needs ES2020+ target for tsc
+        const start = profile ? process.hrtime.bigint() : BigInt(0);
+        try {
+            if (trace) {
+                trace(sql);
+            }
+            if (isSelect) {
+                const rows = runSelect(db, sql, args);
+                results[i] = new SQLiteResult(null, undefined, 0, rows);
+            } else {
+                const executionResult = runNonSelect(db, sql, args);
+                const insertId = Number(executionResult.lastInsertRowid);
+                results[i] = new SQLiteResult(null, insertId, executionResult.changes, []);
+            }
+        } catch (err) {
+            results[i] = new SQLiteResult(/** @type {Error} */ (err));
+        } finally {
+            if (profile) {
+                profile(sql, Number(process.hrtime.bigint() - start));
+            }
+        }
+    }
+    queueMicrotask(() => {
+        callback(null, results);
+    });
+};
+
+export default SQLiteDatabase;

package/src/nodeWebSQL.js

@@ -1,5 +1,5 @@
 import customOpenDatabase from 'websql-configurable/custom/index.js';
-import SQLiteDatabase from 'websql-configurable/lib/sqlite/SQLiteDatabase.js';
+import SQLiteDatabase from './nodeSQLiteDatabase.js';
 import CFG from './CFG.js';
 
 /**
@@ -12,11 +12,9 @@ function wrappedSQLiteDatabase (name) {
         db._db.configure('busyTimeout', /** @type {number} */ (CFG.sqlBusyTimeout)); // Default is 1000
     }
     if (CFG.sqlTrace) {
-        // @ts-expect-error native API?
         db._db.configure('trace', CFG.sqlTrace);
     }
     if (CFG.sqlProfile) {
-        // @ts-expect-error native API?
         db._db.configure('profile', CFG.sqlProfile);
     }
     return db;