@scalar/workspace-store 0.11.0 → 0.14.0

package/dist/client.js

@@ -1,19 +1,26 @@
 import YAML from "yaml";
 import { reactive } from "vue";
-import { bundle, upgrade } from "@scalar/openapi-parser";
-import { fetchUrls } from "@scalar/openapi-parser/plugins-browser";
+import { upgrade } from "@scalar/openapi-parser";
+import { createMagicProxy, getRaw } from "@scalar/json-magic/magic-proxy";
 import { applySelectiveUpdates } from "./helpers/apply-selective-updates.js";
-import { deepClone, isObject, safeAssign } from "./helpers/general.js";
+import { isObject, safeAssign } from "./helpers/general.js";
 import { getValueByPath } from "./helpers/json-path-utils.js";
 import { mergeObjects } from "./helpers/merge-object.js";
-import { createMagicProxy, getRaw } from "./helpers/proxy.js";
 import { createNavigation } from "./navigation/index.js";
 import { extensions } from "./schemas/extensions.js";
 import { coerceValue } from "./schemas/typebox-coerce.js";
-import { OpenAPIDocumentSchema } from "./schemas/v3.1/strict/openapi-document.js";
+import { OpenAPIDocumentSchema as OpenAPIDocumentSchemaStrict } from "./schemas/v3.1/strict/openapi-document.js";
+import { OpenAPIDocumentSchema as OpenAPIDocumentSchemaLoose } from "./schemas/v3.1/loose/openapi-document.js";
 import { defaultReferenceConfig } from "./schemas/reference-config/index.js";
 import { InMemoryWorkspaceSchema } from "./schemas/inmemory-workspace.js";
 import { createOverridesProxy } from "./helpers/overrides-proxy.js";
+import { bundle } from "@scalar/json-magic/bundle";
+import { fetchUrls } from "@scalar/json-magic/bundle/plugins/browser";
+import { apply, diff, merge } from "@scalar/json-magic/diff";
+import { externalValueResolver, loadingStatus, refsEverywhere, restoreOriginalRefs } from "./plugins.js";
+import { Value } from "@sinclair/typebox/value";
+import { deepClone } from "./helpers/deep-clone.js";
+import { measureAsync, measureSync } from "@scalar/helpers/testing/measure";
 const defaultConfig = {
   "x-scalar-reference-config": defaultReferenceConfig
 };
@@ -26,11 +33,19 @@ async function loadDocument(workspaceDocument) {
     data: workspaceDocument.document
   };
 }
+const getDocumentSource = (input) => {
+  if ("url" in input) {
+    return input.url;
+  }
+  return void 0;
+};
 const createWorkspaceStore = (workspaceProps) => {
   const originalDocuments = {};
   const intermediateDocuments = {};
   const documentConfigs = {};
   const overrides = {};
+  const documentMeta = {};
+  const extraDocumentConfigurations = {};
   const workspace = reactive({
     ...workspaceProps?.meta,
     documents: {},
@@ -49,96 +64,128 @@ const createWorkspaceStore = (workspaceProps) => {
   function getActiveDocumentName() {
     return workspace[extensions.workspace.activeDocument] ?? Object.keys(workspace.documents)[0] ?? "";
   }
-  function saveDocument(documentName) {
+  async function saveDocument(documentName) {
     const intermediateDocument = intermediateDocuments[documentName];
     const workspaceDocument = workspace.documents[documentName];
     if (!workspaceDocument) {
       return;
     }
-    const updatedDocument = createOverridesProxy(getRaw(workspaceDocument), overrides[documentName]);
+    const updatedDocument = getRaw(workspaceDocument);
     if (!intermediateDocument || !updatedDocument) {
       return;
     }
-    const excludedDiffs = applySelectiveUpdates(intermediateDocument, updatedDocument);
+    const updatedWithOriginalRefs = await bundle(deepClone(updatedDocument), {
+      plugins: [restoreOriginalRefs()],
+      treeShake: false,
+      urlMap: true
+    });
+    const excludedDiffs = applySelectiveUpdates(intermediateDocument, updatedWithOriginalRefs);
     return excludedDiffs;
   }
-  function addDocumentSync(input) {
+  async function addInMemoryDocument(input) {
     const { name, meta } = input;
-    const document = coerceValue(OpenAPIDocumentSchema, upgrade(input.document).specification);
-    originalDocuments[name] = deepClone({ ...document, ...meta });
-    intermediateDocuments[name] = deepClone({ ...document, ...meta });
-    documentConfigs[name] = input.config ?? {};
-    overrides[name] = input.overrides ?? {};
-    if (document[extensions.document.navigation] === void 0) {
-      document[extensions.document.navigation] = createNavigation(document, input.config ?? {}).entries;
+    const cloned = measureSync("deepClone", () => deepClone(input.document));
+    const inputDocument = measureSync("upgrade", () => upgrade(cloned).specification);
+    measureSync("initialize", () => {
+      if (input.initialize !== false) {
+        originalDocuments[name] = deepClone({ ...inputDocument });
+        intermediateDocuments[name] = deepClone({ ...inputDocument });
+        documentConfigs[name] = input.config ?? {};
+        overrides[name] = input.overrides ?? {};
+        documentMeta[name] = { documentSource: input.documentSource };
+        extraDocumentConfigurations[name] = { fetch: input.fetch };
+      }
+    });
+    const strictDocument = createMagicProxy({ ...inputDocument, ...meta });
+    if (strictDocument[extensions.document.navigation] === void 0) {
+      await measureAsync(
+        "bundle",
+        async () => await bundle(getRaw(strictDocument), {
+          treeShake: false,
+          plugins: [
+            fetchUrls({
+              fetch: extraDocumentConfigurations[name]?.fetch ?? workspaceProps?.fetch
+            }),
+            externalValueResolver(),
+            refsEverywhere()
+            // TODO: investigate problems with type: {} properties
+            // cleanUp(),
+          ],
+          urlMap: true,
+          origin: documentMeta[name]?.documentSource
+          // use the document origin (if provided) as the base URL for resolution
+        })
+      );
+      const coerced = measureSync(
+        "coerceValue",
+        () => coerceValue(OpenAPIDocumentSchemaStrict, deepClone(strictDocument))
+      );
+      measureAsync("mergeObjects", async () => mergeObjects(strictDocument, coerced));
+    }
+    const isValid = Value.Check(OpenAPIDocumentSchemaStrict, strictDocument);
+    if (!isValid) {
+      throw "Invalid document provided! Please check your input document. It has some invalid refs.";
     }
-    workspace.documents[name] = createOverridesProxy(createMagicProxy({ ...document, ...meta }), input.overrides);
-    saveDocument(name);
+    if (strictDocument[extensions.document.navigation] === void 0) {
+      const showModels = input.config?.["x-scalar-reference-config"]?.features?.showModels;
+      strictDocument[extensions.document.navigation] = createNavigation(strictDocument, {
+        ...input.config?.["x-scalar-reference-config"] ?? {},
+        hideModels: showModels === void 0 ? void 0 : !showModels
+      }).entries;
+    }
+    workspace.documents[name] = createOverridesProxy(strictDocument, input.overrides);
   }
   async function addDocument(input) {
     const { name, meta } = input;
-    const resolve = await loadDocument(input);
-    if (!resolve.ok) {
-      console.error(`Failed to fetch document '${name}': request was not successful`);
-      workspace.documents[name] = {
-        ...meta,
-        openapi: "3.1.0",
-        info: {
-          title: `Document '${name}' could not be loaded`,
-          version: "unknown"
-        }
-      };
-      return;
-    }
-    if (!isObject(resolve.data)) {
-      console.error(`Failed to load document '${name}': response data is not a valid object`);
-      workspace.documents[name] = {
-        ...meta,
-        openapi: "3.1.0",
-        info: {
-          title: `Document '${name}' could not be loaded`,
-          version: "unknown"
-        }
-      };
-      return;
-    }
-    addDocumentSync({ ...input, document: resolve.data });
+    const resolve = await measureAsync(
+      "loadDocument",
+      async () => await loadDocument({ ...input, fetch: input.fetch ?? workspaceProps?.fetch })
+    );
+    await measureAsync("addDocument", async () => {
+      if (!resolve.ok) {
+        console.error(`Failed to fetch document '${name}': request was not successful`);
+        workspace.documents[name] = {
+          ...meta,
+          openapi: "3.1.0",
+          info: {
+            title: `Document '${name}' could not be loaded`,
+            version: "unknown"
+          }
+        };
+        return;
+      }
+      if (!isObject(resolve.data)) {
+        console.error(`Failed to load document '${name}': response data is not a valid object`);
+        workspace.documents[name] = {
+          ...meta,
+          openapi: "3.1.0",
+          info: {
+            title: `Document '${name}' could not be loaded`,
+            version: "unknown"
+          }
+        };
+        return;
+      }
+      await addInMemoryDocument({ ...input, document: resolve.data, documentSource: getDocumentSource(input) });
+    });
   }
-  workspaceProps?.documents?.forEach(addDocumentSync);
+  const getDocumentConfiguration = (name) => {
+    return mergeObjects(
+      mergeObjects(defaultConfig, workspaceProps?.config ?? {}),
+      documentConfigs[name] ?? {}
+    );
+  };
   const visitedNodesCache = /* @__PURE__ */ new Set();
   return {
-    /**
-     * Returns the reactive workspace object with an additional activeDocument getter
-     */
     get workspace() {
       return workspace;
     },
-    /**
-     * Updates a specific metadata field in the workspace
-     * @param key - The metadata field to update
-     * @param value - The new value for the field
-     * @example
-     * // Update the workspace title
-     * update('x-scalar-active-document', 'document-name')
-     */
     update(key, value) {
       if (key === "__proto__" || key === "constructor" || key === "prototype") {
         throw new Error("Invalid key: cannot modify prototype");
       }
       Object.assign(workspace, { [key]: value });
     },
-    /**
-     * Updates a specific metadata field in a document
-     * @param name - The name of the document to update ('active' or a specific document name)
-     * @param key - The metadata field to update
-     * @param value - The new value for the field
-     * @throws Error if the specified document doesn't exist
-     * @example
-     * // Update the auth of the active document
-     * updateDocument('active', 'x-scalar-active-auth', 'Bearer')
-     * // Update the auth of a specific document
-     * updateDocument('document-name', 'x-scalar-active-auth', 'Bearer')
-     */
     updateDocument(name, key, value) {
       const currentDocument = workspace.documents[name === "active" ? getActiveDocumentName() : name];
       if (!currentDocument) {
@@ -146,41 +193,22 @@ const createWorkspaceStore = (workspaceProps) => {
       }
       Object.assign(currentDocument, { [key]: value });
     },
-    /**
-     * Replaces the content of a specific document in the workspace with the provided input.
-     * This method computes the difference between the current document and the new input,
-     * then applies only the necessary changes in place. The updates are applied atomically,
-     * ensuring the document is updated in a single operation.
-     *
-     * @param documentName - The name of the document to update.
-     * @param input - The new content to apply to the document (as a plain object).
-     * @example
-     * // Replace the content of the 'api' document with new data
-     * store.replaceDocument('api', {
-     *   openapi: '3.1.0',
-     *   info: { title: 'Updated API', version: '1.0.1' },
-     *   paths: {},
-     * })
-     */
-    replaceDocument(documentName, input) {
+    async replaceDocument(documentName, input) {
       const currentDocument = workspace.documents[documentName];
       if (!currentDocument) {
         return console.error(`Document '${documentName}' does not exist in the workspace.`);
       }
-      const newDocument = coerceValue(OpenAPIDocumentSchema, upgrade(input).specification);
-      applySelectiveUpdates(currentDocument, newDocument);
+      await addInMemoryDocument({
+        name: documentName,
+        document: input,
+        // Preserve the current metadata
+        meta: {
+          "x-scalar-active-auth": currentDocument["x-scalar-active-auth"],
+          "x-scalar-active-server": currentDocument["x-scalar-active-server"]
+        },
+        initialize: false
+      });
     },
-    /**
-     * Resolves a reference in the active document by following the provided path and resolving any external $ref references.
-     * This method traverses the document structure following the given path and resolves any $ref references it encounters.
-     * During resolution, it sets a loading status and updates the reference with the resolved content.
-     *
-     * @param path - Array of strings representing the path to the reference (e.g. ['paths', '/users', 'get', 'responses', '200'])
-     * @throws Error if the path is invalid or empty
-     * @example
-     * // Resolve a reference in the active document
-     * resolve(['paths', '/users', 'get', 'responses', '200'])
-     */
     resolve: async (path) => {
       const activeDocument = workspace.activeDocument;
       const target = getValueByPath(activeDocument, path);
@@ -193,93 +221,15 @@ const createWorkspaceStore = (workspaceProps) => {
       return bundle(target, {
         root: activeDocument,
         treeShake: false,
-        plugins: [fetchUrls()],
-        urlMap: false,
-        hooks: {
-          onResolveStart: (node) => {
-            node["$status"] = "loading";
-          },
-          onResolveError: (node) => {
-            node["$status"] = "error";
-          }
-        },
+        plugins: [fetchUrls(), loadingStatus(), externalValueResolver()],
+        urlMap: true,
         visitedNodes: visitedNodesCache
       });
     },
-    /**
-     * Adds a new document to the workspace
-     * @param document - The document content to add. This should be a valid OpenAPI/Swagger document or other supported format
-     * @param meta - Metadata for the document, including its name and other properties defined in WorkspaceDocumentMeta
-     * @example
-     * // Add a new OpenAPI document to the workspace
-     * store.addDocument({
-     *   name: 'name',
-     *   document: {
-     *     openapi: '3.0.0',
-     *     info: { title: 'title' },
-     *   },
-     *   meta: {
-     *     'x-scalar-active-auth': 'Bearer',
-     *     'x-scalar-active-server': 'production'
-     *   }
-     * })
-     */
     addDocument,
-    /**
-     * Similar to addDocument but requires and in-mem object to be provided and loads the document synchronously
-     * @param document - The document content to add. This should be a valid OpenAPI/Swagger document or other supported format
-     * @param meta - Metadata for the document, including its name and other properties defined in WorkspaceDocumentMeta
-     * @example
-     * // Add a new OpenAPI document to the workspace
-     * store.addDocument({
-     *   name: 'name',
-     *   document: {
-     *     openapi: '3.0.0',
-     *     info: { title: 'title' },
-     *   },
-     *   meta: {
-     *     'x-scalar-active-auth': 'Bearer',
-     *     'x-scalar-active-server': 'production'
-     *   }
-     * })
-     */
-    addDocumentSync,
-    /**
-     * Returns the merged configuration for the active document.
-     *
-     * This getter merges configurations in the following order of precedence:
-     * 1. Document-specific configuration (highest priority)
-     * 2. Workspace-level configuration
-     * 3. Default configuration (lowest priority)
-     *
-     * The active document is determined by the workspace's activeDocument extension,
-     * falling back to the first document if none is specified.
-     */
     get config() {
-      return mergeObjects(
-        mergeObjects(defaultConfig, workspaceProps?.config ?? {}),
-        documentConfigs[getActiveDocumentName()] ?? {}
-      );
+      return getDocumentConfiguration(getActiveDocumentName());
     },
-    /**
-     * Exports the specified document in the requested format.
-     *
-     * This method serializes the most recently saved local version of the document (from the intermediateDocuments map)
-     * to either JSON or YAML. The exported document reflects the last locally saved state, including any edits
-     * that have been saved but not yet synced to a remote registry. Runtime/in-memory changes that have not been saved
-     * will not be included.
-     *
-     * @param documentName - The name of the document to export.
-     * @param format - The output format: 'json' for a JSON string, or 'yaml' for a YAML string.
-     * @returns The document as a string in the requested format, or undefined if the document does not exist.
-     *
-     * @example
-     * // Export a document as JSON
-     * const jsonString = store.exportDocument('api', 'json')
-     *
-     * // Export a document as YAML
-     * const yamlString = store.exportDocument('api', 'yaml')
-     */
     exportDocument: (documentName, format) => {
       const intermediateDocument = intermediateDocuments[documentName];
       if (!intermediateDocument) {
@@ -290,78 +240,22 @@ const createWorkspaceStore = (workspaceProps) => {
       }
       return YAML.stringify(intermediateDocument);
     },
-    /**
-     * Saves the current state of the specified document to the intermediate documents map.
-     *
-     * This function captures the latest (reactive) state of the document from the workspace and
-     * applies its changes to the corresponding entry in the `intermediateDocuments` map.
-     * The `intermediateDocuments` map represents the most recently "saved" local version of the document,
-     * which may include edits not yet synced to the remote registry.
-     *
-     * The update is performed in-place. A deep clone of the current document
-     * state is used to avoid mutating the reactive object directly.
-     *
-     * @param documentName - The name of the document to save.
-     * @returns An array of diffs that were excluded from being applied (such as changes to ignored keys),
-     *          or undefined if the document does not exist or cannot be updated.
-     *
-     * @example
-     * // Save the current state of the document named 'api'
-     * const excludedDiffs = store.saveDocument('api')
-     */
     saveDocument,
-    /**
-     * Restores the specified document to its last locally saved state.
-     *
-     * This method updates the current reactive document (in the workspace) with the contents of the
-     * corresponding intermediate document (from the `intermediateDocuments` map), effectively discarding
-     * any unsaved in-memory changes and reverting to the last saved version.
-     * Vue reactivity is preserved by updating the existing reactive object in place.
-     *
-     * **Warning:** This operation will discard all unsaved (in-memory) changes to the specified document.
-     *
-     * @param documentName - The name of the document to restore.
-     * @returns void
-     *
-     * @example
-     * // Restore the document named 'api' to its last saved state
-     * store.revertDocumentChanges('api')
-     */
-    revertDocumentChanges(documentName) {
+    async revertDocumentChanges(documentName) {
       const workspaceDocument = workspace.documents[documentName];
-      if (!workspaceDocument) {
+      const intermediate = intermediateDocuments[documentName];
+      if (!workspaceDocument || !intermediate) {
         return;
       }
-      const intermediateDocument = intermediateDocuments[documentName];
-      const updatedDocument = createOverridesProxy(getRaw(workspaceDocument), overrides[documentName]);
-      if (!intermediateDocument || !updatedDocument) {
-        return;
-      }
-      applySelectiveUpdates(updatedDocument, intermediateDocument);
+      await addInMemoryDocument({
+        name: documentName,
+        document: intermediate,
+        initialize: false
+      });
     },
-    /**
-     * Commits the specified document.
-     *
-     * This method is intended to finalize and persist the current state of the document,
-     * potentially syncing it with a remote registry or marking it as the latest committed version.
-     *
-     * @param documentName - The name of the document to commit.
-     * @remarks
-     * The actual commit logic is not implemented yet.
-     */
     commitDocument(documentName) {
       console.warn(`Commit operation for document '${documentName}' is not implemented yet.`);
     },
-    /**
-     * Serializes the current workspace state to a JSON string for backup, persistence, or sharing.
-     *
-     * This method exports all workspace documents (removing Vue reactivity proxies), workspace metadata,
-     * document configurations, and both the original and intermediate document states. The resulting JSON
-     * can be imported later to fully restore the workspace to this exact state, including all documents
-     * and their configurations.
-     *
-     * @returns A JSON string representing the complete workspace state.
-     */
     exportWorkspace() {
       return JSON.stringify({
         documents: {
@@ -370,60 +264,36 @@ const createWorkspaceStore = (workspaceProps) => {
               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.
-              createOverridesProxy(getRaw(doc), overrides[name])
+              getRaw(doc)
             ])
           )
         },
         meta: workspaceProps?.meta ?? {},
         documentConfigs,
         originalDocuments,
-        intermediateDocuments
+        intermediateDocuments,
+        overrides,
+        documentMeta
       });
     },
-    /**
-     * Imports a workspace from a serialized JSON string.
-     *
-     * This method parses the input string using the InMemoryWorkspaceSchema,
-     * then updates the current workspace state, including documents, metadata,
-     * and configuration, with the imported values.
-     *
-     * @param input - The serialized workspace JSON string to import.
-     */
     loadWorkspace(input) {
       const result = coerceValue(InMemoryWorkspaceSchema, JSON.parse(input));
       safeAssign(
         workspace.documents,
-        Object.fromEntries(Object.entries(result.documents).map(([name, doc]) => [name, createMagicProxy(doc)]))
+        Object.fromEntries(
+          Object.entries(result.documents).map(([name, doc]) => [
+            name,
+            createOverridesProxy(createMagicProxy(doc), result.overrides[name])
+          ])
+        )
       );
       safeAssign(originalDocuments, result.originalDocuments);
       safeAssign(intermediateDocuments, result.intermediateDocuments);
       safeAssign(documentConfigs, result.documentConfigs);
+      safeAssign(overrides, result.overrides);
       safeAssign(workspace, result.meta);
+      safeAssign(documentMeta, result.documentMeta);
     },
-    /**
-     * Imports a workspace from a WorkspaceSpecification object.
-     *
-     * This method assigns workspace metadata and adds all documents defined in the specification.
-     * Each document is added using its $ref and optional overrides.
-     *
-     * @example
-     * ```ts
-     * await store.importWorkspaceFromSpecification({
-     *   documents: {
-     *     api: { $ref: '/specs/api.yaml' },
-     *     petstore: { $ref: '/specs/petstore.yaml' }
-     *   },
-     *   overrides: {
-     *     api: { config: { features: { showModels: true } } }
-     *   },
-     *   info: { title: 'My Workspace' },
-     *   workspace: 'v1',
-     *   "x-scalar-dark-mode": true
-     * })
-     * ```
-     *
-     * @param specification - The workspace specification to import.
-     */
     importWorkspaceFromSpecification: (specification) => {
       const { documents, overrides: overrides2, info, workspace: workspaceVersion, ...meta } = specification;
       safeAssign(workspace, meta);
@@ -432,6 +302,38 @@ const createWorkspaceStore = (workspaceProps) => {
           ([name, doc]) => addDocument({ url: doc.$ref, name, overrides: overrides2?.[name] })
         )
       );
+    },
+    rebaseDocument: (documentName, newDocumentOrigin, resolvedConflicts) => {
+      const newOrigin = coerceValue(OpenAPIDocumentSchemaLoose, upgrade(newDocumentOrigin).specification);
+      const originalDocument = originalDocuments[documentName];
+      const intermediateDocument = intermediateDocuments[documentName];
+      const activeDocument = workspace.documents[documentName] ? getRaw(workspace.documents[documentName]) : void 0;
+      if (!originalDocument || !intermediateDocument || !activeDocument) {
+        return console.error("[ERROR]: Specified document is missing or internal corrupted workspace state");
+      }
+      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;
     }
   };
 };