@scalar/workspace-store 0.47.0 → 0.48.0

package/dist/persistence/indexdb.d.ts

@@ -1,70 +1,90 @@
 import type { Static, TObject } from '@scalar/typebox';
+/**
+ * Declarative shape for a table at its CURRENT (latest) version.
+ *
+ * This is used purely for TypeScript typing and runtime key serialization in
+ * the wrapper API returned by `get(name)`. IndexedDB schema (object stores,
+ * keyPaths, indexes) is NOT derived from this config — every schema change is
+ * expressed in a migration. That keeps fresh installs and upgraded installs on
+ * exactly the same code path and makes the TypeScript types safe to evolve
+ * without accidentally reshaping the underlying database.
+ */
 type TableEntry<S extends TObject, K extends readonly (keyof Static<S>)[]> = {
     schema: S;
     keyPath: K;
-    indexes?: Record<string, readonly (keyof Static<S>)[]>;
 };
 /**
- * Initializes and manages an IndexedDB database connection for table-based persistence.
+ * Context passed to every migration. The upgrade `transaction` lives for as
+ * long as any IDB request on it is pending, so migrations may schedule async
+ * cursor / getAll work and still mutate the same transaction afterwards.
+ */
+export type MigrationContext = {
+    db: IDBDatabase;
+    transaction: IDBTransaction;
+    oldVersion: number;
+    newVersion: number;
+};
+/**
+ * A single, atomic schema (and/or data) change.
  *
- * @param name - The database name. Defaults to 'scalar-workspace-store'.
- * @param tables - Table definitions: the tables to create and their key schemas.
- * @param version - The database version. Bump this to trigger upgrades (default: 1).
- * @param migrations - Optional migration steps to run for version upgrades.
- * @returns An object with the following methods:
- *   - `get(tableName)` — Get a wrapper to interact with the object store for the given table name.
- *   - `closeDatabase()` — Closes the database connection.
+ * Every structural change to the database — creating an object store, adding
+ * or removing an index, renaming a field, re-keying records — lives inside a
+ * migration. Fresh installs run the full chain from v1 up; existing installs
+ * run only the migrations whose position is past their current version.
  *
- * Example usage:
- * ```ts
- * import { Type } from '@scalar/typebox'
- * import { createIndexDbConnection } from './indexdb.js'
+ * The version of a migration is its 1-based position in the `migrations`
+ * array passed to `createIndexDbConnection` — there is no `version` field to
+ * keep in sync. Append to the end to add a new migration; never reorder or
+ * insert in the middle (each position represents a real schema state that
+ * shipped to users).
  *
- * // Define a schema for a user
- * const UserSchema = Type.Object({
- *   id: Type.String(),
- *   name: Type.String(),
- *   age: Type.Number(),
- * })
+ * Migrations may run synchronously, or may return a Promise when they need
+ * to read existing data (via `getAll`, cursors, ...) before performing schema
+ * changes. The runner awaits each migration before starting the next, so a
+ * later migration always observes the fully-applied state of every earlier
+ * migration. To keep the upgrade transaction alive across awaits, every async
+ * migration must queue at least one IDB request before yielding.
+ */
+export type Migration = {
+    /** Short human-readable summary surfaced in errors / logs. */
+    description?: string;
+    /** Runs inside the upgrade transaction. May be sync or async. */
+    up: (context: MigrationContext) => void | Promise<void>;
+};
+/**
+ * Initializes and manages an IndexedDB database connection for table-based persistence.
  *
- * // Define tables in the database
- * const dbConfig = {
- *   users: {
- *     schema: UserSchema,
- *     index: ['id'] as const,
- *   },
- * }
+ * The database version is derived from `migrations.length`, so callers cannot
+ * accidentally drift between the declared version and the migrations that
+ * define it. Every structural change — including the initial schema — must
+ * be expressed as a migration; append new ones to the end of the array.
  *
- * // Open the database connection and get table API
- * const { get, closeDatabase } = await createIndexDbConnection({
+ * Example:
+ * ```ts
+ * const connection = await createIndexDbConnection({
  *   name: 'my-app-db',
- *   tables: dbConfig,
- *   version: 1,
+ *   tables: {
+ *     users: { schema: UserSchema, keyPath: ['id'] as const },
+ *   },
+ *   migrations: [
+ *     {
+ *       description: 'Initial schema',
+ *       up: ({ db }) => {
+ *         if (!db.objectStoreNames.contains('users')) {
+ *           db.createObjectStore('users', { keyPath: 'id' })
+ *         }
+ *       },
+ *     },
+ *   ],
  * })
- *
- * // Get a strongly-typed users table API
- * const usersTable = get('users')
- *
- * // Add a user
- * await usersTable.addItem({ id: 'user-1' }, { name: 'Alice', age: 25 })
- *
- * // Retrieve a user by id
- * const user = await usersTable.getItem({ id: 'user-1' })
- *
- * // Don't forget to close the database when done!
- * closeDatabase()
  * ```
  */
-export declare const createIndexDbConnection: <T extends Record<string, TableEntry<any, readonly (keyof any)[]>>>({ name, tables, version, migrations, }: {
+export declare const createIndexDbConnection: <T extends Record<string, TableEntry<any, readonly (keyof any)[]>>>({ name, tables, migrations, }: {
     name: string;
     tables: T;
-    version: number;
-    migrations?: {
-        version: number;
-        exec: (db: IDBDatabase, event: IDBVersionChangeEvent) => {};
-    }[];
+    migrations: readonly Migration[];
 }) => Promise<{
-    get: <Name extends keyof T>(name: Name) => {
+    get: <Name extends keyof T>(tableName: Name) => {
         addItem: (key: Record<T[Name]["keyPath"][number], IDBValidKey>, value: Omit<(T[Name]["schema"] & {
             params: [];
         })["static"], T[Name]["keyPath"][number]>) => Promise<(T[Name]["schema"] & {

package/dist/persistence/indexdb.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"indexdb.d.ts","sourceRoot":"","sources":["../../src/persistence/indexdb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAW,MAAM,iBAAiB,CAAA;AAE/D,KAAK,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,SAAS,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI;IAC3E,MAAM,EAAE,CAAC,CAAA;IACT,OAAO,EAAE,CAAC,CAAA;IACV,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;CACvD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,uBAAuB,GAAU,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,wCAK9G;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,CAAC,CAAA;IACT,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,qBAAqB,KAAK,EAAE,CAAA;KAAE,EAAE,CAAA;CAChG;UAqCS,IAAI,SAAS,MAAM,CAAC,QAAQ,IAAI;;;;;;;;;+BA8FV,WAAW,EAAE,cAAc,MAAM;;;8EA+BP,OAAO,CAAC,IAAI,CAAC;kCAmBpC,WAAW,EAAE,KAAG,OAAO,CAAC,MAAM,CAAC;;;;yBA6BpC,OAAO,CAAC,IAAI,CAAC;;;EAtK1C,CAAA"}
+{"version":3,"file":"indexdb.d.ts","sourceRoot":"","sources":["../../src/persistence/indexdb.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAW,MAAM,iBAAiB,CAAA;AAE/D;;;;;;;;;GASG;AACH,KAAK,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,SAAS,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI;IAC3E,MAAM,EAAE,CAAC,CAAA;IACT,OAAO,EAAE,CAAC,CAAA;CACX,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,WAAW,CAAA;IACf,WAAW,EAAE,cAAc,CAAA;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,iEAAiE;IACjE,EAAE,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxD,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,uBAAuB,GAAU,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,+BAI9G;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,CAAC,CAAA;IACT,UAAU,EAAE,SAAS,SAAS,EAAE,CAAA;CACjC;UAuFS,IAAI,SAAS,MAAM,CAAC,aAAa,IAAI;;;;;;;;;+BAiEf,WAAW,EAAE,cAAc,MAAM;;;8EA6BP,OAAO,CAAC,IAAI,CAAC;kCAWpC,WAAW,EAAE,KAAG,OAAO,CAAC,MAAM,CAAC;;;;yBA4BpC,OAAO,CAAC,IAAI,CAAC;;;EAxH1C,CAAA"}

package/dist/persistence/indexdb.js

@@ -1,127 +1,123 @@
 /**
  * Initializes and manages an IndexedDB database connection for table-based persistence.
  *
- * @param name - The database name. Defaults to 'scalar-workspace-store'.
- * @param tables - Table definitions: the tables to create and their key schemas.
- * @param version - The database version. Bump this to trigger upgrades (default: 1).
- * @param migrations - Optional migration steps to run for version upgrades.
- * @returns An object with the following methods:
- *   - `get(tableName)` — Get a wrapper to interact with the object store for the given table name.
- *   - `closeDatabase()` — Closes the database connection.
+ * The database version is derived from `migrations.length`, so callers cannot
+ * accidentally drift between the declared version and the migrations that
+ * define it. Every structural change — including the initial schema — must
+ * be expressed as a migration; append new ones to the end of the array.
  *
- * Example usage:
+ * Example:
  * ```ts
- * import { Type } from '@scalar/typebox'
- * import { createIndexDbConnection } from './indexdb.js'
- *
- * // Define a schema for a user
- * const UserSchema = Type.Object({
- *   id: Type.String(),
- *   name: Type.String(),
- *   age: Type.Number(),
- * })
- *
- * // Define tables in the database
- * const dbConfig = {
- *   users: {
- *     schema: UserSchema,
- *     index: ['id'] as const,
- *   },
- * }
- *
- * // Open the database connection and get table API
- * const { get, closeDatabase } = await createIndexDbConnection({
+ * const connection = await createIndexDbConnection({
  *   name: 'my-app-db',
- *   tables: dbConfig,
- *   version: 1,
+ *   tables: {
+ *     users: { schema: UserSchema, keyPath: ['id'] as const },
+ *   },
+ *   migrations: [
+ *     {
+ *       description: 'Initial schema',
+ *       up: ({ db }) => {
+ *         if (!db.objectStoreNames.contains('users')) {
+ *           db.createObjectStore('users', { keyPath: 'id' })
+ *         }
+ *       },
+ *     },
+ *   ],
  * })
- *
- * // Get a strongly-typed users table API
- * const usersTable = get('users')
- *
- * // Add a user
- * await usersTable.addItem({ id: 'user-1' }, { name: 'Alice', age: 25 })
- *
- * // Retrieve a user by id
- * const user = await usersTable.getItem({ id: 'user-1' })
- *
- * // Don't forget to close the database when done!
- * closeDatabase()
  * ```
  */
-export const createIndexDbConnection = async ({ name = 'scalar-workspace-store', tables, version = 1, migrations = [], }) => {
-    const db = indexedDB.open(name, version);
-    db.onupgradeneeded = (e) => {
-        // Initial setup of object stores
-        if (e.oldVersion < 1) {
-            const database = db.result;
-            // Initialize all the tables
-            Object.entries(tables).forEach(([name, options]) => {
-                if (!database.objectStoreNames.contains(name)) {
-                    const objectStore = database.createObjectStore(name, {
-                        keyPath: options.keyPath.length === 1 ? options.keyPath[0] : options.keyPath,
-                    });
-                    // Create any indexes for the object store
-                    Object.entries(options.indexes ?? {}).forEach(([indexName, indexPath]) => {
-                        objectStore.createIndex(indexName, indexPath);
-                    });
-                }
-            });
+export const createIndexDbConnection = async ({ name = 'scalar-workspace-store', tables, migrations, }) => {
+    if (migrations.length === 0) {
+        throw new Error(`createIndexDbConnection("${name}"): at least one migration is required. The initial schema must be defined as the first migration.`);
+    }
+    // The 1-based array position is the schema version. `migrations[0]` is v1,
+    // `migrations[1]` is v2, and so on. The latest version is just the length.
+    const latestVersion = migrations.length;
+    const request = indexedDB.open(name, latestVersion);
+    // Captured here so the descriptive error from a failing migration can be
+    // surfaced through the `open` promise instead of the generic IDB
+    // `AbortError` that follows `transaction.abort()`.
+    let migrationError;
+    request.onupgradeneeded = (event) => {
+        const transaction = request.transaction;
+        if (!transaction) {
+            // IDB always provides the upgrade transaction here; this is a guard for
+            // exotic environments and keeps types honest.
+            return;
         }
-        // Run any future migrations here
-        migrations.forEach((migration) => {
-            if (e.oldVersion < migration.version) {
-                migration.exec(db.result, e);
+        const context = {
+            db: request.result,
+            transaction,
+            oldVersion: event.oldVersion,
+            newVersion: event.newVersion ?? latestVersion,
+        };
+        // Run pending migrations sequentially, awaiting any async work before
+        // starting the next one. This is important when a migration reads
+        // existing data via IDB requests (e.g. `getAll`) and only performs the
+        // real schema changes inside the request callback — the next migration
+        // would otherwise execute against the pre-migration state.
+        //
+        // The upgrade transaction stays alive across awaits because every async
+        // migration in the codebase queues at least one IDB request before
+        // yielding, and microtasks complete before IDB checks for transaction
+        // commit at the next task boundary.
+        const runMigrations = async () => {
+            for (const [index, migration] of migrations.entries()) {
+                const version = index + 1;
+                if (version <= event.oldVersion) {
+                    continue;
+                }
+                try {
+                    await migration.up(context);
+                }
+                catch (error) {
+                    const label = migration.description ? `v${version} (${migration.description})` : `v${version}`;
+                    throw new Error(`Migration ${label} failed: ${error?.message ?? error}`, { cause: error });
+                }
+            }
+        };
+        runMigrations().catch((error) => {
+            migrationError = error;
+            // Abort the upgrade transaction so we do not leave the DB in a half-
+            // migrated state. Aborting fires `request.onerror`; the captured
+            // `migrationError` takes precedence over the resulting `AbortError`.
+            try {
+                transaction.abort();
+            }
+            catch {
+                // The transaction may already be in a finished state (e.g. when the
+                // failing migration itself triggered an abort). Nothing to do.
             }
         });
     };
     await new Promise((resolve, reject) => {
-        db.onsuccess = () => resolve(true);
-        db.onerror = () => reject(db.error);
+        request.onsuccess = () => resolve(true);
+        request.onerror = () => reject(migrationError ?? request.error);
+        // If another tab holds an older-version connection open we would otherwise
+        // hang forever waiting for the upgrade. Surface it as a clear rejection so
+        // the app can react (reload, notify the user, ...) instead of freezing.
+        request.onblocked = () => reject(new Error(`IndexedDB upgrade for "${name}" is blocked by another open connection. Close other tabs and try again.`));
     });
     return {
-        get: (name) => {
-            return createTableWrapper(name, db.result);
+        get: (tableName) => {
+            // Surface a helpful error if a caller asks for a table that is not in
+            // the typed config — the underlying IDB call would otherwise throw a
+            // generic `NotFoundError` from a lazy `transaction()`.
+            if (!Object.hasOwn(tables, tableName)) {
+                throw new Error(`Unknown table "${String(tableName)}". Add it to the \`tables\` config of "${name}".`);
+            }
+            return createTableWrapper(tableName, request.result);
         },
         closeDatabase: () => {
-            db.result.close();
+            request.result.close();
         },
     };
 };
 /**
  * Utility wrapper for interacting with an IndexedDB object store, typed by the schema.
  *
- * Usage example:
- * ```
- * // Define a TypeBox schema for users
- * const UserSchema = Type.Object({
- *   id: Type.String(),
- *   name: Type.String(),
- *   age: Type.Number(),
- * })
- *
- * // Open or create the users table
- * const usersTable = createTableWrapper<typeof UserSchema, 'id'>('users', openDatabase)
- *
- * // Add a user
-  await usersTable.addItem({ id: 'user-1' }, { name: 'Alice', age: 24 })
- *
- * // Get a user by id
- * const alic = await usersTable.getItem({ id: 'user-1' })
- *
- * // Get users with a partial key (use [] if no composite key)
- * const users = await usersTable.getRange(['user-1'])
- *
- * // Get all users
- * const allUsers = await usersTable.getAll()
- * ```
- *
  * @template T TypeBox schema type for objects in the store
  * @template K Key property names that compose the primary key
- *
- * @param name - Object store name
- * @param getDb - Function returning a Promise for the IDBDatabase
- * @returns Methods to interact with the object store
  */
 function createTableWrapper(name, db) {
     /**
@@ -159,12 +155,6 @@ function createTableWrapper(name, db) {
      * Returns all records matching a partial (prefix) key. Use for composite keys.
      * For non-compound keys, pass single-element array: getRange(['some-id'])
      * For prefix search, pass subset of key parts.
-     * @param partialKey - Array of partial key values
-     * @returns Matching objects
-     *
-     * Example (composite [a,b]):
-     *   getRange(['foo']) // All with a === 'foo'
-     *   getRange(['foo', 'bar']) // All with a === 'foo' and b === 'bar'
      */
     function getRange(partialKey, indexName) {
         const store = getStore('readonly');
@@ -175,9 +165,9 @@ function createTableWrapper(name, db) {
         upperBound.push([]); // ensures upper bound includes all keys with this prefix
         const range = IDBKeyRange.bound(partialKey, upperBound, false, true);
         return new Promise((resolve, reject) => {
-            const request = objectStoreOrIndex.openCursor(range);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = (event) => {
+            const req = objectStoreOrIndex.openCursor(range);
+            req.onerror = () => reject(req.error);
+            req.onsuccess = (event) => {
                 const cursor = event.target.result;
                 if (cursor) {
                     results.push(cursor.value);
@@ -191,8 +181,6 @@ function createTableWrapper(name, db) {
     }
     /**
      * Deletes an item from the store by its composite key.
-     * @param key - Key values. For a single key: { id: '...' }
-     * @returns void
      */
     async function deleteItem(key) {
         const store = getStore('readwrite');
@@ -203,14 +191,6 @@ function createTableWrapper(name, db) {
     }
     /**
      * Deletes all records matching a partial (prefix) key. Use for composite keys.
-     * For non-compound keys, pass single-element array: deleteRange(['some-id'])
-     * For prefix deletion, pass subset of key parts.
-     * @param partialKey - Array of partial key values
-     * @returns Number of deleted items
-     *
-     * Example (composite [a,b]):
-     *   deleteRange(['foo']) // Delete all with a === 'foo'
-     *   deleteRange(['foo', 'bar']) // Delete all with a === 'foo' and b === 'bar'
      */
     function deleteRange(partialKey) {
         const store = getStore('readwrite');
@@ -220,9 +200,9 @@ function createTableWrapper(name, db) {
         upperBound.push([]); // ensures upper bound includes all keys with this prefix
         const range = IDBKeyRange.bound(partialKey, upperBound, false, true);
         return new Promise((resolve, reject) => {
-            const request = store.openCursor(range);
-            request.onerror = () => reject(request.error);
-            request.onsuccess = (event) => {
+            const req = store.openCursor(range);
+            req.onerror = () => reject(req.error);
+            req.onsuccess = (event) => {
                 const cursor = event.target.result;
                 if (cursor) {
                     cursor.delete();
@@ -237,7 +217,6 @@ function createTableWrapper(name, db) {
     }
     /**
      * Deletes all items from the table.
-     * @returns void
      */
     async function deleteAll() {
         const store = getStore('readwrite');
@@ -245,7 +224,6 @@ function createTableWrapper(name, db) {
     }
     /**
      * Retrieves all items from the table.
-     * @returns Array of all objects in the store
      */
     function getAll() {
         const store = getStore('readonly');
@@ -261,7 +239,6 @@ function createTableWrapper(name, db) {
         deleteAll,
     };
 }
-// ---- Utility ----
 function requestAsPromise(req) {
     return new Promise((resolve, reject) => {
         req.onsuccess = () => resolve(req.result);

package/dist/persistence/migrations/v1-initial.d.ts

@@ -0,0 +1,19 @@
+import type { Migration } from '../../persistence/indexdb.js';
+/**
+ * v1 — initial schema for the workspace store.
+ *
+ * This migration defines the database as it first shipped: a `workspace`
+ * object store keyed by `[namespace, slug]` with a `teamUid` index, a `meta`
+ * store keyed by `workspaceId`, and six per-document chunk stores keyed by
+ * `[workspaceId, documentName]`.
+ *
+ * Every installation — fresh or upgraded — runs this migration. Fresh installs
+ * execute the full chain starting here, then each subsequent migration
+ * transforms the schema into the latest shape. Upgraded installs are already
+ * past v1 and skip it.
+ *
+ * Intentionally uses the ORIGINAL field names (including `teamUid`); later
+ * migrations are free to rename, drop, or reshape them.
+ */
+export declare const v1InitialMigration: Migration;
+//# sourceMappingURL=v1-initial.d.ts.map

package/dist/persistence/migrations/v1-initial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1-initial.d.ts","sourceRoot":"","sources":["../../../src/persistence/migrations/v1-initial.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AAmBtD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAoBhC,CAAA"}

package/dist/persistence/migrations/v1-initial.js

@@ -0,0 +1,50 @@
+/**
+ * Tables that store per-workspace chunks keyed by `workspaceId` (single key).
+ */
+const SINGLE_KEY_CHUNK_TABLES = ['meta'];
+/**
+ * Tables that store per-document chunks keyed by `[workspaceId, documentName]`.
+ */
+const COMPOSITE_KEY_CHUNK_TABLES = [
+    'documents',
+    'originalDocuments',
+    'intermediateDocuments',
+    'overrides',
+    'history',
+    'auth',
+];
+/**
+ * v1 — initial schema for the workspace store.
+ *
+ * This migration defines the database as it first shipped: a `workspace`
+ * object store keyed by `[namespace, slug]` with a `teamUid` index, a `meta`
+ * store keyed by `workspaceId`, and six per-document chunk stores keyed by
+ * `[workspaceId, documentName]`.
+ *
+ * Every installation — fresh or upgraded — runs this migration. Fresh installs
+ * execute the full chain starting here, then each subsequent migration
+ * transforms the schema into the latest shape. Upgraded installs are already
+ * past v1 and skip it.
+ *
+ * Intentionally uses the ORIGINAL field names (including `teamUid`); later
+ * migrations are free to rename, drop, or reshape them.
+ */
+export const v1InitialMigration = {
+    description: 'Initial schema: workspace + chunk tables',
+    up: ({ db }) => {
+        if (!db.objectStoreNames.contains('workspace')) {
+            const workspace = db.createObjectStore('workspace', { keyPath: ['namespace', 'slug'] });
+            workspace.createIndex('teamUid', ['teamUid']);
+        }
+        for (const tableName of SINGLE_KEY_CHUNK_TABLES) {
+            if (!db.objectStoreNames.contains(tableName)) {
+                db.createObjectStore(tableName, { keyPath: 'workspaceId' });
+            }
+        }
+        for (const tableName of COMPOSITE_KEY_CHUNK_TABLES) {
+            if (!db.objectStoreNames.contains(tableName)) {
+                db.createObjectStore(tableName, { keyPath: ['workspaceId', 'documentName'] });
+            }
+        }
+    },
+};

package/dist/persistence/migrations/v2-team-to-local.d.ts

@@ -0,0 +1,33 @@
+import type { Migration } from '../../persistence/indexdb.js';
+type WorkspaceRecordV1 = {
+    name: string;
+    /** Old field — dropped entirely in v2. */
+    teamUid?: string;
+    namespace: string;
+    slug: string;
+};
+type WorkspaceRecordV2 = {
+    name: string;
+    teamSlug: string;
+    slug: string;
+};
+/**
+ * Picks a slug that does not collide with anything in `taken`.
+ * Falls back to `<slug>-2`, `<slug>-3`, ... when the desired slug is already used.
+ */
+export declare const pickUniqueSlug: (desired: string, taken: ReadonlySet<string>) => string;
+/**
+ * Computes the new shape for every workspace, preserving local entries under
+ * their existing slug and relocating team entries into the local team with a
+ * unique slug when needed.
+ */
+export declare const planWorkspaceMigration: (workspaces: readonly WorkspaceRecordV1[]) => Array<{
+    before: {
+        namespace: string;
+        slug: string;
+    };
+    after: WorkspaceRecordV2;
+}>;
+export declare const v2TeamToLocalMigration: Migration;
+export {};
+//# sourceMappingURL=v2-team-to-local.d.ts.map

package/dist/persistence/migrations/v2-team-to-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2-team-to-local.d.ts","sourceRoot":"","sources":["../../../src/persistence/migrations/v2-team-to-local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AA2CtD,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,iBAAiB,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,OAAO,WAAW,CAAC,MAAM,CAAC,KAAG,MAU5E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GACjC,YAAY,SAAS,iBAAiB,EAAE,KACvC,KAAK,CAAC;IAAE,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,CAqCjF,CAAA;AAqHD,eAAO,MAAM,sBAAsB,EAAE,SAqCpC,CAAA"}