@workglow/indexeddb 0.2.31 → 0.2.32

package/dist/storage/common.d.ts

@@ -3,8 +3,11 @@
  * Copyright 2025 Steven Roussey <sroussey@gmail.com>
  * SPDX-License-Identifier: Apache-2.0
  */
+export * from "./openIdb";
 export * from "./IndexedDbTable";
 export * from "./IndexedDbKvStorage";
 export * from "./IndexedDbTabularStorage";
+export * from "./IndexedDbTabularMigrationApplier";
 export * from "./IndexedDbVectorStorage";
+export * from "../migrations/IndexedDbMigrationRunner";
 //# sourceMappingURL=common.d.ts.map

package/dist/storage/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/storage/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../src/storage/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0BAA0B,CAAC;AAGzC,cAAc,wCAAwC,CAAC"}

package/dist/storage/node.js

@@ -1,3 +1,24 @@
+// src/storage/openIdb.ts
+function openIdb(dbName, options = {}) {
+  return new Promise((resolve, reject) => {
+    const req = indexedDB.open(dbName, options.version);
+    req.onsuccess = () => {
+      const db = req.result;
+      db.onversionchange = () => db.close();
+      resolve(db);
+    };
+    req.onupgradeneeded = (ev) => options.onUpgradeNeeded?.(ev);
+    req.onerror = () => {
+      const err = req.error;
+      if (err && err.name === "VersionError") {
+        reject(new Error(`IndexedDB ${dbName} exists at a higher version than ${options.version ?? "current"}`));
+        return;
+      }
+      reject(err);
+    };
+    req.onblocked = () => reject(new Error(`IndexedDB ${dbName} is blocked — close other tabs using this database.`));
+  });
+}
 // src/storage/IndexedDbTable.ts
 import { deepEqual } from "@workglow/util";
 var METADATA_STORE_NAME = "__schema_metadata__";
@@ -15,33 +36,8 @@ async function saveSchemaMetadata(db, tableName, snapshot) {
     }
   });
 }
-async function openIndexedDbTable(tableName, version, upgradeNeededCallback) {
-  return new Promise((resolve, reject) => {
-    const openRequest = indexedDB.open(tableName, version);
-    openRequest.onsuccess = (event) => {
-      const db = event.target.result;
-      db.onversionchange = () => {
-        db.close();
-      };
-      resolve(db);
-    };
-    openRequest.onupgradeneeded = (event) => {
-      if (upgradeNeededCallback) {
-        upgradeNeededCallback(event);
-      }
-    };
-    openRequest.onerror = () => {
-      const error = openRequest.error;
-      if (error && error.name === "VersionError") {
-        reject(new Error(`Database ${tableName} exists at a higher version. Cannot open at version ${version || "current"}.`));
-      } else {
-        reject(error);
-      }
-    };
-    openRequest.onblocked = () => {
-      reject(new Error(`Database ${tableName} is blocked. Close all other tabs using this database.`));
-    };
-  });
+function openIndexedDbTable(tableName, version, upgradeNeededCallback) {
+  return openIdb(tableName, { version, onUpgradeNeeded: upgradeNeededCallback });
 }
 async function deleteIndexedDbTable(tableName) {
   return new Promise((resolve, reject) => {
@@ -325,6 +321,404 @@ import {
   isSearchCondition,
   pickCoveringIndex
 } from "@workglow/storage";
+
+// src/migrations/IndexedDbMigrationRunner.ts
+import {
+  MIGRATIONS_TABLE,
+  sortMigrations
+} from "@workglow/storage";
+function getIndexedDb() {
+  const idb = globalThis.indexedDB;
+  if (!idb) {
+    throw new Error("indexedDB is not available in this environment. Provide one via the IndexedDbMigrationRunner constructor or polyfill globalThis.indexedDB.");
+  }
+  return idb;
+}
+
+class MigrationAbortedByOtherTabError extends Error {
+  constructor(dbName) {
+    super(`IndexedDB ${dbName} migration aborted: another tab requested a higher version`);
+    this.name = "MigrationAbortedByOtherTabError";
+  }
+}
+var RUN_LOCKS = new Map;
+
+class IndexedDbMigrationRunner {
+  dbName;
+  idb;
+  constructor(dbName, idb = getIndexedDb()) {
+    this.dbName = dbName;
+    this.idb = idb;
+  }
+  async probe() {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finalize = (db, outcome) => {
+        if (settled)
+          return;
+        settled = true;
+        if (db) {
+          try {
+            db.close();
+          } catch {}
+        }
+        if (outcome.ok)
+          resolve(outcome.value);
+        else
+          reject(outcome.error);
+      };
+      const req = this.idb.open(this.dbName);
+      req.onupgradeneeded = () => {
+        if (settled)
+          return;
+        const u = req.result;
+        if (!u.objectStoreNames.contains(MIGRATIONS_TABLE)) {
+          u.createObjectStore(MIGRATIONS_TABLE, { keyPath: ["component", "version"] });
+        }
+      };
+      req.onsuccess = () => {
+        if (settled)
+          return;
+        const db = req.result;
+        const currentVersion = db.version;
+        if (!db.objectStoreNames.contains(MIGRATIONS_TABLE)) {
+          finalize(db, { ok: true, value: { currentVersion, applied: new Set } });
+          return;
+        }
+        const tx = db.transaction(MIGRATIONS_TABLE, "readonly");
+        const store = tx.objectStore(MIGRATIONS_TABLE);
+        const getAll = store.getAll();
+        getAll.onsuccess = () => {
+          if (settled)
+            return;
+          const rows = getAll.result;
+          finalize(db, {
+            ok: true,
+            value: {
+              currentVersion,
+              applied: new Set(rows.map((r) => `${r.component}@${r.version}`))
+            }
+          });
+        };
+        getAll.onerror = () => {
+          if (settled)
+            return;
+          finalize(db, { ok: false, error: getAll.error });
+        };
+      };
+      req.onerror = () => {
+        if (settled)
+          return;
+        finalize(undefined, { ok: false, error: req.error });
+      };
+      req.onblocked = () => {
+        if (settled)
+          return;
+        finalize(undefined, {
+          ok: false,
+          error: new Error(`IndexedDB ${this.dbName} blocked while probing for bookkeeping store`)
+        });
+      };
+    });
+  }
+  async ensureBookkeepingTable() {
+    await this.probe();
+  }
+  async appliedVersions(component) {
+    const { applied } = await this.probe();
+    const versions = new Set;
+    for (const key of applied) {
+      const at = key.lastIndexOf("@");
+      if (at < 0)
+        continue;
+      const c = key.slice(0, at);
+      const v = Number(key.slice(at + 1));
+      if (c === component && Number.isFinite(v))
+        versions.add(v);
+    }
+    return versions;
+  }
+  async run(migrations, options = {}) {
+    const prev = RUN_LOCKS.get(this.dbName) ?? Promise.resolve();
+    const next = prev.catch(() => {
+      return;
+    }).then(() => this.runLocked(migrations, options));
+    RUN_LOCKS.set(this.dbName, next);
+    try {
+      return await next;
+    } finally {
+      if (RUN_LOCKS.get(this.dbName) === next)
+        RUN_LOCKS.delete(this.dbName);
+    }
+  }
+  async runLocked(migrations, options) {
+    const sorted = sortMigrations(migrations);
+    if (sorted.length === 0)
+      return [];
+    const { currentVersion, applied: alreadyApplied } = await this.probe();
+    const pending = sorted.filter((m) => !alreadyApplied.has(`${m.component}@${m.version}`));
+    if (pending.length === 0)
+      return [];
+    const targetVersion = currentVersion + 1;
+    const applied = [];
+    const onProgress = options.onProgress;
+    const buffered = [];
+    const emitLater = onProgress ? (ev) => buffered.push(ev) : undefined;
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      let upgradeDb;
+      const finalize = (outcome) => {
+        if (settled)
+          return;
+        settled = true;
+        if (upgradeDb) {
+          try {
+            upgradeDb.close();
+          } catch {}
+        }
+        if (outcome.ok)
+          resolve();
+        else
+          reject(outcome.error);
+      };
+      const upreq = this.idb.open(this.dbName, targetVersion);
+      upreq.onupgradeneeded = (ev) => {
+        if (settled)
+          return;
+        try {
+          const db = upreq.result;
+          upgradeDb = db;
+          const tx = upreq.transaction;
+          const oldVersion = ev.oldVersion;
+          const newVersion = ev.newVersion ?? targetVersion;
+          db.onversionchange = () => {
+            try {
+              tx.abort();
+            } catch {}
+            finalize({ ok: false, error: new MigrationAbortedByOtherTabError(this.dbName) });
+          };
+          if (!db.objectStoreNames.contains(MIGRATIONS_TABLE)) {
+            db.createObjectStore(MIGRATIONS_TABLE, { keyPath: ["component", "version"] });
+          }
+          const meta = tx.objectStore(MIGRATIONS_TABLE);
+          for (const m of pending) {
+            emitLater?.({
+              component: m.component,
+              version: m.version,
+              phase: "starting",
+              description: m.description
+            });
+            const ctx = { db, tx, oldVersion, newVersion };
+            const result = m.up(ctx, (fraction) => {
+              emitLater?.({
+                component: m.component,
+                version: m.version,
+                phase: "running",
+                description: m.description,
+                fraction
+              });
+            });
+            if (result instanceof Promise) {
+              throw new Error(`IndexedDB migration "${m.component}@${m.version}" returned a Promise; ` + `IDB upgrade transactions cannot span async work.`);
+            }
+            meta.add({
+              component: m.component,
+              version: m.version,
+              description: m.description ?? null,
+              applied_at: new Date().toISOString()
+            });
+            applied.push(m);
+            emitLater?.({
+              component: m.component,
+              version: m.version,
+              phase: "completed",
+              description: m.description,
+              fraction: 1
+            });
+          }
+        } catch (err) {
+          try {
+            upreq.transaction?.abort();
+          } catch {}
+          const lastStart = [...buffered].reverse().find((e) => e.phase === "starting");
+          if (lastStart) {
+            emitLater?.({
+              component: lastStart.component,
+              version: lastStart.version,
+              phase: "failed",
+              description: lastStart.description,
+              error: err
+            });
+          }
+          finalize({ ok: false, error: err });
+        }
+      };
+      upreq.onsuccess = () => {
+        if (settled)
+          return;
+        upgradeDb = upreq.result;
+        finalize({ ok: true });
+      };
+      upreq.onerror = () => {
+        if (settled)
+          return;
+        finalize({ ok: false, error: upreq.error });
+      };
+      upreq.onblocked = () => {
+        if (settled)
+          return;
+        finalize({
+          ok: false,
+          error: new Error(`IndexedDB ${this.dbName} upgrade blocked — close other tabs.`)
+        });
+      };
+    }).finally(() => {
+      if (onProgress) {
+        for (const ev of buffered)
+          onProgress(ev);
+      }
+    });
+    return applied;
+  }
+}
+async function runIndexedDbMigrationGroups(groups, options = {}) {
+  const { idb, onProgress } = options;
+  const all = [];
+  for (const group of groups) {
+    const runner = idb ? new IndexedDbMigrationRunner(group.dbName, idb) : new IndexedDbMigrationRunner(group.dbName);
+    const applied = await runner.run(group.migrations, { onProgress });
+    all.push(...applied);
+  }
+  return all;
+}
+
+// src/storage/IndexedDbTabularMigrationApplier.ts
+async function idbObjectStoreExists(dbName, storeName) {
+  const idb = globalThis.indexedDB;
+  if (!idb)
+    throw new Error("indexedDB is not available in this environment");
+  return new Promise((resolve, reject) => {
+    const req = idb.open(dbName);
+    req.onsuccess = () => {
+      const db = req.result;
+      const exists = db.objectStoreNames.contains(storeName);
+      db.close();
+      resolve(exists);
+    };
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error(`IndexedDB ${dbName} blocked while probing for object store`));
+  });
+}
+
+class IndexedDbTabularMigrationApplier {
+  dbName;
+  storeName;
+  storage;
+  runner;
+  constructor(dbName, storeName, storage, runner) {
+    this.dbName = dbName;
+    this.storeName = storeName;
+    this.storage = storage;
+    this.runner = runner ?? new IndexedDbMigrationRunner(dbName);
+  }
+  async ensureBookkeeping() {
+    await this.runner.ensureBookkeepingTable();
+  }
+  async appliedVersions(component) {
+    return this.runner.appliedVersions(component);
+  }
+  async tableExists() {
+    return idbObjectStoreExists(this.dbName, this.storeName);
+  }
+  async markAllApplied(component, versions) {
+    if (versions.length === 0)
+      return;
+    await this.runner.run(versions.map((v) => ({
+      component,
+      version: v.version,
+      description: v.description,
+      up: () => {
+        return;
+      }
+    })));
+  }
+  async applyMigration(component, version, description, ops, onProgress) {
+    const ddlOps = [];
+    const backfills = [];
+    for (const op of ops) {
+      switch (op.kind) {
+        case "addIndex":
+        case "dropIndex":
+          ddlOps.push(op);
+          break;
+        case "backfill":
+          backfills.push(op);
+          break;
+        case "addColumn":
+        case "dropColumn":
+        case "renameColumn":
+          break;
+        default: {
+          const _exhaustive = op;
+          throw new Error(`IndexedDbTabularMigrationApplier: unhandled op kind ${_exhaustive.kind}`);
+        }
+      }
+    }
+    let processed = 0;
+    const total = Math.max(ops.length, 1);
+    for (const op of backfills) {
+      const batchSize = op.batchSize ?? 500;
+      let cursor;
+      while (true) {
+        const page = await this.storage.getPage({ limit: batchSize, cursor });
+        for (const row of page.items) {
+          const out = await op.transform(row);
+          if (out === row)
+            continue;
+          if (out === undefined) {
+            await this.storage.delete(row);
+          } else {
+            await this.storage.put(out);
+          }
+        }
+        if (!page.nextCursor)
+          break;
+        cursor = page.nextCursor;
+      }
+      processed++;
+      onProgress?.(processed / total);
+    }
+    const storeName = this.storeName;
+    await this.runner.run([
+      {
+        component,
+        version,
+        description,
+        up: (ctx) => {
+          if (!ctx.db.objectStoreNames.contains(storeName))
+            return;
+          const store = ctx.tx.objectStore(storeName);
+          for (const op of ddlOps) {
+            if (op.kind === "addIndex") {
+              if (store.indexNames.contains(op.name))
+                continue;
+              const keyPath = op.columns.length === 1 ? op.columns[0] : [...op.columns];
+              store.createIndex(op.name, keyPath, { unique: op.unique ?? false });
+            } else {
+              if (!store.indexNames.contains(op.name))
+                continue;
+              store.deleteIndex(op.name);
+            }
+          }
+        }
+      }
+    ]);
+    processed += ddlOps.length;
+    onProgress?.(processed / total);
+  }
+}
+
+// src/storage/IndexedDbTabularStorage.ts
 var IDB_TABULAR_REPOSITORY = createServiceToken("storage.tabularRepository.indexedDb");
 function compareEntitiesForChange(a, b) {
   const au = a?.updated_at;
@@ -338,13 +732,14 @@ function compareEntitiesForChange(a, b) {
 class IndexedDbTabularStorage extends BaseTabularStorage {
   table;
   db;
+  applyingMigrations = false;
   setupPromise = null;
   migrationOptions;
   hybridManager = null;
   hybridOptions;
   cursorSafeIndexes;
-  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], migrationOptions = {}, clientProvidedKeys = "if-missing") {
-    super(schema, primaryKeyNames, indexes, clientProvidedKeys);
+  constructor(table = "tabular_store", schema, primaryKeyNames, indexes = [], migrationOptions = {}, clientProvidedKeys = "if-missing", tabularMigrations) {
+    super(schema, primaryKeyNames, indexes, clientProvidedKeys, tabularMigrations, table);
     this.table = table;
     this.migrationOptions = migrationOptions;
     this.hybridOptions = {
@@ -365,12 +760,46 @@ class IndexedDbTabularStorage extends BaseTabularStorage {
       await this.setupPromise;
       return;
     }
+    if (this.applyingMigrations) {
+      this.setupPromise = this.performSetup();
+      try {
+        this.db = await this.setupPromise;
+        this.rewireOnVersionChange();
+      } finally {
+        this.setupPromise = null;
+      }
+      return;
+    }
+    const freshTable = this.tabularMigrations && this.tabularMigrations.length > 0 ? !await this.probeObjectStoreExists() : false;
     this.setupPromise = this.performSetup();
     try {
       this.db = await this.setupPromise;
     } finally {
       this.setupPromise = null;
     }
+    if (this.tabularMigrations && this.tabularMigrations.length > 0) {
+      this.rewireOnVersionChange();
+      this.applyingMigrations = true;
+      try {
+        await this.applyTabularMigrations({ freshTable });
+      } finally {
+        this.applyingMigrations = false;
+      }
+      if (!this.db) {
+        this.db = await this.performSetup();
+      }
+    }
+  }
+  rewireOnVersionChange() {
+    if (!this.db)
+      return;
+    this.db.onversionchange = () => {
+      this.db?.close();
+      this.db = undefined;
+    };
+  }
+  async probeObjectStoreExists() {
+    return idbObjectStoreExists(this.table, this.table);
   }
   async performSetup() {
     const pkColumns = super.primaryKeyColumns();
@@ -394,6 +823,13 @@ class IndexedDbTabularStorage extends BaseTabularStorage {
     const useAutoIncrement = this.hasAutoGeneratedKey() && this.autoGeneratedKeyStrategy === "autoincrement" && pkColumns.length === 1;
     return await ensureIndexedDbTable(this.table, primaryKey, expectedIndexes, this.migrationOptions, useAutoIncrement);
   }
+  getMigrationApplier() {
+    return new IndexedDbTabularMigrationApplier(this.table, this.table, {
+      getPage: (req) => this.getPage(req),
+      put: (row) => this.put(row),
+      delete: (row) => this.delete(row)
+    });
+  }
   generateKeyValue(columnName, strategy) {
     if (strategy === "uuid") {
       return uuid4();
@@ -1169,14 +1605,20 @@ class IndexedDbVectorStorage extends IndexedDbTabularStorage {
   }
 }
 export {
+  runIndexedDbMigrationGroups,
+  openIdb,
+  idbObjectStoreExists,
   ensureIndexedDbTable,
   dropIndexedDbTable,
+  MigrationAbortedByOtherTabError,
   IndexedDbVectorStorage,
   IndexedDbTabularStorage,
+  IndexedDbTabularMigrationApplier,
+  IndexedDbMigrationRunner,
   IndexedDbKvStorage,
   IDB_VECTOR_REPOSITORY,
   IDB_TABULAR_REPOSITORY,
   IDB_KV_REPOSITORY
 };
 
-//# debugId=D7674124BFA18F0C64756E2164756E21
+//# debugId=2A9580D89ED3759364756E2164756E21