indexeddbshim 17.0.0 → 17.1.0

package/dist/indexeddbshim.js

@@ -1,4 +1,4 @@
-/*! indexeddbshim - v17.0.0 - 7/28/2026 */
+/*! indexeddbshim - v17.1.0 - 8/6/2026 */
 
 (function (factory) {
   typeof define === 'function' && define.amd ? define(factory) :
@@ -58,7 +58,7 @@
     }
   }
   function _createClass(e, r, t) {
-    return r && _defineProperties(e.prototype, r), Object.defineProperty(e, "prototype", {
+    return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", {
       writable: false
     }), e;
   }
@@ -301,6 +301,13 @@
   function _slicedToArray(r, e) {
     return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest();
   }
+  function _taggedTemplateLiteral(e, t) {
+    return t || (t = e.slice(0)), Object.freeze(Object.defineProperties(e, {
+      raw: {
+        value: Object.freeze(t)
+      }
+    }));
+  }
   function _toConsumableArray(r) {
     return _arrayWithoutHoles(r) || _iterableToArray(r) || _unsupportedIterableToArray(r) || _nonIterableSpread();
   }
@@ -1307,6 +1314,7 @@
    *   sqlBusyTimeout: number,
    *   sqlTrace: () => void,
    *   sqlProfile: () => void,
+   *   escapeNULForSQLiteStatements: boolean,
    *   createIndexes: boolean
    * }} ConfigValues
    */
@@ -1461,8 +1469,8 @@
   // Callback not used by default
   'sqlProfile',
   // Callback not used by default
-
-  'createIndexes'].forEach(function (prop) {
+  // Defaults to true except in Node builds where we can preserve literal NUL with better-sqlite3
+  'escapeNULForSQLiteStatements', 'createIndexes'].forEach(function (prop) {
     /** @type {(val: any) => void} */
     var validator;
     if (Array.isArray(prop)) {
@@ -1543,7 +1551,8 @@
    * @returns {string}
    */
   function escapeSQLiteStatement(arg) {
-    return escapeUnmatchedSurrogates(arg.replaceAll('^', '^^').replaceAll('\0', '^0'));
+    var escaped = arg.replaceAll('^', '^^');
+    return escapeUnmatchedSurrogates(CFG.escapeNULForSQLiteStatements === false ? escaped : escaped.replaceAll('\0', '^0'));
   }
 
   /**
@@ -1551,7 +1560,11 @@
    * @returns {string}
    */
   function unescapeSQLiteResponse(arg) {
-    return unescapeUnmatchedSurrogates(arg).replaceAll(/(\^+)0/g, function (_, esc) {
+    var unescaped = unescapeUnmatchedSurrogates(arg);
+    if (CFG.escapeNULForSQLiteStatements === false) {
+      return unescaped.replaceAll('^^', '^');
+    }
+    return unescaped.replaceAll(/(\^+)0/g, function (_, esc) {
       return esc.length % 2 ? esc.slice(1) + '\0' : _;
     }).replaceAll('^^', '^');
   }
@@ -1952,6 +1965,56 @@
     return v === null || v === undefined;
   }
 
+  /**
+   * Cursor/request continuation chains can call each other synchronously
+   * (e.g. walking a large prefetched buffer, or advancing many interleaved
+   * cursors in one transaction) which, for large enough record counts, can
+   * exceed the JS engine's call stack ("Maximum call stack size exceeded").
+   *
+   * This can't be fixed by deferring continuations to a microtask/macrotask:
+   * the transaction machinery synchronously checks (once the current call
+   * stack unwinds) whether there are any pending requests left in order to
+   * decide it's safe to commit; deferring a continuation opens a real gap in
+   * which that check runs first and the transaction completes prematurely,
+   * with the deferred continuation then acting on an already-finished
+   * transaction (a hang, since it can never resolve).
+   *
+   * Instead, this implements a true trampoline: the first call starts a
+   * synchronous work queue and drains it in a flat loop; any call made while
+   * already draining (i.e. a continuation triggering another continuation)
+   * is simply appended to that same queue and returns immediately instead of
+   * recursing. This keeps everything synchronous (so no completion-check
+   * race is introduced) while preventing the call stack from growing with
+   * each successive continuation.
+   */
+  var continuationState = {
+    /** @type {Array<() => void>|null} */
+    queue: null
+  };
+
+  /**
+   * @param {() => void} fn
+   * @returns {void}
+   */
+  function runContinuationSafely(fn) {
+    if (continuationState.queue) {
+      continuationState.queue.push(fn);
+      return;
+    }
+    var queue = [fn];
+    continuationState.queue = queue;
+    try {
+      while (queue.length) {
+        var next = /** @type {() => void} */queue.shift();
+        next();
+      }
+    } finally {
+      // Ensure a thrown exception can't leave the queue permanently
+      // stuck (which would silently swallow all future continuations).
+      continuationState.queue = null;
+    }
+  }
+
   /**
    * @typedef {Error} DebuggingError
    */
@@ -2633,16 +2696,15 @@
   /* eslint-disable promise/prefer-await-to-callbacks -- Needed for API */
   /* eslint-disable promise/catch-or-return, n/callback-return,
       promise/always-return -- Not needed */
-  /* eslint-disable unicorn/no-this-assignment -- Clarity */
   // Since [immediate](https://github.com/calvinmetcalf/immediate) is
   //   not doing the trick for our WebSQL transactions (at least in Node),
   //   we are forced to make the promises run fully synchronously.
 
-  // Todo: Use ES6 classes
-
+  /* eslint-disable jsdoc/reject-any-type -- Truly arbitrary */
   /**
    * @typedef {any} ArbitraryValue
    */
+  /* eslint-enable jsdoc/reject-any-type -- Truly arbitrary */
 
   /**
    * @callback Resolve
@@ -2702,209 +2764,235 @@
     REJECTED = 1;
 
   /**
-   * @class
-   * @param {(
-   *   resolve: (value: ArbitraryValue | PromiseLike<ArbitraryValue>) => void,
-   *   reject: (reason?: any) => void
-   * ) => void} fn
-   */
-  function SyncPromise(fn) {
-    var that = this;
-    // Value, this will be set to either a resolved value or rejected reason
-    that.v = 0;
-    // State of the promise
-    that.s = PENDING;
-    // Callbacks c[0] is fulfillment and c[1] contains rejection callbacks
-    /** @type {Callbacks|null} */
-    that.c = [[], []];
+   *
+   */
+  var SyncPromise = /*#__PURE__*/function () {
     /**
-     *
-     * @param {ArbitraryValue} val
-     * @param {0|1} state
-     * @returns {void}
+     * @param {(
+     *   resolve: (value: ArbitraryValue | PromiseLike<ArbitraryValue>) => void,
+     *   reject: (reason?: ArbitraryValue) => void
+     * ) => void} fn
      */
-    function transist(val, state) {
-      that.v = val;
-      that.s = state;
-
-      // console.log('state', state);
-      /** @type {Callbacks} */
-      that.c[state].forEach(function (func) {
-        func(val);
-      });
-      // Release memory, but if no handlers have been added, as we
-      //   assume that we will resolve/reject (truly) synchronously
-      //   and thus we avoid flagging checks about whether we've
-      //   already resolved/rejected.
-      if (/** @type {Callbacks} */that.c[state].length) {
-        that.c = null;
-      }
-    }
+    function SyncPromise(fn) {
+      var _this = this;
+      _classCallCheck(this, SyncPromise);
+      // Value, this will be set to either a resolved value or rejected reason
+      _defineProperty(this, "v", 0);
+      // State of the promise
+      this.s = PENDING;
+      // Callbacks c[0] is fulfillment and c[1] contains rejection callbacks
+      /** @type {Callbacks|null} */
+      this.c = [[], []];
+      /**
+       *
+       * @param {ArbitraryValue} val
+       * @param {0|1} state
+       * @returns {void}
+       */
+      var transist = function transist(val, state) {
+        _this.v = val;
+        _this.s = state;
 
-    /** @type {Resolve} */
-    function resolve(val) {
-      if (!that.c) ; else if (isPromise(val)) {
-        addReject(val.then(resolve), reject);
-      } else {
-        transist(val, FULFILLED);
-      }
-    }
+        // console.log('state', state);
+        /** @type {Callbacks} */
+        _this.c[state].forEach(function (func) {
+          func(val);
+        });
+        // Release memory, but if no handlers have been added, as we
+        //   assume that we will resolve/reject (truly) synchronously
+        //   and thus we avoid flagging checks about whether we've
+        //   already resolved/rejected.
+        if (/** @type {Callbacks} */_this.c[state].length) {
+          _this.c = null;
+        }
+      };
 
-    /** @type {Reject} */
-    function reject(reason) {
-      if (!that.c) ; else if (isPromise(reason)) {
-        addReject(reason.then(reject), reject);
-      } else {
-        transist(reason, REJECTED);
+      /** @type {Resolve} */
+      var _resolve = function resolve(val) {
+        if (!_this.c) ; else if (isPromise(val)) {
+          addReject(val.then(_resolve), _reject);
+        } else {
+          transist(val, FULFILLED);
+        }
+      };
+
+      /** @type {Reject} */
+      var _reject = function reject(reason) {
+        if (!_this.c) ; else if (isPromise(reason)) {
+          addReject(reason.then(_reject), _reject);
+        } else {
+          transist(reason, REJECTED);
+        }
+      };
+      try {
+        fn(_resolve, _reject);
+      } catch (err) {
+        _reject(err);
       }
     }
-    try {
-      fn(resolve, reject);
-    } catch (err) {
-      reject(err);
-    }
-  }
 
-  /* eslint-disable unicorn/no-thenable -- Promise API */
-  /**
-   * @param {((value: ArbitraryValue) => ArbitraryValue)|null|undefined} [cb]
-   * @param {(reason: any) => PromiseLike<never>} [errBack]
-   * @returns {SyncPromise}
-   */
-  SyncPromise.prototype.then = function (cb, errBack) {
-    /* eslint-enable unicorn/no-thenable -- Promise API */
-    var that = this;
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
-      var rej = typeof errBack === 'function' ? errBack : reject;
+    /* eslint-disable unicorn/no-thenable -- Promise API */
+    /**
+     * @param {((value: ArbitraryValue) => ArbitraryValue)|null|undefined} [cb]
+     * @param {(reason: ArbitraryValue) => PromiseLike<never>} [errBack]
+     * @returns {SyncPromise}
+     */
+    return _createClass(SyncPromise, [{
+      key: "then",
+      value: function then(cb, errBack) {
+        var _this2 = this;
+        /* eslint-enable unicorn/no-thenable -- Promise API */
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve, reject) {
+          var rej = typeof errBack === 'function' ? errBack : reject;
 
-      /** @type {Settle} */
-      function settle() {
-        try {
-          resolve(cb ? cb(that.v) : that.v);
-        } catch (e) {
-          rej(e);
-        }
-      }
-      if (that.s === FULFILLED) {
-        settle();
-      } else if (that.s === REJECTED) {
-        rej(that.v);
-      } else {
-        /** @type {Callbacks} */that.c[FULFILLED].push(settle);
-        /** @type {Callbacks} */
-        that.c[REJECTED].push(rej);
+          /** @type {Settle} */
+          var settle = function settle() {
+            try {
+              resolve(cb ? cb(_this2.v) : _this2.v);
+            } catch (e) {
+              rej(e);
+            }
+          };
+          if (_this2.s === FULFILLED) {
+            settle();
+          } else if (_this2.s === REJECTED) {
+            rej(_this2.v);
+          } else {
+            /** @type {Callbacks} */_this2.c[FULFILLED].push(settle);
+            /** @type {Callbacks} */
+            _this2.c[REJECTED].push(rej);
+          }
+        });
       }
-    });
-  };
 
-  /**
-   * @param {(reason: any) => PromiseLike<never>|null|undefined} cb
-   * @returns {SyncPromise}
-   */
-  SyncPromise.prototype.catch = function (cb) {
-    var that = this;
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
       /**
-       * @returns {void}
+       * @param {(reason: ArbitraryValue) => PromiseLike<never>|null|undefined} cb
+       * @returns {SyncPromise}
        */
-      function settle() {
-        try {
-          resolve(cb(that.v));
-        } catch (e) {
-          reject(e);
-        }
-      }
-      if (that.s === REJECTED) {
-        settle();
-      } else if (that.s === FULFILLED) {
-        resolve(that.v);
-      } else {
-        /** @type {Callbacks} */that.c[REJECTED].push(settle);
-        /** @type {Callbacks} */
-        that.c[FULFILLED].push(resolve);
+    }, {
+      key: "catch",
+      value: function _catch(cb) {
+        var _this3 = this;
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve, reject) {
+          /**
+           * @returns {void}
+           */
+          var settle = function settle() {
+            try {
+              resolve(cb(_this3.v));
+            } catch (e) {
+              reject(e);
+            }
+          };
+          if (_this3.s === REJECTED) {
+            settle();
+          } else if (_this3.s === FULFILLED) {
+            resolve(_this3.v);
+          } else {
+            /** @type {Callbacks} */_this3.c[REJECTED].push(settle);
+            /** @type {Callbacks} */
+            _this3.c[FULFILLED].push(resolve);
+          }
+        });
       }
-    });
-  };
-
-  /**
-   * @param {unknown[]|[]} promises
-   * @returns {SyncPromise}
-   */
-  SyncPromise.all = function (promises) {
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
-      var l = promises.length;
-      /** @type {ArbitraryValue[]} */
-      var newPromises = [];
-      if (!l) {
-        resolve(newPromises);
-        return;
+    }], [{
+      key: "all",
+      value:
+      /**
+       * @param {unknown[]|[]} promises
+       * @returns {SyncPromise}
+       */
+      function all(promises) {
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve, reject) {
+          var l = promises.length;
+          /** @type {ArbitraryValue[]} */
+          var newPromises = [];
+          if (!l) {
+            resolve(newPromises);
+            return;
+          }
+          promises.forEach(function (p, i) {
+            if (isPromise(/** @type {PromiseLike<ArbitraryValue>} */p)) {
+              addReject(/** @type {PromiseLike<ArbitraryValue>} */p.then(/** @type {OnFulfilled} */
+              function (res) {
+                newPromises[i] = res;
+                --l;
+                if (!l) {
+                  resolve(newPromises);
+                }
+              }), reject);
+            } else {
+              newPromises[i] = p;
+              --l;
+              if (!l) {
+                resolve(promises);
+              }
+            }
+          });
+        });
       }
-      promises.forEach(function (p, i) {
-        if (isPromise(/** @type {PromiseLike<any>} */p)) {
-          addReject(/** @type {PromiseLike<any>} */p.then(/** @type {OnFulfilled} */
-          function (res) {
-            newPromises[i] = res;
-            --l || resolve(newPromises);
-          }), reject);
-        } else {
-          newPromises[i] = p;
-          --l || resolve(promises);
-        }
-      });
-    });
-  };
 
-  /**
-   * @param {unknown[]|[]} promises
-   * @returns {SyncPromise}
-   */
-  SyncPromise.race = function (promises) {
-    var resolved = false;
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
-      promises.some(function (p, i) {
-        if (isPromise(/** @type {PromiseLike<any>} */p)) {
-          addReject(/** @type {PromiseLike<any>} */p.then(/** @type {OnFulfilled} */
-          function (res) {
-            if (resolved) {
-              return;
+      /**
+       * @param {unknown[]|[]} promises
+       * @returns {SyncPromise}
+       */
+    }, {
+      key: "race",
+      value: function race(promises) {
+        var resolved = false;
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve, reject) {
+          // eslint-disable-next-line @stylistic/max-len -- Long
+          // eslint-disable-next-line unicorn/no-unused-array-method-return -- Shortcuts
+          promises.some(function (p) {
+            if (isPromise(/** @type {PromiseLike<ArbitraryValue>} */p)) {
+              addReject(/** @type {PromiseLike<ArbitraryValue>} */p.then(/** @type {OnFulfilled} */
+              function (res) {
+                if (resolved) {
+                  return;
+                }
+                resolve(res);
+                resolved = true;
+              }), reject);
+              return false;
             }
-            resolve(res);
+            resolve(p);
             resolved = true;
-          }), reject);
-          return false;
-        }
-        resolve(p);
-        resolved = true;
-        return true;
-      });
-    });
-  };
+            return true;
+          });
+        });
+      }
 
-  /**
-   * @param {ArbitraryValue} val
-   * @returns {SyncPromise}
-   */
-  SyncPromise.resolve = function (val) {
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
-      resolve(val);
-    });
-  };
+      /**
+       * @param {ArbitraryValue} val
+       * @returns {SyncPromise}
+       */
+    }, {
+      key: "resolve",
+      value: function resolve(val) {
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve) {
+          resolve(val);
+        });
+      }
 
-  /**
-   * @param {ArbitraryValue} val
-   * @returns {SyncPromise}
-   */
-  SyncPromise.reject = function (val) {
-    return new SyncPromise(/** @type {ResolveReject} */
-    function (resolve, reject) {
-      reject(val);
-    });
-  };
+      /**
+       * @param {ArbitraryValue} val
+       * @returns {SyncPromise}
+       */
+    }, {
+      key: "reject",
+      value: function reject(val) {
+        return new SyncPromise(/** @type {ResolveReject} */
+        function (resolve, reject) {
+          reject(val);
+        });
+      }
+    }]);
+  }();
 
   /**
    * Compares two keys.
@@ -2941,6 +3029,8 @@
     return result;
   }
 
+  var _templateObject, _templateObject2;
+
   /**
    * @typedef {NodeJS.TypedArray|DataView} ArrayBufferView
    */
@@ -3216,14 +3306,22 @@
           _iterator.f();
         }
         encoded.push(keyTypeToEncodedChar.invalid + '-'); // append an extra item, so empty arrays sort correctly
-        return keyTypeToEncodedChar.array + '-' + JSON.stringify(encoded);
+        var encodedKey = JSON.stringify(encoded);
+        if (CFG.escapeNULForSQLiteStatements === false) {
+          encodedKey = encodedKey.replaceAll(String.raw(_templateObject || (_templateObject = _taggedTemplateLiteral(["\0"], ["\\u0000"]))), '\0');
+        }
+        return keyTypeToEncodedChar.array + '-' + encodedKey;
       },
       /**
        * @param {string} key
        * @returns {ValueTypeArray}
        */
       decode: function decode(key) {
-        var decoded = JSON.parse(key.slice(2));
+        var decodedKey = key.slice(2);
+        if (CFG.escapeNULForSQLiteStatements === false) {
+          decodedKey = decodedKey.replaceAll('\0', String.raw(_templateObject2 || (_templateObject2 = _taggedTemplateLiteral(["\0"], ["\\u0000"]))));
+        }
+        var decoded = JSON.parse(decodedKey);
         decoded.pop(); // remove the extra item
         for (var i = 0; i < decoded.length; i++) {
           var item = decoded[i];
@@ -4687,6 +4785,7 @@
    *   },
    *   __requestsFinished: boolean,
    *   __transFinishedCb: (err: boolean, cb: ((bool?: boolean) => void)) => void,
+   *   __callTransFinishedCb: (err: boolean, cb: ((bool?: boolean) => void)) => void,
    *   __transactionEndCallback: () => void,
    *   __transactionFinished: boolean,
    *   __completed: boolean,
@@ -4796,6 +4895,35 @@
   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) {
+    var me = this;
+    if (me.__transFinishedCb === IDBTransaction.prototype.__transFinishedCb) {
+      setTimeout(function () {
+        me.__callTransFinishedCb(err, cb);
+      }, 0);
+      return;
+    }
+    me.__transFinishedCb(err, cb);
+  };
   /**
    * @this {IDBTransactionFull}
    * @returns {void}
@@ -4855,7 +4983,7 @@
           me.__abortTransaction(createDOMException('AbortError', 'A request was aborted (in user handler after success).'));
           return;
         }
-        executeNextRequest();
+        runContinuationSafely(executeNextRequest);
       }
 
       /**
@@ -4930,7 +5058,9 @@
           try {
             q = me.__requests[i];
             if (!q.req) {
-              q.op(tx, q.args, executeNextRequest, error);
+              q.op(tx, q.args, function () {
+                return runContinuationSafely(executeNextRequest);
+              }, error);
               return;
             }
             if (q.req.__done) {
@@ -7626,7 +7756,7 @@
                   reject(err);
                 });
               }));
-              SyncPromise.all(indexCreations).then(finish, /** @type {(reason: any) => PromiseLike<never>} */
+              SyncPromise.all(indexCreations).then(finish).catch(/** @type {(reason: any) => PromiseLike<never>} */
               error).catch(function (err) {
                 console.log('Index rename error');
                 throw err;
@@ -10010,7 +10140,7 @@
                   /** @type {import('./IDBDatabase.js').IDBDatabaseFull} */
                   req.__result.__versionTransaction = null;
                   sysdbFinishedCb(systx, false, function () {
-                    req.transaction.__transFinishedCb(false, function () {
+                    req.transaction.__callTransFinishedCb(false, function () {
                       ev.complete();
                       req.__transaction = null;
                     });
@@ -10121,6 +10251,13 @@
     function openDB(oldVersion) {
       /** @type {DatabaseFull} */
       var 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 {
@@ -10132,9 +10269,6 @@
           websqlDBCache[name][version] = db;
         }
       }
-      if (version === undefined) {
-        version = oldVersion || 1;
-      }
       if (oldVersion > version) {
         var err = createDOMException('VersionError', 'An attempt was made to open a database using a lower version than the existing version.', version);
         if (useDatabaseCache) {
@@ -10302,7 +10436,6 @@
             version = _data$rows$item.version;
             var openConnections = me.__connections[name] || [];
             triggerAnyVersionChangeAndBlockedEvents(openConnections, req, version, null).then(function () {
-              // eslint-disable-line promise/catch-or-return -- Sync promise
               // 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
@@ -10331,7 +10464,7 @@
               });
               return undefined;
               // @ts-expect-error It's ok
-            }, dbError);
+            }).catch(dbError);
             return undefined;
           }, dbError);
         });
@@ -10513,6 +10646,9 @@
    *   __unique: boolean,
    *   __sqlDirection: "DESC"|"ASC",
    *   __matchedKeys: {[key: string]: true},
+   *   __continuationKey: import('./Key.js').Key|undefined,
+   *   __continuationPrimaryKey: import('./Key.js').Key|undefined,
+   *   __multiEntryExhausted: boolean,
    *   __invalidateCache: () => void
    * }} IDBCursorFull
    */
@@ -10586,6 +10722,9 @@
     this.__valueDecoder = this.__keyOnly ? Key : Sca;
     this.__count = count;
     this.__prefetchedIndex = -1;
+    this.__continuationKey = undefined;
+    this.__continuationPrimaryKey = undefined;
+    this.__multiEntryExhausted = false;
     this.__multiEntryIndex = this.__indexSource ? 'multiEntry' in source && source.multiEntry : false;
     this.__unique = this.direction.includes('unique');
     this.__sqlDirection = ['prev', 'prevunique'].includes(this.direction) ? 'DESC' : 'ASC';
@@ -10749,73 +10888,97 @@
    * @param {SQLTransaction} tx
    * @param {KeySuccess} success
    * @param {FindError} error
-   * @param {Integer|undefined} recordsToLoad
+   * @param {Integer} [recordsToLoad]
    * @this {IDBCursorFull}
    * @returns {void}
    */
-  IDBCursor.prototype.__findMultiEntry = function (key, primaryKey, tx, success, error, recordsToLoad) {
+  IDBCursor.prototype.__findMultiEntry = function (key, primaryKey, tx, success, error) {
+    var recordsToLoad = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : 1;
     var me = this;
-    if (me.__prefetchedData && me.__prefetchedData.length === me.__prefetchedIndex) {
+    if (me.__multiEntryExhausted) {
       if (CFG.DEBUG) {
-        console.log('Reached end of multiEntry cursor');
+        console.log('[multiEntry] Reached end of multiEntry cursor (already exhausted)');
       }
       success(undefined, undefined, undefined);
       return;
     }
     var quotedKeyColumnName = sqlQuote(me.__keyColumnName);
-    var sql = ['SELECT * FROM', escapeStoreNameForSQL(me.__store.__currentName)];
-    /** @type {string[]} */
-    var sqlValues = [];
-    sql.push('WHERE', quotedKeyColumnName, 'NOT NULL');
-    if (me.__range && me.__range.lower !== undefined && Array.isArray(me.__range.upper)) {
-      if (me.__range.upper.indexOf(me.__range.lower) === 0) {
-        sql.push('AND', quotedKeyColumnName, "LIKE ? ESCAPE '^'");
-        sqlValues.push('%' + sqlLIKEEscape(/** @type {string} */me.__range.__lowerCached.slice(0, -1)) + '%');
-      }
-    }
+    var quotedKey = sqlQuote('key');
 
     // Determine the ORDER BY direction based on the cursor.
     var direction = me.__sqlDirection;
     var op = direction === 'ASC' ? '>' : '<';
-    var quotedKey = sqlQuote('key');
-    if (primaryKey !== undefined) {
-      sql.push('AND', quotedKey, op + '= ?');
-      // Key.convertValueToKey(primaryKey); // Already checked by `continuePrimaryKey`
-      sqlValues.push(/** @type {string} */_encode(primaryKey));
-    }
-    if (key !== undefined) {
-      sql.push('AND', quotedKeyColumnName, op + '= ?');
-      // Key.convertValueToKey(key); // Already checked by `continue` or `continuePrimaryKey`
-      sqlValues.push(/** @type {string} */_encode(key));
-    } else if (me.__key !== undefined) {
-      sql.push('AND', quotedKeyColumnName, op + ' ?');
-      // Key.convertValueToKey(me.__key); // Already checked when entered
-      sqlValues.push(/** @type {string} */_encode(me.__key));
-    }
-    if (!me.__count) {
-      // 1. Sort by key
-      sql.push('ORDER BY', quotedKeyColumnName, direction);
 
-      // 2. Sort by primaryKey (if defined and not unique)
-      if (!me.__unique && me.__keyColumnName !== 'key') {
-        // Avoid adding 'key' twice
-        sql.push(',', sqlQuote('key'), direction);
+    /**
+     * Runs (and, if a batch of underlying rows produces no matching
+     * multi-entry values, repeatedly re-runs) the query for the next batch
+     * of underlying rows, advancing `me.__continuationKey`/
+     * `me.__continuationPrimaryKey` (tracking the last *physical* row
+     * scanned) each time, until either some matches are found or the
+     * underlying table is exhausted.
+     * @returns {void}
+     */
+    function runQuery() {
+      var sql = ['SELECT * FROM', escapeStoreNameForSQL(me.__store.__currentName)];
+      /** @type {string[]} */
+      var sqlValues = [];
+      sql.push('WHERE', quotedKeyColumnName, 'NOT NULL');
+      if (me.__range && me.__range.lower !== undefined && Array.isArray(me.__range.upper)) {
+        if (me.__range.upper.indexOf(me.__range.lower) === 0) {
+          sql.push('AND', quotedKeyColumnName, "LIKE ? ESCAPE '^'");
+          sqlValues.push('%' + sqlLIKEEscape(/** @type {string} */me.__range.__lowerCached.slice(0, -1)) + '%');
+        }
+      }
+      if (primaryKey !== undefined) {
+        sql.push('AND', quotedKey, op + '= ?');
+        // Key.convertValueToKey(primaryKey); // Already checked by `continuePrimaryKey`
+        sqlValues.push(/** @type {string} */_encode(primaryKey));
       }
-
-      // 3. Sort by position (if defined)
-
-      if (!me.__unique && me.__indexSource) {
-        // 4. Sort by object store position (if defined and not unique)
-        sql.push(',', sqlQuote(me.__valueColumnName), direction);
+      if (key !== undefined) {
+        sql.push('AND', quotedKeyColumnName, op + '= ?');
+        // Key.convertValueToKey(key); // Already checked by `continue` or `continuePrimaryKey`
+        sqlValues.push(/** @type {string} */_encode(key));
+      } else if (me.__continuationKey !== undefined) {
+        // Resume from the last underlying (physical) row we scanned, not
+        // from the last *matching* multi-entry value (which lives in a
+        // different key-space than the raw index column and cannot be
+        // reliably compared against it, e.g. for array index keys).
+        sql.push('AND (', quotedKeyColumnName, op, '?', 'OR (', quotedKeyColumnName, '= ?', 'AND', quotedKey, op, '?))');
+        var encodedContinuationKey = /** @type {string} */
+        _encode(me.__continuationKey, true);
+        sqlValues.push(encodedContinuationKey, encodedContinuationKey, /** @type {string} */_encode(me.__continuationPrimaryKey));
+      }
+      if (!me.__count) {
+        // 1. Sort by key
+        sql.push('ORDER BY', quotedKeyColumnName, direction);
+
+        // 2. Sort by primaryKey (if defined and not unique)
+        if (!me.__unique && me.__keyColumnName !== 'key') {
+          // Avoid adding 'key' twice
+          sql.push(',', sqlQuote('key'), direction);
+        }
+
+        // 3. Sort by position (if defined)
+
+        if (!me.__unique && me.__indexSource) {
+          // 4. Sort by object store position (if defined and not unique)
+          sql.push(',', sqlQuote(me.__valueColumnName), direction);
+        }
+        sql.push('LIMIT', String(recordsToLoad));
+      }
+      var sqlStr = sql.join(' ');
+      if (CFG.DEBUG) {
+        console.log('[multiEntry] query', sqlStr, sqlValues);
       }
-      sql.push('LIMIT', String(recordsToLoad));
-    }
-    var sqlStr = sql.join(' ');
-    if (CFG.DEBUG) {
-      console.log(sqlStr, sqlValues);
-    }
-    tx.executeSql(sqlStr, sqlValues, function (tx, data) {
-      if (data.rows.length > 0) {
+      tx.executeSql(sqlStr, sqlValues, function (tx, data) {
+        if (data.rows.length === 0) {
+          me.__multiEntryExhausted = true;
+          if (CFG.DEBUG) {
+            console.log('[multiEntry] Reached end of multiEntry cursor (no more rows)');
+          }
+          success(undefined, undefined, undefined);
+          return;
+        }
         if (me.__count) {
           // Avoid caching and other processing below
           var ct = 0;
@@ -10828,6 +10991,16 @@
           success(undefined, ct, undefined);
           return;
         }
+
+        // Track how far we've physically scanned, regardless of whether
+        // this batch produced any matches, so the next batch (if any)
+        // resumes after this one instead of re-scanning or stopping early.
+        var lastRawRow = data.rows.item(data.rows.length - 1);
+        me.__continuationKey = _decode(lastRawRow[me.__keyColumnName], true);
+        me.__continuationPrimaryKey = _decode(lastRawRow.key);
+        if (data.rows.length < recordsToLoad) {
+          me.__multiEntryExhausted = true;
+        }
         var rows = [];
         for (var _i = 0; _i < data.rows.length; _i++) {
           var _rowItem = data.rows.item(_i);
@@ -10854,6 +11027,20 @@
             _iterator.f();
           }
         }
+        if (rows.length === 0) {
+          if (me.__multiEntryExhausted) {
+            if (CFG.DEBUG) {
+              console.log('[multiEntry] Reached end of multiEntry cursor (last batch had no matches)');
+            }
+            success(undefined, undefined, undefined);
+            return;
+          }
+          if (CFG.DEBUG) {
+            console.log('[multiEntry] batch had no matches; fetching next batch');
+          }
+          runQuery();
+          return;
+        }
         var reverse = me.direction.indexOf('prev') === 0;
         rows.sort(function (a, b) {
           if (a.matchingKey.replaceAll(leftBracketRegex, 'z') < b.matchingKey.replaceAll(leftBracketRegex, 'z')) {
@@ -10870,47 +11057,31 @@
           }
           return 0;
         });
-        if (rows.length > 1) {
-          me.__prefetchedIndex = 0;
-          me.__prefetchedData = {
-            data: rows,
-            length: rows.length,
-            /**
-             * @param {Integer} index
-             * @returns {RowItemNonNull}
-             */
-            item: function item(index) {
-              return this.data[index];
-            }
-          };
-          if (CFG.DEBUG) {
-            console.log('Preloaded ' + me.__prefetchedData.length + ' records for multiEntry cursor');
-          }
-          me.__decode(rows[0], success);
-        } else if (rows.length === 1) {
-          if (CFG.DEBUG) {
-            console.log('Reached end of multiEntry cursor');
-          }
-          me.__decode(rows[0], success);
-        } else {
-          if (CFG.DEBUG) {
-            console.log('Reached end of multiEntry cursor');
+        me.__prefetchedIndex = 0;
+        me.__prefetchedData = {
+          data: rows,
+          length: rows.length,
+          /**
+           * @param {Integer} index
+           * @returns {RowItemNonNull}
+           */
+          item: function item(index) {
+            return this.data[index];
           }
-          success(undefined, undefined, undefined);
+        };
+        if (CFG.DEBUG) {
+          console.log('[multiEntry] Preloaded ' + me.__prefetchedData.length + ' records for multiEntry cursor');
         }
-      } else {
+        me.__decode(rows[0], success);
+      }, function (tx, err) {
         if (CFG.DEBUG) {
-          console.log('Reached end of multiEntry cursor');
+          console.log('[multiEntry] Could not execute Cursor.continue', sqlStr, sqlValues);
         }
-        success(undefined, undefined, undefined);
-      }
-    }, function (tx, err) {
-      if (CFG.DEBUG) {
-        console.log('Could not execute Cursor.continue', sqlStr, sqlValues);
-      }
-      error(err);
-      return false;
-    });
+        error(err);
+        return false;
+      });
+    }
+    runQuery();
   };
 
   /**
@@ -11019,6 +11190,7 @@
   IDBCursor.prototype.__invalidateCache = function () {
     // @ts-expect-error Why is this not being found?
     this.__prefetchedData = null;
+    this.__multiEntryExhausted = false;
   };
 
   /**
@@ -11074,8 +11246,8 @@
             me.__advanceCount--;
             me.__key = k;
             me.__continue(undefined, true);
-            /** @type {() => void} */
-            executeNextRequest(); // We don't call success yet but do need to advance the transaction queue
+            // We don't call success yet but do need to advance the transaction queue
+            runContinuationSafely(/** @type {() => void} */executeNextRequest);
             return;
           }
           me.__advanceCount = undefined;
@@ -11097,11 +11269,15 @@
                 return;
               }
               // @ts-expect-error Todo: Our bug to fix
-              cursorContinue(tx, args, success, error);
+              runContinuationSafely(function () {
+                return cursorContinue(tx, args, success, error);
+              });
             }
             if (me.__unique && !me.__multiEntryIndex && encKey === _encode(me.key, me.__multiEntryIndex)) {
               // @ts-expect-error Todo: Our bug to fix
-              cursorContinue(tx, args, success, error);
+              runContinuationSafely(function () {
+                return cursorContinue(tx, args, success, error);
+              });
               return;
             }
             checkKey();