@korajs/store 1.0.0-beta.11 → 1.0.0-beta.13

package/dist/adapters/sqlite-wasm-worker.js

@@ -1,6 +1,42 @@
-// src/adapters/sqlite-wasm-worker-core.ts
-var OPFS_POOL_NAME = "kora-opfs";
+import {
+  STORED_SCHEMA_VERSION_SQL,
+  parseSchemaCeiling,
+  schemaAheadMessage,
+  storedSchemaVersion
+} from "../chunk-A6GFH5IG.js";
+import {
+  LEGACY_OPFS_POOL_NAME,
+  TransactionSerializingWorkerBridge,
+  opfsPoolDirectory,
+  opfsPoolLockName,
+  opfsPoolNameFor,
+  opfsPoolPath,
+  startWorkerRpcRelay
+} from "../chunk-W5F2LWG6.js";
+import "../chunk-DUKTWVZW.js";
+
+// src/adapters/opfs-pool-ownership.ts
+var OPFS_POOL_HEADROOM = 2;
+var BLOCKED_REPORT_AFTER_MS = 750;
+var INSTALL_RACE_ATTEMPTS = 20;
 var OPFS_INIT_TIMEOUT_MS = 1e4;
+var OPAQUE_DIR_NAME = ".opaque";
+var PoolUnavailableError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "PoolUnavailableError";
+  }
+  reason;
+};
+function opfsSahSupported(sqlite3) {
+  const g = globalThis;
+  const fileHandle = g.FileSystemFileHandle;
+  return typeof sqlite3.installOpfsSAHPoolVfs === "function" && typeof g.FileSystemDirectoryHandle !== "undefined" && typeof fileHandle?.prototype?.createSyncAccessHandle === "function" && typeof navigator !== "undefined" && typeof navigator.storage?.getDirectory === "function";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function withTimeout(promise, timeoutMs, label) {
   let timer;
   try {
@@ -8,7 +44,7 @@ async function withTimeout(promise, timeoutMs, label) {
       promise,
       new Promise((_, reject) => {
         timer = setTimeout(
-          () => reject(new Error(`${label} timed out after ${timeoutMs}ms`)),
+          () => reject(new PoolUnavailableError(`${label} timed out after ${timeoutMs}ms`, "timeout")),
           timeoutMs
         );
       })
@@ -17,25 +53,198 @@ async function withTimeout(promise, timeoutMs, label) {
     if (timer !== void 0) clearTimeout(timer);
   }
 }
-function opfsDatabaseFilename(dbName) {
-  const base = dbName.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return base.endsWith(".db") ? base : `${base}.db`;
+async function holdExclusiveLock(name, reporter) {
+  const locks = typeof navigator !== "undefined" ? navigator.locks : void 0;
+  if (!locks || typeof locks.request !== "function") {
+    return () => {
+    };
+  }
+  const grab = (ifAvailable) => new Promise((resolve, reject) => {
+    locks.request(name, { mode: "exclusive", ifAvailable }, (lock) => {
+      if (lock === null) {
+        resolve(null);
+        return void 0;
+      }
+      return new Promise((release2) => {
+        resolve(() => release2());
+      });
+    }).catch(reject);
+  });
+  const immediate = await grab(true);
+  if (immediate) return immediate;
+  const start = Date.now();
+  reporter?.blocked();
+  const release = await grab(false);
+  if (!release) {
+    throw new PoolUnavailableError(`Web Lock "${name}" was not granted`, "lock-conflict");
+  }
+  reporter?.unblocked(Date.now() - start);
+  return release;
+}
+async function opfsRoot() {
+  return await navigator.storage.getDirectory();
+}
+async function childDirectory(parent, name) {
+  try {
+    return await parent.getDirectoryHandle(name);
+  } catch {
+    return null;
+  }
+}
+async function poolDirectoryExists(poolName) {
+  return await childDirectory(await opfsRoot(), opfsPoolDirectory(poolName)) !== null;
+}
+function isHandleBusy(error) {
+  const name = error?.name;
+  return name === "NoModificationAllowedError" || name === "InvalidStateError";
+}
+async function poolHandlesBusy(poolName) {
+  const dir = await childDirectory(await opfsRoot(), opfsPoolDirectory(poolName));
+  if (!dir) return false;
+  const opaque = await childDirectory(dir, OPAQUE_DIR_NAME);
+  if (!opaque) return false;
+  for await (const [, handle] of opaque.entries()) {
+    if (handle.kind !== "file") continue;
+    try {
+      const access = await handle.createSyncAccessHandle();
+      access.close();
+    } catch (error) {
+      if (isHandleBusy(error)) return true;
+      throw error;
+    }
+  }
+  return false;
+}
+async function waitForPoolHandles(poolName, reporter) {
+  const start = Date.now();
+  let reported = false;
+  let delay = 15;
+  while (await poolHandlesBusy(poolName)) {
+    if (!reported && Date.now() - start >= BLOCKED_REPORT_AFTER_MS) {
+      reported = true;
+      reporter?.blocked();
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 2, 500);
+  }
+  if (reported) reporter?.unblocked(Date.now() - start);
 }
-function classifyOpfsFailure(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  if (/timed out|timeout/i.test(message)) {
-    return "timeout";
+async function installPool(sqlite3, poolName, reporter) {
+  const install = sqlite3.installOpfsSAHPoolVfs;
+  if (!install || !opfsSahSupported(sqlite3)) {
+    throw new PoolUnavailableError("OPFS SyncAccessHandle pool is not supported", "unsupported");
   }
-  if (/lock|already|in use|in-use|NoModificationAllowed|acquire|SyncAccessHandle|being created/i.test(
-    message
-  )) {
-    return "lock-conflict";
+  let lastError = null;
+  for (let attempt = 0; attempt < INSTALL_RACE_ATTEMPTS; attempt += 1) {
+    await waitForPoolHandles(poolName, reporter);
+    try {
+      const pool = await withTimeout(
+        install({ name: poolName, forceReinitIfPreviouslyFailed: true }),
+        OPFS_INIT_TIMEOUT_MS,
+        "OPFS VFS install"
+      );
+      if (pool.isPaused()) {
+        await pool.unpauseVfs();
+      }
+      return pool;
+    } catch (error) {
+      if (error instanceof PoolUnavailableError) throw error;
+      lastError = error;
+      if (!isHandleBusy(error)) break;
+      await sleep(Math.min(25 * 2 ** attempt, 250));
+    }
   }
-  return "unsupported";
+  const message = lastError instanceof Error ? lastError.message : String(lastError);
+  if (isHandleBusy(lastError)) {
+    throw new PoolUnavailableError(
+      `OPFS pool "${poolName}" stayed busy: ${message}`,
+      "lock-conflict"
+    );
+  }
+  throw new PoolUnavailableError(
+    `OPFS pool "${poolName}" could not be installed: ${message}`,
+    "unsupported"
+  );
+}
+async function ensurePoolCapacity(pool) {
+  await pool.reserveMinimumCapacity(pool.getFileCount() + 2 + OPFS_POOL_HEADROOM);
 }
+function assertDatabaseHealthy(db, label) {
+  const rows = db.exec({
+    sql: "PRAGMA quick_check",
+    returnValue: "resultRows",
+    rowMode: "array"
+  });
+  const verdict = rows?.[0]?.[0];
+  if (verdict !== "ok") {
+    throw new Error(`${label} failed integrity check: ${String(verdict)}`);
+  }
+}
+function pausePool(pool) {
+  if (!pool.isPaused()) {
+    pool.pauseVfs();
+  }
+}
+async function migrateFromLegacyPool(sqlite3, target, poolPath, reporter) {
+  if (!await poolDirectoryExists(LEGACY_OPFS_POOL_NAME)) {
+    return false;
+  }
+  const releaseLegacyLock = await holdExclusiveLock(
+    opfsPoolLockName(LEGACY_OPFS_POOL_NAME),
+    reporter
+  );
+  try {
+    if (!await poolDirectoryExists(LEGACY_OPFS_POOL_NAME)) {
+      return false;
+    }
+    const legacy = await installPool(sqlite3, LEGACY_OPFS_POOL_NAME, reporter);
+    try {
+      if (!legacy.getFileNames().includes(poolPath)) {
+        return false;
+      }
+      const legacyDb = new legacy.OpfsSAHPoolDb(poolPath);
+      try {
+        assertDatabaseHealthy(legacyDb, `Legacy database ${poolPath}`);
+      } finally {
+        legacyDb.close();
+      }
+      const bytes = legacy.exportFile(poolPath);
+      if (bytes.byteLength === 0) {
+        legacy.unlink(poolPath);
+        return false;
+      }
+      await ensurePoolCapacity(target);
+      await target.importDb(poolPath, bytes);
+      let migratedDb = null;
+      try {
+        migratedDb = new target.OpfsSAHPoolDb(poolPath);
+        assertDatabaseHealthy(migratedDb, `Migrated database ${poolPath}`);
+      } catch (error) {
+        migratedDb?.close();
+        migratedDb = null;
+        target.unlink(poolPath);
+        throw error;
+      }
+      migratedDb.close();
+      legacy.unlink(poolPath);
+      legacy.unlink(`${poolPath}-journal`);
+      return true;
+    } finally {
+      if (legacy.getFileCount() === 0) {
+        await legacy.removeVfs();
+      } else {
+        pausePool(legacy);
+      }
+    }
+  } finally {
+    releaseLegacyLock();
+  }
+}
+
+// src/adapters/sqlite-wasm-worker-core.ts
+var PROGRESS_HEARTBEAT_MS = 500;
+var PROGRESS_HANDLER_OPS = 2e4;
 var sqlite3Promise = null;
-var opfsPoolPromise = null;
-var opfsFallbackReason;
 async function loadSqlite3() {
   const sqlite3InitModule = (await import("@sqlite.org/sqlite-wasm")).default;
   const wasmUrl = globalThis.__KORA_SQLITE_WASM_URL;
@@ -43,7 +252,20 @@ async function loadSqlite3() {
     locateFile: (file) => file.endsWith(".wasm") ? wasmUrl : file
   } : void 0;
   const initFn = sqlite3InitModule;
-  return await withTimeout(initFn(initOptions), 6e4, "SQLite3 module init");
+  let timer;
+  try {
+    return await Promise.race([
+      initFn(initOptions),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("SQLite3 module init timed out after 60000ms")),
+          6e4
+        );
+      })
+    ]);
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+  }
 }
 function getSqlite3() {
   if (!sqlite3Promise) {
@@ -51,64 +273,213 @@ function getSqlite3() {
   }
   return sqlite3Promise;
 }
-async function installOpfsPool(sqlite3) {
-  if (!sqlite3.installOpfsSAHPoolVfs) {
-    opfsFallbackReason = "unsupported";
-    return null;
+function createSqliteWasmCore(options = {}) {
+  let db = null;
+  let sqlite3Api = null;
+  let persistent = false;
+  let fallbackReason;
+  let pool = null;
+  let poolName = null;
+  let releasePoolLock = null;
+  let openInfo = {
+    created: false,
+    migratedFromLegacy: false
+  };
+  let lastProgressBeat = 0;
+  function reporterFor(resource, name) {
+    return {
+      blocked: () => options.postEvent?.({ kind: "storage-blocked", resource, poolName: name }),
+      unblocked: (waitedMs) => options.postEvent?.({ kind: "storage-unblocked", resource, poolName: name, waitedMs })
+    };
   }
-  try {
-    return await withTimeout(
-      sqlite3.installOpfsSAHPoolVfs({ name: OPFS_POOL_NAME }),
-      OPFS_INIT_TIMEOUT_MS,
-      "OPFS VFS install"
+  async function releaseStorage(mode) {
+    if (db) {
+      detachProgressHandler(db);
+      try {
+        db.close();
+      } finally {
+        db = null;
+      }
+    }
+    if (pool) {
+      if (mode === "remove") {
+        await pool.removeVfs();
+      } else {
+        pausePool(pool);
+      }
+      pool = null;
+    }
+    releasePoolLock?.();
+    releasePoolLock = null;
+  }
+  function attachProgressHandler(target) {
+    const register = sqlite3Api?.capi?.sqlite3_progress_handler;
+    if (!options.onProgress || typeof register !== "function" || !target.pointer) return;
+    register(
+      target.pointer,
+      PROGRESS_HANDLER_OPS,
+      () => {
+        const now = Date.now();
+        if (now - lastProgressBeat >= PROGRESS_HEARTBEAT_MS) {
+          lastProgressBeat = now;
+          options.onProgress?.();
+        }
+        return 0;
+      },
+      0
     );
-  } catch (error) {
-    opfsFallbackReason = classifyOpfsFailure(error);
-    return null;
   }
-}
-function getOpfsPool(sqlite3) {
-  if (!opfsPoolPromise) {
-    opfsPoolPromise = installOpfsPool(sqlite3);
+  function detachProgressHandler(target) {
+    const register = sqlite3Api?.capi?.sqlite3_progress_handler;
+    if (typeof register !== "function" || !target.pointer) return;
+    try {
+      register(target.pointer, 0, 0, 0);
+    } catch {
+    }
   }
-  return opfsPoolPromise;
-}
-function createSqliteWasmCore() {
-  let db = null;
-  let sqlite3Api = null;
-  let persistent = false;
-  async function open(id, ddlStatements, dbName) {
+  async function openOpfs(sqlite3, dbName, mustExist) {
+    const name = opfsPoolNameFor(dbName);
+    const path = opfsPoolPath(dbName);
+    poolName = name;
+    releasePoolLock = await holdExclusiveLock(opfsPoolLockName(name), reporterFor("pool", name));
+    pool = await installPool(sqlite3, name, reporterFor("pool", name));
+    let migratedFromLegacy = false;
+    if (!pool.getFileNames().includes(path)) {
+      migratedFromLegacy = await migrateFromLegacyPool(
+        sqlite3,
+        pool,
+        path,
+        reporterFor("legacy-pool", name)
+      );
+    }
+    const existedBefore = pool.getFileNames().includes(path);
+    if (!existedBefore && mustExist) {
+      await releaseStorage(pool.getFileCount() === 0 ? "remove" : "pause");
+      return { id: 0, type: "error", message: `Database file ${path} not found`, code: "NOT_FOUND" };
+    }
+    await ensurePoolCapacity(pool);
     try {
-      if (db) {
+      db = new pool.OpfsSAHPoolDb(path);
+    } catch (error) {
+      if (!existedBefore) pool.unlink(path);
+      throw error;
+    }
+    persistent = true;
+    openInfo = { created: !existedBefore, migratedFromLegacy };
+    return null;
+  }
+  async function open(id, ddlStatements, dbName, storage, mustExist) {
+    if (db) {
+      try {
         applyDdl(db, ddlStatements);
         return { id, type: "success", data: buildOpenData() };
+      } catch (error) {
+        return { id, type: "error", message: error.message, code: "INIT_ERROR" };
       }
+    }
+    let createdPath = null;
+    try {
       const sqlite3 = await getSqlite3();
       sqlite3Api = sqlite3;
-      const pool = await getOpfsPool(sqlite3);
-      if (pool) {
-        db = new pool.OpfsSAHPoolDb(opfsDatabaseFilename(dbName ?? "kora-db"));
-        persistent = true;
+      if (storage === "opfs" && opfsSahSupported(sqlite3)) {
+        try {
+          const early = await openOpfs(sqlite3, dbName, mustExist);
+          if (early) return { ...early, id };
+          if (openInfo.created) createdPath = opfsPoolPath(dbName);
+        } catch (error) {
+          if (!(error instanceof PoolUnavailableError) || error.reason === "lock-conflict") {
+            throw error;
+          }
+          await releaseStorage("pause");
+          fallbackReason = error.reason;
+        }
       } else {
+        fallbackReason = "unsupported";
+      }
+      if (!db) {
         db = new sqlite3.oo1.DB({ filename: ":memory:" });
         persistent = false;
       }
-      db.exec({ sql: "PRAGMA journal_mode = WAL" });
       db.exec({ sql: "PRAGMA foreign_keys = ON" });
       applyDdl(db, ddlStatements);
+      attachProgressHandler(db);
       return { id, type: "success", data: buildOpenData() };
     } catch (error) {
-      return { id, type: "error", message: error.message, code: "INIT_ERROR" };
+      const currentPool = pool;
+      if (db) {
+        try {
+          db.close();
+        } catch {
+        }
+        db = null;
+      }
+      if (createdPath && currentPool) {
+        try {
+          currentPool.unlink(createdPath);
+          currentPool.unlink(`${createdPath}-journal`);
+        } catch {
+        }
+      }
+      try {
+        await releaseStorage("pause");
+      } catch {
+      }
+      const reason = error instanceof PoolUnavailableError ? error.reason : void 0;
+      return {
+        id,
+        type: "error",
+        message: error.message,
+        code: "INIT_ERROR",
+        context: {
+          ...reason ? { reason } : {},
+          ...createdPath ? { removedCreatedFile: createdPath } : {}
+        }
+      };
+    }
+  }
+  function readJournalMode() {
+    if (!db) return void 0;
+    try {
+      let mode;
+      db.exec({
+        sql: "PRAGMA journal_mode",
+        rowMode: "object",
+        callback: (row) => {
+          if (typeof row.journal_mode === "string") mode = row.journal_mode;
+        }
+      });
+      return mode;
+    } catch {
+      return void 0;
     }
   }
   function buildOpenData() {
+    const journalMode = readJournalMode();
     return {
+      ...journalMode ? { journalMode } : {},
       persistent,
-      ...persistent ? {} : { fallbackReason: opfsFallbackReason ?? "unsupported" }
+      ...persistent ? {} : { fallbackReason: fallbackReason ?? "unsupported" },
+      ...poolName && persistent ? { poolName } : {},
+      created: openInfo.created,
+      migratedFromLegacy: openInfo.migratedFromLegacy
     };
   }
   function applyDdl(target, ddlStatements) {
     for (const sql of ddlStatements) {
+      const ceiling = parseSchemaCeiling(sql);
+      if (ceiling !== null) {
+        const rows = [];
+        target.exec({
+          sql: STORED_SCHEMA_VERSION_SQL,
+          rowMode: "object",
+          callback: (row) => {
+            rows.push({ value: row.value });
+          }
+        });
+        const stored = storedSchemaVersion(rows);
+        if (stored > ceiling) throw new Error(schemaAheadMessage(stored, ceiling));
+        continue;
+      }
       if (sql.startsWith("--kora:safe-alter")) {
         try {
           target.exec({ sql: sql.replace("--kora:safe-alter\n", "") });
@@ -153,12 +524,13 @@ function createSqliteWasmCore() {
       return { id, type: "error", message: error.message, code: "QUERY_ERROR" };
     }
   }
-  function close(id) {
-    if (db) {
-      db.close();
-      db = null;
+  async function close(id, mode) {
+    try {
+      await releaseStorage(mode);
+      return { id, type: "success" };
+    } catch (error) {
+      return { id, type: "error", message: error.message, code: "CLOSE_ERROR" };
     }
-    return { id, type: "success" };
   }
   function migrate(id, statements) {
     if (!db) {
@@ -177,10 +549,9 @@ function createSqliteWasmCore() {
     if (!db) {
       return { id, type: "error", message: "Database is not open", code: "DB_NOT_OPEN" };
     }
-    const dbWithDeserialize = db;
-    if (typeof dbWithDeserialize.deserialize === "function") {
+    if (typeof db.deserialize === "function") {
       try {
-        dbWithDeserialize.deserialize(data);
+        db.deserialize(data);
         return { id, type: "success" };
       } catch (error) {
         return { id, type: "error", message: error.message, code: "IMPORT_ERROR" };
@@ -205,9 +576,17 @@ function createSqliteWasmCore() {
     try {
       switch (request.type) {
         case "open":
-          return await open(request.id, request.ddlStatements, request.dbName);
+          return await open(
+            request.id,
+            request.ddlStatements,
+            request.dbName ?? "kora-db",
+            request.storage ?? "opfs",
+            request.mustExist === true
+          );
         case "close":
-          return close(request.id);
+          return await close(request.id, "pause");
+        case "destroy":
+          return await close(request.id, "remove");
         case "execute":
           return execute(request.id, request.sql, request.params);
         case "query":
@@ -229,6 +608,8 @@ function createSqliteWasmCore() {
             message: "Export not yet supported in browser worker",
             code: "EXPORT_NOT_SUPPORTED"
           };
+        case "serve":
+          return { id: request.id, type: "success" };
         default:
           return {
             id: request.id,
@@ -250,10 +631,47 @@ function createSqliteWasmCore() {
 }
 
 // src/adapters/sqlite-wasm-worker.ts
-var core = createSqliteWasmCore();
+var relay = null;
+var core = createSqliteWasmCore({
+  postEvent: (event) => {
+    const message = { id: -1, type: "event", event };
+    self.postMessage(message);
+  },
+  // Keep followers' watchdogs fed while a long statement blocks this worker.
+  onProgress: () => relay?.beat()
+});
+var serializer = new TransactionSerializingWorkerBridge({
+  send: (request) => core.handle(request),
+  terminate: () => {
+  }
+});
 self.onmessage = (event) => {
-  void core.handle(event.data).then((response) => {
+  const { clientId, ...request } = event.data;
+  if (request.type === "serve") {
+    if (!relay) {
+      relay = startWorkerRpcRelay(request.channelName, serializer);
+    }
+    const response = { id: request.id, type: "success" };
     self.postMessage(response);
-  });
+    return;
+  }
+  void serializer.send(request, clientId).then(
+    (response) => {
+      if (request.type === "close" || request.type === "destroy") {
+        relay?.stop();
+        relay = null;
+      }
+      self.postMessage(response);
+    },
+    (error) => {
+      const response = {
+        id: request.id,
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+        code: "WORKER_ERROR"
+      };
+      self.postMessage(response);
+    }
+  );
 };
 //# sourceMappingURL=sqlite-wasm-worker.js.map