@scalar/workspace-store 0.17.0 → 0.18.0

package/dist/client.js

@@ -1,3 +1,4 @@
+import { generateHash } from "@scalar/helpers/crypto/generate-hash";
 import { measureAsync, measureSync } from "@scalar/helpers/testing/measure";
 import { bundle } from "@scalar/json-magic/bundle";
 import { fetchUrls } from "@scalar/json-magic/bundle/plugins/browser";
@@ -5,16 +6,18 @@ import { apply, diff, merge } from "@scalar/json-magic/diff";
 import { createMagicProxy, getRaw } from "@scalar/json-magic/magic-proxy";
 import { upgrade } from "@scalar/openapi-upgrader";
 import { Value } from "@scalar/typebox/value";
-import { reactive } from "vue";
+import { reactive, toRaw } from "vue";
 import YAML from "yaml";
 import { applySelectiveUpdates } from "./helpers/apply-selective-updates.js";
 import { deepClone } from "./helpers/deep-clone.js";
+import { createDetectChangesProxy } from "./helpers/detect-changes-proxy.js";
 import { isObject, safeAssign } from "./helpers/general.js";
 import { getValueByPath } from "./helpers/json-path-utils.js";
 import { mergeObjects } from "./helpers/merge-object.js";
-import { createOverridesProxy } from "./helpers/overrides-proxy.js";
+import { createOverridesProxy, unpackOverridesProxy } from "./helpers/overrides-proxy.js";
+import { unpackProxyObject } from "./helpers/unpack-proxy.js";
 import { createNavigation } from "./navigation/index.js";
-import { externalValueResolver, loadingStatus, refsEverywhere, restoreOriginalRefs } from "./plugins.js";
+import { externalValueResolver, loadingStatus, refsEverywhere, restoreOriginalRefs } from "./plugins/bundler/index.js";
 import { getServersFromDocument } from "./preprocessing/server.js";
 import { extensions } from "./schemas/extensions.js";
 import { InMemoryWorkspaceSchema } from "./schemas/inmemory-workspace.js";
@@ -26,14 +29,16 @@ import {
 const defaultConfig = {
   "x-scalar-reference-config": defaultReferenceConfig
 };
-async function loadDocument(workspaceDocument) {
+function loadDocument(workspaceDocument) {
   if ("url" in workspaceDocument) {
     return fetchUrls({ fetch: workspaceDocument.fetch }).exec(workspaceDocument.url);
   }
-  return {
+  return Promise.resolve({
     ok: true,
-    data: workspaceDocument.document
-  };
+    data: workspaceDocument.document,
+    // string version of the raw document for hashing purposes
+    raw: JSON.stringify(workspaceDocument.document)
+  });
 }
 const getDocumentSource = (input) => {
   if ("url" in input) {
@@ -42,37 +47,176 @@ const getDocumentSource = (input) => {
   return void 0;
 };
 const createWorkspaceStore = (workspaceProps) => {
-  const originalDocuments = {};
-  const intermediateDocuments = {};
-  const documentConfigs = {};
-  const overrides = {};
-  const documentMeta = {};
   const extraDocumentConfigurations = {};
-  const workspace = reactive({
-    ...workspaceProps?.meta,
-    documents: {},
-    /**
-     * Returns the currently active document from the workspace.
-     * The active document is determined by the 'x-scalar-active-document' metadata field,
-     * falling back to the first document in the workspace if no active document is specified.
-     *
-     * @returns The active document or undefined if no document is found
-     */
-    get activeDocument() {
-      const activeDocumentKey = workspace[extensions.workspace.activeDocument] ?? Object.keys(workspace.documents)[0] ?? "";
-      return workspace.documents[activeDocumentKey];
+  const fireWorkspaceChange = (event) => {
+    workspaceProps?.plugins?.forEach((plugin) => plugin.hooks?.onWorkspaceStateChanges?.(event));
+  };
+  const workspace = reactive(
+    createDetectChangesProxy(
+      {
+        ...workspaceProps?.meta,
+        documents: {},
+        /**
+         * Returns the currently active document from the workspace.
+         * The active document is determined by the 'x-scalar-active-document' metadata field,
+         * falling back to the first document in the workspace if no active document is specified.
+         *
+         * @returns The active document or undefined if no document is found
+         */
+        get activeDocument() {
+          return workspace.documents[getActiveDocumentName()];
+        }
+      },
+      {
+        hooks: {
+          onAfterChange(path) {
+            const type = path[0];
+            if (type === "documents") {
+              if (path.length < 2) {
+                console.log("[WARN]: Overriding entire documents object is not supported");
+                return;
+              }
+              const documentName = path[1];
+              const event2 = {
+                type: "documents",
+                documentName,
+                value: unpackProxyObject(
+                  workspace.documents[documentName] ?? {
+                    openapi: "3.1.0",
+                    info: { title: "", version: "" },
+                    "x-scalar-original-document-hash": ""
+                  }
+                )
+              };
+              fireWorkspaceChange(event2);
+              return;
+            }
+            if (type === "activeDocument") {
+              const documentName = getActiveDocumentName();
+              const event2 = {
+                type: "documents",
+                documentName,
+                value: unpackProxyObject(
+                  workspace.documents[documentName] ?? {
+                    openapi: "3.1.0",
+                    info: { title: "", version: "" },
+                    "x-scalar-original-document-hash": ""
+                  }
+                )
+              };
+              fireWorkspaceChange(event2);
+              return;
+            }
+            const { activeDocument: _a, documents: _d, ...meta } = workspace;
+            const event = {
+              type: "meta",
+              value: unpackProxyObject(meta)
+            };
+            fireWorkspaceChange(event);
+            return;
+          }
+        }
+      }
+    )
+  );
+  const { originalDocuments, intermediateDocuments, overrides, documentConfigs } = createDetectChangesProxy(
+    {
+      /**
+       * Holds the original, unmodified documents as they were initially loaded into the workspace.
+       * These documents are stored in their raw form—prior to any reactive wrapping, dereferencing, or bundling.
+       * This map preserves the pristine structure of each document, using deep clones to ensure that
+       * subsequent mutations in the workspace do not affect the originals.
+       * The originals are retained so that we can restore, compare, or sync with the remote registry as needed.
+       */
+      originalDocuments: {},
+      /**
+       * Stores the intermediate state of documents after local edits but before syncing with the remote registry.
+       *
+       * This map acts as a local "saved" version of the document, reflecting the user's changes after they hit "save".
+       * The `originalDocuments` map, by contrast, always mirrors the document as it exists in the remote registry.
+       *
+       * Use this map to stage local changes that are ready to be propagated back to the remote registry.
+       * This separation allows us to distinguish between:
+       *   - The last known remote version (`originalDocuments`)
+       *   - The latest locally saved version (`intermediateDocuments`)
+       *   - The current in-memory (possibly unsaved) workspace document (`workspace.documents`)
+       */
+      intermediateDocuments: {},
+      /**
+       * A map of document configurations keyed by document name.
+       * This stores the configuration options for each document in the workspace,
+       * allowing for document-specific settings like navigation options, appearance,
+       * and other reference configuration.
+       */
+      documentConfigs: {},
+      /**
+       * Stores per-document overrides for OpenAPI documents.
+       * This object is used to override specific fields of a document
+       * when you cannot (or should not) modify the source document directly.
+       * For example, this enables UI-driven or temporary changes to be applied
+       * on top of the original document, without mutating the source.
+       * The key is the document name, and the value is a deep partial
+       * OpenAPI document representing the overridden fields.
+       */
+      overrides: {}
+    },
+    {
+      hooks: {
+        onAfterChange(path) {
+          const type = path[0];
+          if (!type) {
+            return;
+          }
+          if (path.length < 2) {
+            return;
+          }
+          const documentName = path[1];
+          if (type === "originalDocuments") {
+            const event = {
+              type,
+              documentName,
+              value: unpackProxyObject(originalDocuments[documentName] ?? {})
+            };
+            fireWorkspaceChange(event);
+          }
+          if (type === "intermediateDocuments") {
+            const event = {
+              type,
+              documentName,
+              value: unpackProxyObject(intermediateDocuments[documentName] ?? {})
+            };
+            fireWorkspaceChange(event);
+          }
+          if (type === "documentConfigs") {
+            const event = {
+              type,
+              documentName,
+              value: unpackProxyObject(documentConfigs[documentName] ?? {})
+            };
+            fireWorkspaceChange(event);
+          }
+          if (type === "overrides") {
+            const event = {
+              type,
+              documentName,
+              value: unpackProxyObject(overrides[documentName] ?? {})
+            };
+            fireWorkspaceChange(event);
+          }
+        }
+      }
     }
-  });
+  );
   function getActiveDocumentName() {
     return workspace[extensions.workspace.activeDocument] ?? Object.keys(workspace.documents)[0] ?? "";
   }
-  function exportDocument(documentName, format) {
+  function exportDocument(documentName, format, minify) {
     const intermediateDocument = intermediateDocuments[documentName];
     if (!intermediateDocument) {
       return;
     }
     if (format === "json") {
-      return JSON.stringify(intermediateDocument);
+      return minify ? JSON.stringify(intermediateDocument) : JSON.stringify(intermediateDocument, null, 2);
     }
     return YAML.stringify(intermediateDocument);
   }
@@ -106,20 +250,27 @@ const createWorkspaceStore = (workspaceProps) => {
   };
   async function addInMemoryDocument(input) {
     const { name, meta } = input;
-    const cloned = measureSync("deepClone", () => deepClone(input.document));
-    const inputDocument = measureSync("upgrade", () => upgrade(cloned, "3.1"));
+    const clonedRawInputDocument = measureSync("deepClone", () => deepClone(input.document));
     measureSync("initialize", () => {
       if (input.initialize !== false) {
-        originalDocuments[name] = deepClone({ ...inputDocument });
-        intermediateDocuments[name] = deepClone({ ...inputDocument });
+        originalDocuments[name] = deepClone(clonedRawInputDocument);
+        intermediateDocuments[name] = deepClone(clonedRawInputDocument);
         documentConfigs[name] = input.config ?? {};
         overrides[name] = input.overrides ?? {};
-        documentMeta[name] = { documentSource: input.documentSource };
         extraDocumentConfigurations[name] = { fetch: input.fetch };
       }
     });
-    const strictDocument = createMagicProxy({ ...inputDocument, ...meta }, { showInternal: true });
-    strictDocument["x-original-oas-version"] = input.document.openapi ?? input.document.swagger;
+    const inputDocument = measureSync("upgrade", () => upgrade(deepClone(clonedRawInputDocument), "3.1"));
+    const strictDocument = createMagicProxy(
+      {
+        ...inputDocument,
+        ...meta,
+        "x-original-oas-version": originalDocuments[name]?.openapi ?? originalDocuments[name]?.swagger,
+        "x-scalar-original-document-hash": input.documentHash,
+        "x-scalar-original-source-url": input.documentSource
+      },
+      { showInternal: true }
+    );
     if (strictDocument[extensions.document.navigation] === void 0) {
       await measureAsync(
         "bundle",
@@ -133,7 +284,7 @@ const createWorkspaceStore = (workspaceProps) => {
             refsEverywhere()
           ],
           urlMap: true,
-          origin: documentMeta[name]?.documentSource
+          origin: input.documentSource
           // use the document origin (if provided) as the base URL for resolution
         })
       );
@@ -141,7 +292,7 @@ const createWorkspaceStore = (workspaceProps) => {
         "coerceValue",
         () => coerceValue(OpenAPIDocumentSchemaStrict, deepClone(strictDocument))
       );
-      measureAsync("mergeObjects", async () => mergeObjects(strictDocument, coerced));
+      measureSync("mergeObjects", () => mergeObjects(strictDocument, coerced));
     }
     const isValid = Value.Check(OpenAPIDocumentSchemaStrict, strictDocument);
     if (!isValid) {
@@ -157,17 +308,16 @@ const createWorkspaceStore = (workspaceProps) => {
       );
     }
     if (strictDocument[extensions.document.navigation] === void 0) {
-      const navigation = createNavigation(strictDocument, input.config);
-      strictDocument[extensions.document.navigation] = navigation.entries;
+      const navigation = createNavigation(name, strictDocument, input.config);
+      strictDocument[extensions.document.navigation] = navigation;
       processDocument(getRaw(strictDocument), {
         ...documentConfigs[name] ?? {},
         documentSource: input.documentSource
       });
     }
-    workspace.documents[name] = createOverridesProxy(
-      createMagicProxy(getRaw(strictDocument)),
-      input.overrides
-    );
+    workspace.documents[name] = createOverridesProxy(createMagicProxy(getRaw(strictDocument)), {
+      overrides: overrides[name]
+    });
   }
   async function addDocument(input) {
     const { name, meta } = input;
@@ -184,7 +334,8 @@ const createWorkspaceStore = (workspaceProps) => {
           info: {
             title: `Document '${name}' could not be loaded`,
             version: "unknown"
-          }
+          },
+          "x-scalar-original-document-hash": "not-a-hash"
         };
         return;
       }
@@ -196,14 +347,16 @@ const createWorkspaceStore = (workspaceProps) => {
           info: {
             title: `Document '${name}' could not be loaded`,
             version: "unknown"
-          }
+          },
+          "x-scalar-original-document-hash": "not-a-hash"
         };
         return;
       }
       await addInMemoryDocument({
         ...input,
         document: resolve.data,
-        documentSource: getDocumentSource(input)
+        documentSource: getDocumentSource(input),
+        documentHash: await generateHash(resolve.raw)
       });
     });
   }
@@ -240,6 +393,8 @@ const createWorkspaceStore = (workspaceProps) => {
         name: documentName,
         document: input,
         // Preserve the current metadata
+        documentSource: currentDocument["x-scalar-original-source-url"],
+        documentHash: currentDocument["x-scalar-original-document-hash"],
         meta: {
           "x-scalar-active-auth": currentDocument["x-scalar-active-auth"],
           "x-scalar-active-server": currentDocument["x-scalar-active-server"]
@@ -247,14 +402,14 @@ const createWorkspaceStore = (workspaceProps) => {
         initialize: false
       });
     },
-    resolve: async (path) => {
+    resolve: (path) => {
       const activeDocument = workspace.activeDocument;
       const target = getValueByPath(activeDocument, path);
       if (!isObject(target)) {
         console.error(
           `Invalid path provided for resolution. Path: [${path.join(", ")}]. Found value of type: ${typeof target}. Expected an object.`
         );
-        return;
+        return Promise.resolve();
       }
       return bundle(target, {
         root: activeDocument,
@@ -269,7 +424,7 @@ const createWorkspaceStore = (workspaceProps) => {
       return getDocumentConfiguration(getActiveDocumentName());
     },
     exportDocument,
-    exportActiveDocument: (format) => exportDocument(getActiveDocumentName(), format),
+    exportActiveDocument: (format, minify) => exportDocument(getActiveDocumentName(), format, minify),
     saveDocument,
     async revertDocumentChanges(documentName) {
       const workspaceDocument = workspace.documents[documentName];
@@ -280,6 +435,8 @@ const createWorkspaceStore = (workspaceProps) => {
       await addInMemoryDocument({
         name: documentName,
         document: intermediate,
+        documentSource: workspaceDocument["x-scalar-original-source-url"],
+        documentHash: workspaceDocument["x-scalar-original-document-hash"],
         initialize: false
       });
     },
@@ -287,14 +444,14 @@ const createWorkspaceStore = (workspaceProps) => {
       console.warn(`Commit operation for document '${documentName}' is not implemented yet.`);
     },
     exportWorkspace() {
-      return JSON.stringify({
+      return {
         documents: {
           ...Object.fromEntries(
             Object.entries(workspace.documents).map(([name, doc]) => [
               name,
               // Extract the raw document data for export, removing any Vue reactivity wrappers.
               // When importing, the document can be wrapped again in a magic proxy.
-              getRaw(doc)
+              toRaw(getRaw(unpackOverridesProxy(doc)))
             ])
           )
         },
@@ -302,18 +459,19 @@ const createWorkspaceStore = (workspaceProps) => {
         documentConfigs,
         originalDocuments,
         intermediateDocuments,
-        overrides,
-        documentMeta
-      });
+        overrides
+      };
     },
     loadWorkspace(input) {
-      const result = coerceValue(InMemoryWorkspaceSchema, JSON.parse(input));
+      const result = coerceValue(InMemoryWorkspaceSchema, input);
       safeAssign(
         workspace.documents,
         Object.fromEntries(
           Object.entries(result.documents).map(([name, doc]) => [
             name,
-            createOverridesProxy(createMagicProxy(doc), result.overrides[name])
+            createOverridesProxy(createMagicProxy(doc), {
+              overrides: result.overrides[name]
+            })
           ])
         )
       );
@@ -322,7 +480,6 @@ const createWorkspaceStore = (workspaceProps) => {
       safeAssign(documentConfigs, result.documentConfigs);
       safeAssign(overrides, result.overrides);
       safeAssign(workspace, result.meta);
-      safeAssign(documentMeta, result.documentMeta);
     },
     importWorkspaceFromSpecification: (specification) => {
       const { documents, overrides: overrides2, info: _info, workspace: _workspaceVersion, ...meta } = specification;
@@ -333,37 +490,82 @@ const createWorkspaceStore = (workspaceProps) => {
         )
       );
     },
-    rebaseDocument: (documentName, newDocumentOrigin, resolvedConflicts) => {
-      const newOrigin = upgrade(newDocumentOrigin, "3.1");
-      const originalDocument = originalDocuments[documentName];
-      const intermediateDocument = intermediateDocuments[documentName];
-      const activeDocument = workspace.documents[documentName] ? getRaw(workspace.documents[documentName]) : void 0;
+    rebaseDocument: async (input) => {
+      const { name } = input;
+      const originalDocument = originalDocuments[name];
+      const intermediateDocument = intermediateDocuments[name];
+      const activeDocument = workspace.documents[name] ? toRaw(getRaw(unpackOverridesProxy(workspace.documents[name]))) : void 0;
       if (!originalDocument || !intermediateDocument || !activeDocument) {
-        return console.error("[ERROR]: Specified document is missing or internal corrupted workspace state");
+        return {
+          ok: false,
+          type: "CORRUPTED_STATE",
+          message: `Cannot rebase document '${name}': missing original, intermediate, or active document state`
+        };
+      }
+      const resolve = await measureAsync(
+        "loadDocument",
+        async () => await loadDocument({ ...input, fetch: input.fetch ?? workspaceProps?.fetch })
+      );
+      if (!resolve.ok || !isObject(resolve.data)) {
+        return {
+          ok: false,
+          type: "FETCH_FAILED",
+          message: `Failed to fetch document '${name}': request was not successful or returned invalid data`
+        };
+      }
+      const newHash = await generateHash(resolve.raw);
+      if (activeDocument["x-scalar-original-document-hash"] === newHash) {
+        return {
+          ok: false,
+          type: "NO_CHANGES_DETECTED",
+          message: `No changes detected for document '${name}': document hash matches the active document`
+        };
+      }
+      const newDocumentOrigin = resolve.data;
+      documentConfigs[name] = input.config ?? {};
+      overrides[name] = input.overrides ?? {};
+      extraDocumentConfigurations[name] = { fetch: input.fetch };
+      const changelogAA = diff(originalDocument, newDocumentOrigin);
+      if (changelogAA.length === 0) {
+        return {
+          ok: false,
+          type: "NO_CHANGES_DETECTED",
+          message: `No changes detected for document '${name}' after fetching the latest version.`
+        };
       }
-      const changelogAA = diff(originalDocument, newOrigin);
       const changelogAB = diff(originalDocument, intermediateDocument);
       const changesA = merge(changelogAA, changelogAB);
-      if (resolvedConflicts === void 0) {
-        return changesA.conflicts;
-      }
-      const changesetA = changesA.diffs.concat(resolvedConflicts);
-      const newIntermediateDocument = apply(deepClone(originalDocument), changesetA);
-      intermediateDocuments[documentName] = newIntermediateDocument;
-      originalDocuments[documentName] = newOrigin;
-      const changelogBA = diff(intermediateDocument, newIntermediateDocument);
-      const changelogBB = diff(intermediateDocument, activeDocument);
-      const changesB = merge(changelogBA, changelogBB);
-      const changesetB = changesB.diffs.concat(changesB.conflicts.flatMap((it) => it[0]));
-      const newActiveDocument = coerceValue(
-        OpenAPIDocumentSchemaStrict,
-        apply(deepClone(newIntermediateDocument), changesetB)
-      );
-      workspace.documents[documentName] = createOverridesProxy(
-        createMagicProxy({ ...newActiveDocument }),
-        overrides[documentName]
-      );
-      return;
+      return {
+        ok: true,
+        conflicts: changesA.conflicts,
+        applyChanges: async (resolvedConflicts) => {
+          const changesetA = changesA.diffs.concat(resolvedConflicts);
+          const newIntermediateDocument = apply(deepClone(originalDocument), changesetA);
+          intermediateDocuments[name] = newIntermediateDocument;
+          originalDocuments[name] = newDocumentOrigin;
+          const changelogBA = diff(intermediateDocument, newIntermediateDocument);
+          const changelogBB = diff(intermediateDocument, activeDocument);
+          const changesB = merge(changelogBA, changelogBB);
+          const changesetB = changesB.diffs.concat(changesB.conflicts.flatMap((it) => it[0]));
+          const newActiveDocument = coerceValue(
+            OpenAPIDocumentSchemaStrict,
+            apply(deepClone(newIntermediateDocument), changesetB)
+          );
+          await addInMemoryDocument({
+            ...input,
+            document: {
+              ...newActiveDocument,
+              // force regeneration of navigation
+              // when we are rebasing, we want to ensure that the navigation is always up to date
+              [extensions.document.navigation]: void 0
+            },
+            documentSource: getDocumentSource(input),
+            // Update the original document hash
+            documentHash: await generateHash(resolve.raw),
+            initialize: false
+          });
+        }
+      };
     }
   };
 };