@framers/sql-storage-adapter 0.7.1 → 0.7.3

package/dist/cjs/adapters/indexedDbAdapter.js

@@ -0,0 +1,993 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var indexedDbAdapter_exports = {};
+__export(indexedDbAdapter_exports, {
+  IndexedDbAdapter: () => IndexedDbAdapter,
+  IndexedDbConflictError: () => IndexedDbConflictError
+});
+module.exports = __toCommonJS(indexedDbAdapter_exports);
+var import_sql = __toESM(require("sql.js"));
+var import_parameterUtils = require("../shared/parameterUtils.js");
+var import_sqlPlaceholders = require("../shared/sqlPlaceholders.js");
+var import_serializedTransaction = require("../shared/serializedTransaction.js");
+var import_connectionGate = require("../shared/connectionGate.js");
+var import_segment = require("../shared/segment.js");
+const LONG_WAIT_MS = 1e4;
+const IMAGE_KEY = "db";
+const STAMP_KEY = "db:stamp";
+const MAX_CONFLICT_RETRIES = 50;
+const CONNECTION_PRAGMAS = [
+  "foreign_keys",
+  "recursive_triggers",
+  "automatic_index",
+  "cache_size",
+  "cache_spill",
+  "cell_size_check",
+  "ignore_check_constraints",
+  "legacy_alter_table",
+  "query_only",
+  "reverse_unordered_selects",
+  "secure_delete",
+  "synchronous",
+  "temp_store",
+  "trusted_schema",
+  "busy_timeout"
+];
+let globalSQL = null;
+let globalSQLPromise = null;
+async function getGlobalSQL(config) {
+  if (globalSQL) {
+    return globalSQL;
+  }
+  if (globalSQLPromise) {
+    return globalSQLPromise;
+  }
+  globalSQLPromise = (0, import_sql.default)(config).then((sql) => {
+    globalSQL = sql;
+    return sql;
+  });
+  return globalSQLPromise;
+}
+class IndexedDbConflictError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IndexedDbConflictError";
+  }
+}
+const DB_VERSION = 1;
+const firstKeyword = (statement) => {
+  const rest = statement.replace(/^(?:\s+|--[^\n]*(?:\n|$)|\/\*[\s\S]*?\*\/)*/, "");
+  return (/^[A-Za-z]+/.exec(rest)?.[0] ?? "").toUpperCase();
+};
+class IndexedDbAdapter {
+  /** @throws {Error} When `options.segment` is not a name a segment can take. */
+  constructor(options = {}) {
+    this.kind = "indexeddb";
+    this.capabilities = /* @__PURE__ */ new Set(["transactions", "persistence", "json", "prepared"]);
+    this.SQL = null;
+    this.db = null;
+    this.idb = null;
+    this.saveTimer = null;
+    this.writeGeneration = 0;
+    this.savedGeneration = 0;
+    this.saving = null;
+    this.savingGeneration = 0;
+    this.saveFailureReported = false;
+    this.opening = null;
+    this.closing = false;
+    this.closeRun = null;
+    this.longWaitReported = false;
+    this.lockWaitReported = false;
+    this.loadedStamp = null;
+    this.stampCount = 0;
+    this.pragmaDefaults = /* @__PURE__ */ new Map();
+    this.locks = void 0;
+    this.runCoordinatedInTurn = (0, import_serializedTransaction.createSerializedTransactionRunner)();
+    this.runSerializedTransaction = (0, import_serializedTransaction.createSerializedTransactionRunner)();
+    this.gate = (0, import_connectionGate.createConnectionGate)(null, { withoutContext: "wait" });
+    this.longWait = {
+      afterMs: LONG_WAIT_MS,
+      onLongWait: () => this.reportLongWait()
+    };
+    this.dbName = (0, import_segment.segmentName)(options.dbName || "app-db", options.segment);
+    this.storeName = options.storeName || "sqliteDb";
+    this.autoSave = options.autoSave ?? true;
+    this.saveIntervalMs = options.saveIntervalMs || 5e3;
+    this.sqlJsConfig = options.sqlJsConfig || {};
+    this.crossTab = options.crossTab === true ? {} : typeof options.crossTab === "object" && options.crossTab !== null ? options.crossTab : null;
+    this.durability = this.crossTab ? "commit" : options.durability ?? "interval";
+  }
+  /** The name of the Web Lock that coordinates the tabs on this database. */
+  get lockName() {
+    return `@framers/sql-storage-adapter:indexeddb:${this.dbName}:${this.storeName}`;
+  }
+  /**
+   * Opens IndexedDB and initializes sql.js database.
+   * Loads existing database from IndexedDB if present.
+   *
+   * Uses a global sql.js singleton to prevent race conditions when
+   * multiple adapters (e.g., fabric_codex_db and quarry-codex-local)
+   * are initialized simultaneously. Two calls at once open once.
+   */
+  open(options) {
+    if (this.db) {
+      return Promise.resolve();
+    }
+    if (!this.opening) {
+      this.foreignKeys = options?.foreignKeys;
+      this.opening = this.openNow().finally(() => {
+        this.opening = null;
+      });
+    }
+    return this.opening;
+  }
+  async openNow() {
+    this.SQL = await getGlobalSQL(this.sqlJsConfig);
+    this.idb = await this.openIndexedDbWithRetry();
+    const stored = await this.loadFromIndexedDb();
+    const db = stored.image ? new this.SQL.Database(stored.image) : new this.SQL.Database();
+    this.pragmaDefaults = readPragmas(db);
+    this.db = db;
+    this.loadedStamp = stored.stamp;
+    this.applyConnectionSettings();
+    if (this.crossTab) {
+      this.locks = this.resolveLocks(this.crossTab);
+    } else if (this.autoSave) {
+      this.startAutoSave();
+    }
+  }
+  /** The lock manager crossTab uses, or null for the version stamp alone. */
+  resolveLocks(options) {
+    if (options.locks !== void 0) {
+      return options.locks;
+    }
+    const scope = globalThis;
+    const locks = scope.navigator?.locks;
+    if (locks && typeof locks.request === "function") {
+      return locks;
+    }
+    console.warn(`[IndexedDbAdapter] Web Locks are not available here, so "${this.dbName}" coordinates tabs by its version stamp alone: a statement another tab saved over runs again, and a transaction() another tab saved over fails with IndexedDbConflictError.`);
+    return null;
+  }
+  /**
+   * Executes a SQL statement that doesn't return rows (INSERT, UPDATE, DELETE, CREATE, etc.).
+   * @param statement SQL statement with ? or :name placeholders
+   * @param parameters Positional array or named object
+   * @returns Result with changes count and last insert row ID
+   */
+  async run(statement, parameters) {
+    if (this.crossTab) {
+      return this.coordinatedStatement(() => this.runNow(statement, parameters));
+    }
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.stored(this.runNow(statement, parameters)), void 0, this.longWait);
+  }
+  runNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    this.ensureOpen();
+    const stmt = this.db.prepare(statement);
+    try {
+      const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+      if (named) {
+        stmt.bind((0, import_parameterUtils.expandNamedParameters)(named));
+      } else if (positional) {
+        stmt.bind(positional);
+      }
+      stmt.step();
+      const rowIdResult = this.db.exec("SELECT last_insert_rowid() AS id");
+      const rawRowId = rowIdResult[0]?.values?.[0]?.[0];
+      const lastInsertRowid = this.normaliseRowId(rawRowId);
+      this.writeGeneration += 1;
+      return {
+        changes: this.db.getRowsModified(),
+        lastInsertRowid
+      };
+    } finally {
+      stmt.free();
+    }
+  }
+  /**
+   * Executes a SQL query and returns the first row.
+   * @param statement SELECT statement
+   * @param parameters Query parameters
+   * @returns First row as object or null if no results
+   */
+  async get(statement, parameters) {
+    const rows = await this.all(statement, parameters);
+    return rows.length > 0 ? rows[0] : null;
+  }
+  /**
+   * Executes a SQL query and returns all matching rows. A statement that
+   * writes (`INSERT ... RETURNING`) is saved like a `run()`.
+   * @param statement SELECT statement
+   * @param parameters Query parameters
+   * @returns Array of result rows as objects
+   */
+  async all(statement, parameters) {
+    if (this.crossTab) {
+      return this.coordinatedStatement(() => this.allNow(statement, parameters));
+    }
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => {
+      const before = this.writeGeneration;
+      const rows = this.allNow(statement, parameters);
+      return this.writeGeneration === before ? rows : this.stored(rows);
+    }, void 0, this.longWait);
+  }
+  allNow(statement, parameters) {
+    ({ statement, parameters } = (0, import_sqlPlaceholders.toSqliteStatement)(statement, parameters));
+    this.ensureOpen();
+    const keyword = firstKeyword(statement);
+    const reads = keyword === "SELECT" || keyword === "EXPLAIN" || keyword === "VALUES";
+    const mayWrite = keyword === "WITH" || keyword === "PRAGMA";
+    const changesBefore = mayWrite ? this.totalChanges() : 0;
+    const stmt = this.db.prepare(statement);
+    try {
+      const { named, positional } = (0, import_parameterUtils.normaliseParameters)(parameters);
+      if (named) {
+        stmt.bind((0, import_parameterUtils.expandNamedParameters)(named));
+      } else if (positional) {
+        stmt.bind(positional);
+      }
+      const results = [];
+      const columnNames = stmt.getColumnNames();
+      while (stmt.step()) {
+        const row = stmt.get();
+        const obj = {};
+        columnNames.forEach((col, idx) => {
+          obj[col] = row[idx];
+        });
+        results.push(obj);
+      }
+      if (!reads && (!mayWrite || this.totalChanges() !== changesBefore)) {
+        this.writeGeneration += 1;
+      }
+      return results;
+    } finally {
+      stmt.free();
+    }
+  }
+  /** The rows changed on this connection since it opened. */
+  totalChanges() {
+    return Number(this.db.exec("SELECT total_changes()")[0]?.values?.[0]?.[0] ?? 0);
+  }
+  /**
+   * Executes a script containing multiple SQL statements.
+   */
+  async exec(script) {
+    if (this.crossTab) {
+      return this.coordinatedStatement(() => this.execNow(script));
+    }
+    return (0, import_connectionGate.whenAdmitted)(this.gate, () => this.stored(this.execNow(script)), void 0, this.longWait);
+  }
+  execNow(script) {
+    this.ensureOpen();
+    try {
+      this.db.exec(script);
+    } finally {
+      this.writeGeneration += 1;
+    }
+  }
+  /**
+   * With `durability: 'commit'`, resolves with `result` once the write that
+   * produced it is stored; otherwise with `result` at once.
+   */
+  stored(result) {
+    if (this.durability !== "commit") {
+      return result;
+    }
+    return this.saveThrough(this.writeGeneration).then(() => result);
+  }
+  /**
+   * Executes a callback within a database transaction.
+   *
+   * 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. With
+   * `durability: 'commit'` the transaction resolves once it is stored.
+   */
+  async transaction(fn) {
+    this.ensureOpen();
+    if (this.crossTab) {
+      return this.coordinatedTransaction(fn);
+    }
+    const queued = setTimeout(() => this.reportLongWait(), LONG_WAIT_MS);
+    return this.runSerializedTransaction(async () => {
+      clearTimeout(queued);
+      const result = await this.transactionNow(fn);
+      if (this.durability === "commit") {
+        await this.saveThrough(this.writeGeneration);
+      }
+      return result;
+    });
+  }
+  /** Runs one transaction: BEGIN, the callback through its handle, COMMIT or ROLLBACK. */
+  transactionNow(fn) {
+    return this.gate.hold(async (token) => {
+      this.ensureOpen();
+      this.db.run("BEGIN TRANSACTION");
+      const transactionAdapter = (0, import_serializedTransaction.createSharedConnectionTransactionAdapter)(this.handleStatements(token));
+      try {
+        const result = await fn(transactionAdapter);
+        this.ensureOpen();
+        this.db.run("COMMIT");
+        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) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.runNow(statement, parameters), token),
+      get: async (statement, parameters) => {
+        const rows = await (0, import_connectionGate.whenAdmitted)(this.gate, () => this.allNow(statement, parameters), token);
+        return rows.length > 0 ? rows[0] : null;
+      },
+      all: (statement, parameters) => (0, import_connectionGate.whenAdmitted)(this.gate, () => this.allNow(statement, parameters), token),
+      exec: (script) => (0, import_connectionGate.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 {
+      this.db.run("ROLLBACK");
+    } catch {
+    }
+  }
+  /**
+   * 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. With
+   * `crossTab` it is refused: use transaction().
+   */
+  async beginTransaction() {
+    await this.run("BEGIN");
+  }
+  /**
+   * Commits the current transaction.
+   */
+  async commit() {
+    await this.run("COMMIT");
+  }
+  /**
+   * Rolls back the current transaction.
+   */
+  async rollback() {
+    await this.run("ROLLBACK");
+  }
+  /**
+   * Stores every write made so far in IndexedDB. A `transaction()` that is
+   * open is waited for and stored with the rest; a transaction a caller began
+   * with `BEGIN` cannot be stored without ending it, so flush() rejects while
+   * one is open. Resolves at once when nothing is waiting to be saved.
+   */
+  async flush() {
+    this.ensureOpen();
+    if (this.crossTab) {
+      await this.coordinatedStatement(() => void 0);
+      return;
+    }
+    const target = this.writeGeneration;
+    while (this.savedGeneration < target && this.db && this.idb) {
+      if (this.saving) {
+        const covering = this.savingGeneration >= target;
+        try {
+          await this.saving;
+        } catch (error) {
+          if (covering)
+            throw error;
+        }
+        continue;
+      }
+      if (this.gate.openToken() !== null) {
+        await this.gate.ended();
+        continue;
+      }
+      if (this.inTransaction()) {
+        throw new Error(`IndexedDbAdapter: flush() cannot store "${this.dbName}" while a transaction begun with BEGIN is open: sql.js's export would end it. COMMIT or ROLLBACK it first.`);
+      }
+      await this.startSave();
+    }
+  }
+  /**
+   * Closes the database and saves its committed state to IndexedDB.
+   *
+   * 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() {
+    if (!this.closeRun) {
+      this.closeRun = this.closeNow().finally(() => {
+        this.closeRun = null;
+      });
+    }
+    return this.closeRun;
+  }
+  async closeNow() {
+    if (this.opening) {
+      await this.opening.catch(() => void 0);
+    }
+    if (this.saveTimer) {
+      clearInterval(this.saveTimer);
+      this.saveTimer = null;
+    }
+    if (this.db) {
+      this.closing = true;
+      try {
+        if (this.inTransaction()) {
+          this.rollbackQuietly();
+        }
+        if (this.crossTab) {
+          await this.withCoordination(async () => {
+            if (this.db && this.hasUnsavedWrites()) {
+              await this.saveIfStampIs(this.loadedStamp);
+            }
+          });
+        } else {
+          await this.settleSave();
+          if (this.hasUnsavedWrites()) {
+            await this.startSave();
+          }
+        }
+        this.db?.close();
+        this.db = null;
+      } finally {
+        this.closing = false;
+      }
+    }
+    if (this.idb) {
+      this.idb.close();
+      this.idb = null;
+    }
+  }
+  /**
+   * Exports the database as a Uint8Array (SQLite file format).
+   * Can be downloaded or stored externally. With `crossTab` it is this tab's
+   * image, which another tab's save can have overtaken.
+   *
+   * Throws while a transaction is open: sql.js's export closes and reopens the
+   * connection, which would end the transaction.
+   * @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.exportImage();
+  }
+  /**
+   * Applies the connection settings open() was asked for. sql.js loses them
+   * whenever export() reopens the connection; a save, an export, an import
+   * and a reload set them again with the other settings a caller changed
+   * (exportImage, replaceDatabase).
+   */
+  applyConnectionSettings() {
+    if (this.foreignKeys !== void 0) {
+      this.db.run(`PRAGMA foreign_keys = ${this.foreignKeys ? "ON" : "OFF"};`);
+    }
+  }
+  /**
+   * Imports a database from a Uint8Array (SQLite file).
+   * Replaces the current database once any open transaction() has ended, and
+   * saves it to IndexedDB before it resolves; with `crossTab`, in place of
+   * what every tab stored. Bytes that are not a SQLite database are refused,
+   * and the adapter keeps its database.
+   * @param data SQLite database file
+   */
+  async importDatabase(data) {
+    this.ensureOpen();
+    if (this.crossTab) {
+      await this.withCoordination(async () => {
+        this.swapIn(data);
+        await this.saveIfStampIs(void 0);
+      });
+      return;
+    }
+    await (0, import_connectionGate.whenAdmitted)(this.gate, () => {
+      this.swapIn(data);
+      return this.startSave();
+    }, void 0, this.longWait);
+  }
+  /** Replaces the database with an image, once sql.js has read it as a SQLite database. */
+  swapIn(data) {
+    this.ensureOpen();
+    const imported = new this.SQL.Database(data);
+    try {
+      imported.exec("SELECT count(*) FROM sqlite_master");
+    } catch (error) {
+      imported.close();
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new Error(`IndexedDbAdapter: the image to import is not a SQLite database that sql.js can read (${reason}).`);
+    }
+    this.replaceDatabase(imported);
+    this.writeGeneration += 1;
+  }
+  /** Puts `next` in place of the database, with the connection settings the current one has. */
+  replaceDatabase(next) {
+    const settings = this.changedPragmas();
+    this.db.close();
+    this.db = next;
+    this.applyPragmas(settings);
+  }
+  // ==========================================================================
+  // Across tabs
+  // ==========================================================================
+  /**
+   * Runs `work` with this tab holding the database: under the Web Lock, or,
+   * without Web Locks, after this adapter's earlier coordinated work.
+   */
+  withCoordination(work) {
+    const waiting = setTimeout(() => this.reportLockWait(), LONG_WAIT_MS);
+    const start = () => {
+      clearTimeout(waiting);
+      return work();
+    };
+    const locks = this.locks;
+    const held = locks ? locks.request(this.lockName, { mode: "exclusive" }, start) : this.runCoordinatedInTurn(start);
+    return held.finally(() => clearTimeout(waiting));
+  }
+  /**
+   * One statement across tabs: on the newest stored image, and stored before
+   * it resolves. Without Web Locks another tab can save between the load and
+   * the save; the statement then runs again on that tab's image.
+   */
+  coordinatedStatement(statement) {
+    return this.withCoordination(async () => {
+      for (let attempt = 1; ; attempt += 1) {
+        this.ensureOpen();
+        await this.syncFromStore();
+        const result = statement();
+        if (this.inTransaction()) {
+          this.rollbackQuietly();
+          throw new Error(`IndexedDbAdapter: "${this.dbName}" coordinates tabs, so a transaction begun with BEGIN through run() or exec() cannot be held open; it was rolled back. Use transaction().`);
+        }
+        if (!this.hasUnsavedWrites() || await this.saveIfStampIs(this.loadedStamp)) {
+          return result;
+        }
+        if (attempt >= MAX_CONFLICT_RETRIES) {
+          await this.syncFromStore();
+          throw new IndexedDbConflictError(`IndexedDbAdapter: other tabs saved "${this.dbName}" before each of ${attempt} attempts to store a statement; nothing of it is stored.`);
+        }
+        await this.syncFromStore();
+        await new Promise((resolve) => setTimeout(resolve, Math.random() * 4 * attempt));
+      }
+    });
+  }
+  /**
+   * One transaction across tabs: on the newest stored image, and stored before
+   * it resolves. Without Web Locks another tab can save while the callback
+   * runs; the transaction is then refused, nothing of it is stored, and the
+   * other tab's image is loaded for the caller to run it again.
+   */
+  coordinatedTransaction(fn) {
+    return this.withCoordination(async () => {
+      this.ensureOpen();
+      await this.syncFromStore();
+      const result = await this.runSerializedTransaction(() => this.transactionNow(fn));
+      if (this.hasUnsavedWrites() && !await this.saveIfStampIs(this.loadedStamp)) {
+        await this.syncFromStore();
+        throw new IndexedDbConflictError(`IndexedDbAdapter: another tab saved "${this.dbName}" while this transaction ran, so nothing of it is stored. That tab's writes are loaded; run the transaction again.`);
+      }
+      return result;
+    });
+  }
+  /** Loads the stored image when another tab (or adapter) has saved since this one loaded or saved. */
+  async syncFromStore() {
+    const stored = await this.readIfChanged(this.loadedStamp);
+    if (!stored || !this.db) {
+      return;
+    }
+    this.replaceDatabase(stored.image ? new this.SQL.Database(stored.image) : new this.SQL.Database());
+    this.loadedStamp = stored.stamp;
+    this.savedGeneration = this.writeGeneration;
+  }
+  /** Reads the stored stamp, and the image with it when the stamp is not `known`; null when it is. */
+  readIfChanged(known) {
+    return this.withTransactionRetry(() => new Promise((resolve, reject) => {
+      const tx = this.idb.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      let answer = null;
+      const stampRequest = store.get(STAMP_KEY);
+      stampRequest.onsuccess = () => {
+        const stamp = typeof stampRequest.result === "string" ? stampRequest.result : null;
+        if (stamp === known)
+          return;
+        const imageRequest = store.get(IMAGE_KEY);
+        imageRequest.onsuccess = () => {
+          answer = { image: imageRequest.result ?? null, stamp };
+        };
+      };
+      tx.oncomplete = () => resolve(answer);
+      tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: reading "${this.dbName}" was aborted.`));
+    }));
+  }
+  /**
+   * Stores the image when the stored stamp is still `expected`, in one
+   * IndexedDB transaction, so no other tab's save lands between the check and
+   * the write. `undefined` stores it whatever the stamp is. Resolves with
+   * whether it stored the image.
+   */
+  async saveIfStampIs(expected) {
+    const generation = this.writeGeneration;
+    const image = this.exportImage();
+    const stamp = this.nextStamp();
+    const stored = await this.withTransactionRetry(() => new Promise((resolve, reject) => {
+      const tx = this.idb.transaction(this.storeName, "readwrite");
+      const store = tx.objectStore(this.storeName);
+      let wrote = false;
+      const write = () => {
+        store.put(image, IMAGE_KEY);
+        store.put(stamp, STAMP_KEY);
+        wrote = true;
+      };
+      if (expected === void 0) {
+        write();
+      } else {
+        const current = store.get(STAMP_KEY);
+        current.onsuccess = () => {
+          const found = typeof current.result === "string" ? current.result : null;
+          if (found === expected)
+            write();
+        };
+      }
+      tx.oncomplete = () => resolve(wrote);
+      tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: saving "${this.dbName}" to IndexedDB was aborted.`));
+    }));
+    if (stored) {
+      this.loadedStamp = stamp;
+      this.savedGeneration = Math.max(this.savedGeneration, generation);
+    }
+    return stored;
+  }
+  /** A stamp no other save of this or another tab writes. */
+  nextStamp() {
+    this.stampCount += 1;
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}-${this.stampCount}`;
+  }
+  // ==========================================================================
+  // Saving
+  // ==========================================================================
+  /**
+   * Exports the database for a save, keeping the connection settings a
+   * caller made: sql.js's export() closes the connection and opens it again.
+   */
+  exportImage() {
+    const settings = this.changedPragmas();
+    const image = this.db.export();
+    this.applyPragmas(settings);
+    return image;
+  }
+  /** The connection settings that differ from a fresh connection's. */
+  changedPragmas() {
+    const changed = /* @__PURE__ */ new Map();
+    if (!this.db)
+      return changed;
+    for (const [name, value] of readPragmas(this.db)) {
+      if (this.pragmaDefaults.get(name) !== value)
+        changed.set(name, value);
+    }
+    return changed;
+  }
+  /** Sets connection settings on the database, after a save or a reload. */
+  applyPragmas(settings) {
+    for (const [name, value] of settings) {
+      const literal = typeof value === "number" ? String(value) : `'${String(value).replace(/'/g, "''")}'`;
+      try {
+        this.db.exec(`PRAGMA ${name} = ${literal}`);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Opens or creates the IndexedDB database.
+   */
+  openIndexedDb() {
+    return new Promise((resolve, reject) => {
+      const req = indexedDB.open(this.dbName, DB_VERSION);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName);
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error);
+    });
+  }
+  /**
+   * Opens IndexedDB with retry logic and exponential backoff.
+   * Handles race conditions when multiple adapters initialize simultaneously.
+   *
+   * The "NotFoundError" for object stores typically occurs when:
+   * 1. Two adapters try to open/upgrade simultaneously
+   * 2. One adapter opens the DB while another is still upgrading
+   * 3. Schema version mismatch during concurrent initialization
+   *
+   * @param maxRetries Maximum number of retry attempts (default: 3)
+   * @param baseDelayMs Base delay in milliseconds (default: 100)
+   */
+  async openIndexedDbWithRetry(maxRetries = 3, baseDelayMs = 100) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await this.openIndexedDb();
+      } catch (error) {
+        lastError = error;
+        const isNotFoundError = error instanceof DOMException && error.name === "NotFoundError";
+        const isVersionError = error instanceof DOMException && error.name === "VersionError";
+        const isRetryable = isNotFoundError || isVersionError;
+        if (!isRetryable || attempt === maxRetries) {
+          break;
+        }
+        const delay = baseDelayMs * Math.pow(2, attempt);
+        console.warn(`[IndexedDbAdapter] Retrying IndexedDB open for "${this.dbName}" (attempt ${attempt + 1}/${maxRetries + 1}, delay: ${delay}ms)`, error);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Loads the SQLite database and its stamp from IndexedDB, in one
+   * transaction, so the two belong together.
+   */
+  async loadFromIndexedDb() {
+    if (!this.idb)
+      return { image: null, stamp: null };
+    return this.withTransactionRetry(() => new Promise((resolve, reject) => {
+      const tx = this.idb.transaction(this.storeName, "readonly");
+      const store = tx.objectStore(this.storeName);
+      const image = store.get(IMAGE_KEY);
+      const stamp = store.get(STAMP_KEY);
+      tx.oncomplete = () => resolve({
+        image: image.result ?? null,
+        stamp: typeof stamp.result === "string" ? stamp.result : null
+      });
+      tx.onabort = () => reject(tx.error ?? new Error(`IndexedDbAdapter: reading "${this.dbName}" was aborted.`));
+    }));
+  }
+  /**
+   * Writes the current image to IndexedDB, with a new stamp. Never called
+   * while a transaction is open (see saveIfIdle): sql.js's export() closes and
+   * reopens the connection, which ends an open transaction.
+   *
+   * Settles when the IndexedDB transaction completes, not when its put request
+   * succeeds: the transaction can still abort after that (a quota error at
+   * 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;
+    await this.saveIfStampIs(void 0);
+  }
+  /** 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 {
+      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();
+  }
+  /**
+   * Resolves once the writes up to `generation` are stored. A save in
+   * progress that holds them is waited for; an open transaction() is waited
+   * for, since its own save holds them; while a transaction a caller began
+   * with BEGIN is open, nothing can be stored, and its COMMIT stores them.
+   * Rejects when the save that held them failed.
+   */
+  async saveThrough(generation) {
+    while (this.savedGeneration < generation && this.db && this.idb) {
+      if (this.saving) {
+        const covering = this.savingGeneration >= generation;
+        try {
+          await this.saving;
+        } catch (error) {
+          if (covering)
+            throw error;
+        }
+        continue;
+      }
+      if (this.gate.openToken() !== null) {
+        await this.gate.ended();
+        continue;
+      }
+      if (this.inTransaction()) {
+        return;
+      }
+      await this.startSave();
+    }
+  }
+  /**
+   * Starts a save at once and keeps it as the save in progress. The caller has
+   * made sure no transaction is open: the export would end it.
+   */
+  startSave() {
+    this.savingGeneration = this.writeGeneration;
+    const saving = this.saveToIndexedDb().finally(() => {
+      if (this.saving === saving)
+        this.saving = null;
+    });
+    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(() => void 0);
+    }
+  }
+  reportLongWait() {
+    if (this.longWaitReported)
+      return;
+    this.longWaitReported = true;
+    console.warn(`[IndexedDbAdapter] A statement on "${this.dbName}" has waited ${LONG_WAIT_MS / 1e3} 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.`);
+  }
+  reportLockWait() {
+    if (this.lockWaitReported)
+      return;
+    this.lockWaitReported = true;
+    console.warn(`[IndexedDbAdapter] A statement on "${this.dbName}" has waited ${LONG_WAIT_MS / 1e3} s for its turn across tabs: another tab's transaction holds the lock, or a transaction() of this tab whose callback runs a statement through the adapter itself instead of the callback's handle waits on itself.`);
+  }
+  /**
+   * Wraps a transaction operation with retry logic.
+   * Handles "NotFoundError" by reopening IndexedDB connection.
+   */
+  async withTransactionRetry(operation, maxRetries = 2) {
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        return await operation();
+      } catch (error) {
+        lastError = error;
+        const isNotFoundError = error instanceof DOMException && error.name === "NotFoundError";
+        if (!isNotFoundError || attempt === maxRetries) {
+          break;
+        }
+        console.warn(`[IndexedDbAdapter] Transaction failed for "${this.dbName}", reopening connection (attempt ${attempt + 1}/${maxRetries + 1})`, error);
+        try {
+          if (this.idb) {
+            this.idb.close();
+          }
+          this.idb = await this.openIndexedDbWithRetry();
+        } catch (reopenError) {
+          console.error("[IndexedDbAdapter] Failed to reopen IndexedDB:", reopenError);
+          throw lastError;
+        }
+      }
+    }
+    throw lastError;
+  }
+  /**
+   * Starts auto-save interval.
+   */
+  startAutoSave() {
+    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 || this.closing) {
+      throw new Error("IndexedDbAdapter: Database not open. Call open() first.");
+    }
+  }
+  /**
+   * Normalizes last insert row ID to string or number.
+   */
+  normaliseRowId(value) {
+    if (typeof value === "number" || typeof value === "string") {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return value.toString();
+    }
+    return null;
+  }
+}
+const readPragmas = (db) => {
+  const values = /* @__PURE__ */ new Map();
+  for (const name of CONNECTION_PRAGMAS) {
+    try {
+      const value = db.exec(`PRAGMA ${name}`)[0]?.values?.[0]?.[0];
+      if (value !== void 0)
+        values.set(name, value);
+    } catch {
+    }
+  }
+  return values;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  IndexedDbAdapter,
+  IndexedDbConflictError
+});