@workglow/indexeddb 0.2.31 → 0.2.32

package/dist/migrations/IndexedDbMigrationRunner.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type IMigration, type IMigrationRunner, type RunMigrationsOptions } from "@workglow/storage";
+/**
+ * Context handed to an IndexedDB migration's `up()` body. IDB's spec only
+ * permits schema changes (createObjectStore, createIndex, etc.) inside an
+ * `onupgradeneeded` callback, so migrations receive both the {@link IDBDatabase}
+ * and the version-change {@link IDBTransaction} active during that callback.
+ *
+ * `up()` MUST be synchronous — IDB upgrade transactions auto-commit as soon as
+ * the callback returns control to the event loop, so any awaited Promise
+ * between IDB requests would silently lose the rest of the migration.
+ */
+export interface IndexedDbUpgradeContext {
+    readonly db: IDBDatabase;
+    readonly tx: IDBTransaction;
+    readonly oldVersion: number;
+    readonly newVersion: number;
+}
+/** Convenience alias for IndexedDB-flavoured migrations. */
+export type IndexedDbMigration = IMigration<IndexedDbUpgradeContext>;
+/**
+ * Thrown when an in-flight migration is interrupted by another tab opening
+ * the same database at a higher version. Surfaces as the `run()` rejection
+ * so callers can distinguish a tab-coordination failure from a programming
+ * error in `up()`.
+ */
+export declare class MigrationAbortedByOtherTabError extends Error {
+    constructor(dbName: string);
+}
+/**
+ * Runs versioned migrations against a single IndexedDB database.
+ *
+ * Bookkeeping-driven dispatch (NOT IDB-version-ordinal driven). The runner:
+ *   1. Probes the DB to read the `_storage_migrations` object store, building
+ *      a set of already-applied `(component, version)` pairs. The probe
+ *      registers an `onupgradeneeded` handler so that if the DB doesn't yet
+ *      exist, IDB's auto-creation path also creates the bookkeeping store
+ *      atomically (rather than leaving an empty v1 DB with no schema).
+ *   2. Computes the pending migrations as `sorted \ alreadyApplied` —
+ *      identifying each migration by `(component, version)`, NOT by its
+ *      position in the sorted array. This means inserting a new migration
+ *      that sorts BEFORE existing ones (e.g. a new component name that's
+ *      lexicographically earlier) is still correctly detected as pending.
+ *   3. If pending is empty, returns without bumping the IDB version.
+ *   4. Otherwise reopens at `currentVersion + 1` and runs every pending
+ *      migration inside the upgrade transaction, recording each in the
+ *      bookkeeping store as it goes.
+ *
+ * Concurrent `run()` calls against the same dbName (across instances) are
+ * serialized via {@link RUN_LOCKS} so that two callers don't deadlock each
+ * other on the open-at-higher-version handshake.
+ *
+ * The IDB database version is treated purely as a monotonic trigger for
+ * `onupgradeneeded`; we never use it to decide which migrations to apply.
+ *
+ * Caveats:
+ *   - `up()` must be synchronous. IDB upgrade transactions auto-commit as
+ *     soon as control returns to the event loop, so awaited Promises between
+ *     IDB requests would silently lose the rest of the migration. The runner
+ *     throws if `up()` returns a Promise.
+ */
+export declare class IndexedDbMigrationRunner implements IMigrationRunner<IndexedDbUpgradeContext> {
+    private readonly dbName;
+    private readonly idb;
+    constructor(dbName: string, idb?: IDBFactory);
+    private probe;
+    /** Ensures the bookkeeping object store exists (created lazily by {@link probe}). */
+    ensureBookkeepingTable(): Promise<void>;
+    appliedVersions(component: string): Promise<Set<number>>;
+    run(migrations: ReadonlyArray<IndexedDbMigration>, options?: RunMigrationsOptions): Promise<ReadonlyArray<IndexedDbMigration>>;
+    private runLocked;
+}
+/**
+ * Convenience helper used by storage classes — runs the supplied migration
+ * groups (one per IDB database) against fresh runners and returns an array
+ * of the applied migrations across all groups.
+ *
+ * IndexedDB groups exist because some storages (e.g. the rate limiter) span
+ * multiple databases and expose them as separate `(dbName, migrations)` pairs
+ * via `getMigrations()`.
+ */
+export interface IndexedDbMigrationGroup {
+    readonly dbName: string;
+    readonly migrations: ReadonlyArray<IndexedDbMigration>;
+}
+export declare function runIndexedDbMigrationGroups(groups: ReadonlyArray<IndexedDbMigrationGroup>, options?: RunMigrationsOptions & {
+    idb?: IDBFactory;
+}): Promise<ReadonlyArray<IndexedDbMigration>>;
+//# sourceMappingURL=IndexedDbMigrationRunner.d.ts.map

package/dist/migrations/IndexedDbMigrationRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedDbMigrationRunner.d.ts","sourceRoot":"","sources":["../../src/migrations/IndexedDbMigrationRunner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAG1B,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAAC;AAerE;;;;;GAKG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,YAAY,MAAM,EAAE,MAAM,EAGzB;CACF;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,wBAAyB,YAAW,gBAAgB,CAAC,uBAAuB,CAAC;IAEtF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFtB,YACmB,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,UAA2B,EAC/C;YAQU,KAAK;IAiFnB,qFAAqF;IAC/E,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAE5C;IAEK,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAW7D;IAEK,GAAG,CACP,UAAU,EAAE,aAAa,CAAC,kBAAkB,CAAC,EAC7C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAS5C;YAQa,SAAS;CAgKxB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CACxD;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,aAAa,CAAC,uBAAuB,CAAC,EAC9C,OAAO,GAAE,oBAAoB,GAAG;IAAE,GAAG,CAAC,EAAE,UAAU,CAAA;CAAO,GACxD,OAAO,CAAC,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAW5C"}

package/dist/migrations/indexedDbQueueMigrations.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { PrefixColumn } from "@workglow/job-queue";
+import type { IndexedDbMigration, IndexedDbMigrationGroup } from "./IndexedDbMigrationRunner";
+/**
+ * Initial migration set for the IndexedDB queue object store identified by
+ * `tableName`.
+ *
+ * Component name is `queue:indexeddb:<tableName>` so two queues with
+ * different table names get tracked independently in `_storage_migrations`.
+ *
+ * Schema: a single object store keyed by `id` plus four compound indexes
+ * (queue/status, queue/status/run_after, queue/job_run_id,
+ * queue/fingerprint/status). When `prefixes` is non-empty the prefix columns
+ * are prepended to every index key path so per-tenant queries can be served
+ * directly by the index.
+ */
+export declare function indexedDbQueueMigrations(tableName: string, prefixes: readonly PrefixColumn[]): IndexedDbMigration[];
+/** Returns the queue migrations packaged with their target IDB database name. */
+export declare function indexedDbQueueMigrationGroup(tableName: string, prefixes: readonly PrefixColumn[]): IndexedDbMigrationGroup;
+//# sourceMappingURL=indexedDbQueueMigrations.d.ts.map

package/dist/migrations/indexedDbQueueMigrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDbQueueMigrations.d.ts","sourceRoot":"","sources":["../../src/migrations/indexedDbQueueMigrations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE9F;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,kBAAkB,EAAE,CAyBtB;AAED,iFAAiF;AACjF,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,uBAAuB,CAKzB"}

package/dist/migrations/indexedDbRateLimiterMigrations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * Copyright 2025 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { PrefixColumn } from "@workglow/job-queue";
+import type { IndexedDbMigration, IndexedDbMigrationGroup } from "./IndexedDbMigrationRunner";
+/**
+ * Initial migrations for the IndexedDB rate-limiter execution table.
+ *
+ * Schema: an object store keyed by `id` (autoincrement-style; we generate
+ * UUIDs at the storage layer) plus a compound index `queue_executed_at` for
+ * windowed counts. Prefix columns are prepended to every index key path.
+ */
+export declare function indexedDbRateLimiterExecutionMigrations(executionTableName: string, prefixes: readonly PrefixColumn[]): IndexedDbMigration[];
+/**
+ * Initial migrations for the IndexedDB rate-limiter `next_available` table.
+ *
+ * Schema: object store keyed by a single synthetic field whose name is
+ * `prefixCols.concat(["queue_name"]).join("_")`. The storage layer writes
+ * a record where this field holds `prefixValues.concat([queueName]).join("_")`
+ * — i.e. tenant-qualified — so the same physical store can hold rows for
+ * multiple tenants without collisions. Without this, two tenants with the
+ * same queue name would silently overwrite each other's row (the
+ * `next_available_at` of one would be returned for the other).
+ *
+ * No `queue_name = "myqueue"` index is created because the storage's read
+ * path (`store.get(syntheticKey)`) goes through the primary key directly.
+ */
+export declare function indexedDbRateLimiterNextAvailableMigrations(nextAvailableTableName: string, prefixes: readonly PrefixColumn[]): IndexedDbMigration[];
+/**
+ * Returns the rate-limiter migrations packaged as IDB migration groups —
+ * one group per database, since `IndexedDbRateLimiterStorage` keeps the
+ * execution and next-available tables in separate databases.
+ */
+export declare function indexedDbRateLimiterMigrationGroups(executionTableName: string, nextAvailableTableName: string, prefixes: readonly PrefixColumn[]): IndexedDbMigrationGroup[];
+//# sourceMappingURL=indexedDbRateLimiterMigrations.d.ts.map

package/dist/migrations/indexedDbRateLimiterMigrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexedDbRateLimiterMigrations.d.ts","sourceRoot":"","sources":["../../src/migrations/indexedDbRateLimiterMigrations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAE9F;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CACrD,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,kBAAkB,EAAE,CAoBtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2CAA2C,CACzD,sBAAsB,EAAE,MAAM,EAC9B,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,kBAAkB,EAAE,CAoBtB;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,CACjD,kBAAkB,EAAE,MAAM,EAC1B,sBAAsB,EAAE,MAAM,EAC9B,QAAQ,EAAE,SAAS,YAAY,EAAE,GAChC,uBAAuB,EAAE,CAW3B"}

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

@@ -1 +1 @@
-{"version":3,"file":"IndexedDbTable.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDbTable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,WAAW,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,oFAAoF;IACpF,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,8CAA8C;IAC9C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/D;AAsZD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,eAAe,GAAE,uBAAuB,EAAO,EAC/C,OAAO,GAAE,gBAAqB,EAC9B,aAAa,GAAE,OAAe,GAC7B,OAAO,CAAC,WAAW,CAAC,CA6KtB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}
+{"version":3,"file":"IndexedDbTable.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDbTable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,kBAAkB,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,WAAW,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,OAAO,EAAE,GAAG,GAAG,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,oFAAoF;IACpF,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,8CAA8C;IAC9C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACnE,yDAAyD;IACzD,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/D;AA6WD;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,EAC7B,eAAe,GAAE,uBAAuB,EAAO,EAC/C,OAAO,GAAE,gBAAqB,EAC9B,aAAa,GAAE,OAAe,GAC7B,OAAO,CAAC,WAAW,CAAC,CA6KtB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEzE"}

package/dist/storage/IndexedDbTabularMigrationApplier.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { type ITabularMigrationApplier, type TabularMigrationOp } from "@workglow/storage";
+import { IndexedDbMigrationRunner } from "../migrations/IndexedDbMigrationRunner";
+interface BackfillCapableStorage {
+    getPage: (req?: {
+        limit?: number;
+        cursor?: unknown;
+    }) => Promise<{
+        items: Array<Record<string, unknown>>;
+        nextCursor?: unknown;
+    }>;
+    put: (row: Record<string, unknown>) => Promise<unknown>;
+    delete: (row: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * Read-only existence probe shared by `IndexedDbTabularMigrationApplier.tableExists`
+ * and `IndexedDbTabularStorage.probeObjectStoreExists`. Opens the IDB
+ * database without a version (which is the only documented way to read the
+ * existing version + object stores) and inspects `objectStoreNames`.
+ *
+ * **Side effect:** if the database does not yet exist, IDB's spec says
+ * `open(name)` *creates* it at version 1 with no object stores. The caller
+ * must be prepared to handle that — `ensureIndexedDbTable` already does, by
+ * deleting and recreating the empty DB before bumping its version.
+ */
+export declare function idbObjectStoreExists(dbName: string, storeName: string): Promise<boolean>;
+/**
+ * IndexedDB applier for tabular migrations.
+ *
+ * Op handling matches `InMemoryTabularMigrationApplier`'s schemaless model
+ * (column ops are no-ops) and `SqlTabularMigrationApplier`'s SQL-backed
+ * model (DDL is real) where each makes sense:
+ *
+ *   - `addColumn` / `dropColumn` / `renameColumn` — **no-ops.** IDB stores
+ *     arbitrary JS objects, so there is no schema to evolve. Authors who
+ *     need to populate or rewrite a property on existing rows must pair
+ *     the column op with an explicit `backfill` op (which runs on every
+ *     backend, including SQL, where the backfill is in addition to the
+ *     real ALTER TABLE). This keeps a single migration spec portable
+ *     across backends.
+ *   - `addIndex` / `dropIndex` — **real DDL.** Run inside an upgrade
+ *     transaction issued by {@link IndexedDbMigrationRunner}, which writes
+ *     the `_storage_migrations` row in the same transaction so DDL +
+ *     bookkeeping commit atomically. `createIndex` / `deleteIndex` are
+ *     guarded by `objectStore.indexNames.contains` so a re-run does not
+ *     throw on already-existing / already-deleted indexes — mirroring
+ *     SQL's `IF NOT EXISTS` / `IF EXISTS` semantics.
+ *   - `backfill` — runs on a **separate** readwrite transaction *before*
+ *     the upgrade tx, because IDB upgrade transactions cannot span async
+ *     work. This means the backfill and the bookkeeping write are NOT
+ *     atomic on this backend: if the upgrade tx fails after a partial
+ *     backfill, the row mutations persist while no `(component, version)`
+ *     row is written, and the next run re-invokes `transform()` on the
+ *     already-mutated rows. **Backfill `transform`s on this applier MUST
+ *     therefore be idempotent.** SQL backends wrap everything in
+ *     `withTransaction` and do not have this requirement.
+ *
+ * Order of execution within a single migration: backfill first, then DDL.
+ * This means a `[backfill, addIndex]` pair sees the new index applied to
+ * the rewritten rows; the reverse order (`[addIndex, backfill]`) would
+ * still execute backfill first because the runner buffers DDL until the
+ * upgrade tx.
+ */
+export declare class IndexedDbTabularMigrationApplier implements ITabularMigrationApplier {
+    private readonly dbName;
+    private readonly storeName;
+    private readonly storage;
+    private readonly runner;
+    constructor(dbName: string, storeName: string, storage: BackfillCapableStorage, runner?: IndexedDbMigrationRunner);
+    ensureBookkeeping(): Promise<void>;
+    appliedVersions(component: string): Promise<Set<number>>;
+    tableExists(): Promise<boolean>;
+    markAllApplied(component: string, versions: ReadonlyArray<{
+        version: number;
+        description: string | undefined;
+    }>): Promise<void>;
+    applyMigration(component: string, version: number, description: string | undefined, ops: ReadonlyArray<TabularMigrationOp>, onProgress?: (fraction: number) => void): Promise<void>;
+}
+export {};
+//# sourceMappingURL=IndexedDbTabularMigrationApplier.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IndexedDbTabularMigrationApplier.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDbTabularMigrationApplier.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,wBAAwB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,EACL,wBAAwB,EAEzB,MAAM,wCAAwC,CAAC;AAEhD,UAAU,sBAAsB;IAC9B,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC;QAC/D,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACtC,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,CAAC,CAAC;IACH,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACxD,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAe9F;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,gCAAiC,YAAW,wBAAwB;IAG7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,YACmB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,sBAAsB,EAChD,MAAM,CAAC,EAAE,wBAAwB,EAGlC;IAEK,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAEvC;IAEK,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAE7D;IAEK,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAEpC;IAEK,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,aAAa,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC,GAC5E,OAAO,CAAC,IAAI,CAAC,CAUf;IAEK,cAAc,CAClB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,GAAG,EAAE,aAAa,CAAC,kBAAkB,CAAC,EACtC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC,CA2Ff;CACF"}

package/dist/storage/IndexedDbTabularStorage.d.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { DataPortSchemaObject, FromSchema, TypedArraySchemaOptions } from "@workglow/util/schema";
-import { BaseTabularStorage, ClientProvidedKeysOption, KeyGenerationStrategy, AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularSubscribeOptions } from "@workglow/storage";
+import { BaseTabularStorage, ClientProvidedKeysOption, KeyGenerationStrategy, AnyTabularStorage, AutoGeneratedKeys, CoveringIndexQueryOptions, DeleteSearchCriteria, InsertEntity, QueryOptions, SearchCriteria, SimplifyPrimaryKey, TabularChangePayload, TabularSubscribeOptions, type ITabularMigration, type ITabularMigrationApplier } from "@workglow/storage";
 import { MigrationOptions } from "./IndexedDbTable";
 export declare const IDB_TABULAR_REPOSITORY: import("@workglow/util").ServiceToken<AnyTabularStorage>;
 /**
@@ -17,6 +17,15 @@ export declare class IndexedDbTabularStorage<Schema extends DataPortSchemaObject
     table: string;
     /** Promise that resolves to the IndexedDB database instance */
     private db;
+    /**
+     * True between `setupDatabase`'s call to `applyTabularMigrations` and its
+     * completion. Backfill ops inside the orchestrator may close `this.db`
+     * (via `onversionchange` from the next migration's upgrade) and trigger
+     * a re-entrant `setupDatabase` call from `getDb()`. The re-entrant call
+     * must only re-open the IDB connection — it MUST NOT recurse into the
+     * orchestrator, or migrations will be replayed mid-flight.
+     */
+    private applyingMigrations;
     /** Promise to track ongoing database setup to prevent concurrent setup calls */
     private setupPromise;
     /** Migration options for database schema changes */
@@ -46,14 +55,24 @@ export declare class IndexedDbTabularStorage<Schema extends DataPortSchemaObject
     constructor(table: string | undefined, schema: Schema, primaryKeyNames: PrimaryKeyNames, indexes?: readonly (keyof NoInfer<Entity> | readonly (keyof NoInfer<Entity>)[])[], migrationOptions?: MigrationOptions & {
         readonly useBroadcastChannel?: boolean;
         readonly backupPollingIntervalMs?: number;
-    }, clientProvidedKeys?: ClientProvidedKeysOption);
+    }, clientProvidedKeys?: ClientProvidedKeysOption, tabularMigrations?: ReadonlyArray<ITabularMigration>);
     private getDb;
     /**
      * Sets up the IndexedDB database table with the required schema and indexes.
      * Must be called before using any other methods.
      */
     setupDatabase(): Promise<void>;
+    /**
+     * Wires `onversionchange` so that when the migration runner bumps the IDB
+     * version (currentVersion + 1 to trigger onupgradeneeded), the current
+     * open connection is both closed AND cleared from `this.db`. Without the
+     * clear, getDb() would return a stale closed connection and throw
+     * InvalidStateError on the next transaction attempt (e.g. during backfill).
+     */
+    private rewireOnVersionChange;
+    private probeObjectStoreExists;
     private performSetup;
+    getMigrationApplier(): ITabularMigrationApplier | null;
     /**
      * Generates a key value for UUID keys
      * Integer autoincrement keys are handled by IndexedDB's autoIncrement

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

@@ -1 +1 @@
-{"version":3,"file":"IndexedDbTabularStorage.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDbTabularStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"IndexedDbTabularStorage.d.ts","sourceRoot":"","sources":["../../src/storage/IndexedDbTabularStorage.ts"],"names":[],"mappings":"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"}