@scalar/workspace-store 0.49.3 → 0.51.0

package/dist/persistence/index.d.ts

@@ -1,134 +1,177 @@
 import type { PathMethodHistory } from '../entities/history/schema.js';
 import type { InMemoryWorkspace } from '../schemas/inmemory-workspace.js';
 import type { WorkspaceMeta } from '../schemas/workspace.js';
-type WorkspaceKey = {
+/**
+ * Lookup key for fetching a workspace by its URL slugs. Both `teamSlug` and
+ * `slug` are mutable metadata — they map to a stable `workspaceUid` via the
+ * `teamSlug_slug` unique index. `teamSlug` defaults to `'local'` so personal
+ * workspaces can omit it.
+ */
+type WorkspaceSlugKey = {
     teamSlug?: string;
     slug: string;
 };
+/**
+ * Full record written to the workspace object store. `workspaceUid` is the
+ * primary key and is the only identifier that survives slug renames.
+ */
+type WorkspaceRecord = {
+    workspaceUid: string;
+    teamUid: string;
+    teamSlug: string;
+    slug: string;
+    name: string;
+};
 type WorkspaceStoreShape = {
     name: string;
     workspace: InMemoryWorkspace;
 };
 /**
- * Generates a workspace ID from team slug and workspace slug. Used as the key
- * in the per-workspace chunk tables (meta, documents, ...).
+ * Generates a fresh `workspaceUid` for new workspaces.
+ *
+ * Wraps `crypto.randomUUID` so every caller produces UIDs in a consistent
+ * shape and we can swap the implementation later without rippling through
+ * the codebase.
  */
-export declare const getWorkspaceId: (teamSlug: string, slug: string) => string;
+export declare const generateWorkspaceUid: () => string;
 /**
  * Creates the persistence layer for the workspace store using IndexedDB.
- * This sets up all the required tables for storing workspace chunk information,
- * such as workspace meta, documents, original documents, intermediate documents, overrides, etc.
- * Each logical group (meta, documents, etc) gets its own table keyed appropriately for efficient sub-document access.
- * Returns an object containing `meta`, `documents`, `originalDocuments`, `intermediateDocuments`, `overrides`,
- * `documentMeta`, `documentConfigs`, and `workspace` sections, each exposing a `setItem` method
- * for upsetting records, and in the case of `workspace`, also `getItem` and `deleteItem`.
+ *
+ * Storage model:
+ * - `workspace` is the catalog. Its primary key is `workspaceUid`, a
+ *   stable UUID that does not change when the user (or the server)
+ *   renames the team or workspace slug. Two indexes back the runtime:
+ *     - `teamSlug_slug` (unique) for slug-based URL lookups.
+ *     - `teamUid` for team-scoped queries.
+ * - Every chunk table (`meta`, `documents`, ...) is keyed by
+ *   `workspaceUid` so chunks survive slug renames without ever being
+ *   re-keyed.
  */
 export declare const createWorkspaceStorePersistence: () => Promise<{
     close: () => void;
     meta: {
         /**
-         * Set meta data for a workspace.
+         * Loads persisted workspace meta only (no document or other chunk
+         * reads). Returns an empty object when no meta row exists yet.
          */
-        setItem: (workspaceId: string, data: WorkspaceMeta) => Promise<void>;
+        getItem: (workspaceUid: string) => Promise<InMemoryWorkspace["meta"]>;
+        /** Set meta data for a workspace. */
+        setItem: (workspaceUid: string, data: WorkspaceMeta) => Promise<void>;
     };
     documents: {
-        /**
-         * Set (persist) a workspace document using workspaceId and documentName as composite key.
-         */
-        setItem: (workspaceId: string, documentName: string, data: InMemoryWorkspace["documents"][string]) => Promise<void>;
+        /** Set (persist) a workspace document using workspaceUid and documentName as composite key. */
+        setItem: (workspaceUid: string, documentName: string, data: InMemoryWorkspace["documents"][string]) => Promise<void>;
     };
     originalDocuments: {
-        /**
-         * Set an original (raw) document for a workspace/document pair.
-         */
-        setItem: (workspaceId: string, documentName: string, data: InMemoryWorkspace["originalDocuments"][string]) => Promise<void>;
+        /** Set an original (raw) document for a workspace/document pair. */
+        setItem: (workspaceUid: string, documentName: string, data: InMemoryWorkspace["originalDocuments"][string]) => Promise<void>;
     };
     intermediateDocuments: {
-        /**
-         * Set an intermediate (transformed) document for a workspace/document pair.
-         */
-        setItem: (workspaceId: string, documentName: string, data: InMemoryWorkspace["intermediateDocuments"][string]) => Promise<void>;
+        /** Set an intermediate (transformed) document for a workspace/document pair. */
+        setItem: (workspaceUid: string, documentName: string, data: InMemoryWorkspace["intermediateDocuments"][string]) => Promise<void>;
     };
     overrides: {
-        /**
-         * Set document overrides for a workspace/document pair.
-         */
-        setItem: (workspaceId: string, documentName: string, data: InMemoryWorkspace["overrides"][string]) => Promise<void>;
+        /** Set document overrides for a workspace/document pair. */
+        setItem: (workspaceUid: string, documentName: string, data: InMemoryWorkspace["overrides"][string]) => Promise<void>;
     };
     history: {
-        /**
-         * Set history for a document.
-         */
-        setItem: (workspaceId: string, documentName: string, data: PathMethodHistory) => Promise<void>;
+        /** Set history for a document. */
+        setItem: (workspaceUid: string, documentName: string, data: PathMethodHistory) => Promise<void>;
     };
     auth: {
-        /**
-         * Set auth for a document.
-         */
-        setItem: (workspaceId: string, documentName: string, data: InMemoryWorkspace["auth"][string]) => Promise<void>;
+        /** Set auth for a document. */
+        setItem: (workspaceUid: string, documentName: string, data: InMemoryWorkspace["auth"][string]) => Promise<void>;
     };
     workspace: {
         /**
-         * Retrieves a workspace by its team + workspace slug.
-         * Returns undefined if the workspace does not exist.
-         * Gathers all workspace 'chunk' tables and assembles a full workspace shape.
+         * Retrieves a workspace by its stable UID, returning the full
+         * assembled state (chunks included). Returns `undefined` when no
+         * workspace matches.
+         *
+         * This is the primary lookup path because the UID never changes,
+         * making it safe to cache and reference across slug renames.
          */
-        getItem: ({ teamSlug, slug, }: WorkspaceKey) => Promise<(WorkspaceStoreShape & {
-            teamSlug: string;
-            slug: string;
-        }) | undefined>;
+        getItem: (workspaceUid: string) => Promise<(WorkspaceStoreShape & WorkspaceRecord) | undefined>;
         /**
-         * Retrieves all workspaces from the database.
-         * Returns only the workspace ID and name for each workspace.
-         * To get the full workspace data including documents and metadata, use getItem() with a specific ID.
-         * Returns an empty array if no workspaces exist.
+         * Retrieves a workspace by its mutable `[teamSlug, slug]` pair.
+         *
+         * Use this when the only thing you have is the URL — for example
+         * when the router needs to resolve `/@<teamSlug>/<workspaceSlug>`
+         * back to a workspace. For all other cases, prefer `getItem(uid)`
+         * because the slugs can change at any time.
          */
-        getAll: () => Promise<{
-            name: string;
-            slug: string;
-            teamSlug: string;
-        }[]>;
+        getItemBySlug: ({ teamSlug, slug, }: WorkspaceSlugKey) => Promise<(WorkspaceStoreShape & WorkspaceRecord) | undefined>;
         /**
-         * Retrieves all workspaces for a given team slug. Uses the primary key
-         * prefix so no secondary index is required.
+         * Retrieves all workspace catalog records.
+         *
+         * Only returns the workspace shell (`workspaceUid`, `teamUid`,
+         * `teamSlug`, `slug`, `name`). To get the full workspace data
+         * including documents and metadata, use `getItem(workspaceUid)`.
          */
-        getAllByTeamSlug: (teamSlug: string) => Promise<{
-            name: string;
-            slug: string;
-            teamSlug: string;
-        }[]>;
+        getAll: () => Promise<WorkspaceRecord[]>;
+        /**
+         * Retrieves all workspaces for a given team UID. Uses the `teamUid`
+         * index, so this is O(matches) rather than a full scan.
+         *
+         * Prefer this over `getAllByTeamSlug` because the team UID is the
+         * canonical identifier and survives team-slug renames.
+         */
+        getAllByTeamUid: (teamUid: string) => Promise<WorkspaceRecord[]>;
         /**
-         * Saves a workspace to the database.
-         * All chunks (meta, documents, configs, etc.) are upsert in their respective tables.
-         * If a workspace with the same ID already exists, it will be replaced.
+         * Retrieves all workspaces for a given team slug. Uses the
+         * `teamSlug_slug` compound index as a prefix scan. Useful when the
+         * only thing on hand is the URL segment; otherwise prefer
+         * `getAllByTeamUid`.
          */
-        setItem: ({ teamSlug, slug }: WorkspaceKey, value: WorkspaceStoreShape) => Promise<{
-            name: string;
+        getAllByTeamSlug: (teamSlug: string) => Promise<WorkspaceRecord[]>;
+        /**
+         * Saves a workspace and all of its chunks. The caller is responsible
+         * for providing a stable `workspaceUid` (typically `crypto.randomUUID()`
+         * for new records, or the existing UID for updates).
+         *
+         * `teamSlug` and `slug` are validated by the underlying unique index;
+         * attempting to persist a duplicate pair will reject the transaction.
+         */
+        setItem: ({ workspaceUid, teamUid, teamSlug, slug, }: {
+            workspaceUid: string;
+            teamUid?: string;
+            teamSlug?: string;
             slug: string;
-            teamSlug: string;
-        }>;
+        }, value: WorkspaceStoreShape) => Promise<WorkspaceRecord>;
         /**
-         * Deletes an entire workspace and all associated chunk records from all tables by ID.
+         * Deletes an entire workspace and every chunk that belongs to it.
+         * Safe to call on a workspace that does not exist — the chunk
+         * deletions are range scans that simply find nothing to delete.
          */
-        deleteItem: ({ teamSlug, slug }: WorkspaceKey) => Promise<void>;
+        deleteItem: (workspaceUid: string) => Promise<void>;
         /**
-         * Deletes a single document and all related records (overrides, history, auth, etc.)
-         * for the given workspace and document name from all relevant tables.
+         * Deletes a single document and all related chunks (overrides,
+         * history, auth, ...) for the given workspace/document pair.
          */
-        deleteDocument: (workspaceId: string, documentName: string) => Promise<void>;
+        deleteDocument: (workspaceUid: string, documentName: string) => Promise<void>;
         /**
-         * Updates the name of an existing workspace.
-         * Returns the updated workspace object, or undefined if the workspace does not exist.
+         * Updates the name of an existing workspace. Returns the updated
+         * record, or `undefined` when the workspace does not exist.
          */
-        updateName: ({ teamSlug, slug }: WorkspaceKey, name: string) => Promise<{
-            name: string;
-            slug: string;
-            teamSlug: string;
-        } | undefined>;
+        updateName: (workspaceUid: string, name: string) => Promise<WorkspaceRecord | undefined>;
         /**
-         * Checks if a workspace with the given team + workspace slug exists in the store.
+         * Updates the mutable slug metadata for an existing workspace.
+         * Returns the updated record, or `undefined` when the workspace
+         * does not exist, or when another workspace already owns the target
+         * `[teamSlug, slug]` pair (the `teamSlug_slug` index is unique).
+         *
+         * Use this when the server tells us a team slug or workspace slug
+         * has changed. The `workspaceUid` stays the same, so all chunk
+         * references continue to resolve.
          */
-        has: ({ teamSlug, slug }: WorkspaceKey) => Promise<boolean>;
+        updateSlugs: (workspaceUid: string, slugs: {
+            teamSlug?: string;
+            slug?: string;
+        }) => Promise<WorkspaceRecord | undefined>;
+        /** Checks if a workspace with the given UID exists. */
+        has: (workspaceUid: string) => Promise<boolean>;
+        /** Checks if a workspace with the given `[teamSlug, slug]` pair exists. */
+        hasSlug: ({ teamSlug, slug }: WorkspaceSlugKey) => Promise<boolean>;
     };
     clear: () => Promise<void>;
 }>;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAIlE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AACrE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAExD,KAAK,YAAY,GAAG;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,mBAAmB,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,iBAAiB,CAAA;CAC7B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,MAAM,MAAM,WAA0B,CAAA;AAEvF;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B;;;QAmEtC;;WAEG;+BAC0B,MAAM,QAAQ,aAAa;;;QAKxD;;WAEG;+BAC0B,MAAM,gBAAgB,MAAM,QAAQ,iBAAiB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;;;QAKvG;;WAEG;+BAEY,MAAM,gBACL,MAAM,QACd,iBAAiB,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAAC;;;QAMtD;;WAEG;+BAEY,MAAM,gBACL,MAAM,QACd,iBAAiB,CAAC,uBAAuB,CAAC,CAAC,MAAM,CAAC;;;QAM1D;;WAEG;+BAC0B,MAAM,gBAAgB,MAAM,QAAQ,iBAAiB,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC;;;QAKvG;;WAEG;+BAC0B,MAAM,gBAAgB,MAAM,QAAQ,iBAAiB;;;QAKlF;;WAEG;+BAC0B,MAAM,gBAAgB,MAAM,QAAQ,iBAAiB,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC;;;QAKlG;;;;WAIG;uCAIA,YAAY,KAAG,OAAO,CAAC,CAAC,mBAAmB,GAAG;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,GAAG,SAAS,CAAC;QAwCjG;;;;;WAKG;;;;;;QAKH;;;WAGG;qCACgC,MAAM;;;;;QAIzC;;;;WAIG;sCAC2C,YAAY,SAAS,mBAAmB;;;;;QAyDtF;;WAEG;yCAC8C,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC;QAoB7E;;;WAGG;sCACiC,MAAM,gBAAgB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;QAWhF;;;WAGG;yCAC8C,YAAY,QAAQ,MAAM;;;;;QAU3E;;WAEG;kCACuC,YAAY,KAAG,OAAO,CAAC,OAAO,CAAC;;;EAQ9E,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/persistence/index.ts"],"names":[],"mappings":"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"}