@scalar/workspace-store 0.17.1 → 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";
@@ -9,12 +10,14 @@ 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, 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);
   }
@@ -113,13 +257,20 @@ const createWorkspaceStore = (workspaceProps) => {
         intermediateDocuments[name] = deepClone(clonedRawInputDocument);
         documentConfigs[name] = input.config ?? {};
         overrides[name] = input.overrides ?? {};
-        documentMeta[name] = { documentSource: input.documentSource };
         extraDocumentConfigurations[name] = { fetch: input.fetch };
       }
     });
     const inputDocument = measureSync("upgrade", () => upgrade(deepClone(clonedRawInputDocument), "3.1"));
-    const strictDocument = createMagicProxy({ ...inputDocument, ...meta }, { showInternal: true });
-    strictDocument["x-original-oas-version"] = input.document.openapi ?? input.document.swagger;
+    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
         })
       );
@@ -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)),
-      overrides[name]
-    );
+    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,60 +490,82 @@ const createWorkspaceStore = (workspaceProps) => {
         )
       );
     },
-    rebaseDocument: async (input, resolvedConflicts) => {
+    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 {
+          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 console.error(`[ERROR]: Failed to load document '${name}': response data is not a valid object`);
+        return {
+          ok: false,
+          type: "FETCH_FAILED",
+          message: `Failed to fetch document '${name}': request was not successful or returned invalid data`
+        };
       }
-      const newDocumentOrigin = resolve.data;
-      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");
+      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 documentSource = getDocumentSource(input);
+      const newDocumentOrigin = resolve.data;
       documentConfigs[name] = input.config ?? {};
       overrides[name] = input.overrides ?? {};
-      documentMeta[name] = { documentSource };
       extraDocumentConfigurations[name] = { fetch: input.fetch };
       const changelogAA = diff(originalDocument, newDocumentOrigin);
       if (changelogAA.length === 0) {
-        return;
+        return {
+          ok: false,
+          type: "NO_CHANGES_DETECTED",
+          message: `No changes detected for document '${name}' after fetching the latest version.`
+        };
       }
       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[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,
-        initialize: false
-      });
-      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
+          });
+        }
+      };
     }
   };
 };