@scalar/workspace-store 0.12.0 → 0.14.1

package/dist/client.js

@@ -1,21 +1,28 @@
-import YAML from "yaml";
-import { reactive } from "vue";
-import { upgrade } from "@scalar/openapi-parser";
 import { createMagicProxy, getRaw } from "@scalar/json-magic/magic-proxy";
+import { upgrade } from "@scalar/openapi-parser";
+import { reactive } from "vue";
+import YAML from "yaml";
 import { applySelectiveUpdates } from "./helpers/apply-selective-updates.js";
-import { deepClone, isObject, safeAssign } from "./helpers/general.js";
+import { deepClone } from "./helpers/deep-clone.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 { createNavigation } from "./navigation/index.js";
+import { externalValueResolver, loadingStatus, refsEverywhere, restoreOriginalRefs } from "./plugins.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 { defaultReferenceConfig } from "./schemas/reference-config/index.js";
 import { InMemoryWorkspaceSchema } from "./schemas/inmemory-workspace.js";
-import { createOverridesProxy } from "./helpers/overrides-proxy.js";
+import { defaultReferenceConfig } from "./schemas/reference-config/index.js";
+import { coerceValue } from "./schemas/typebox-coerce.js";
+import { OpenAPIDocumentSchema as OpenAPIDocumentSchemaLoose } from "./schemas/v3.1/loose/openapi-document.js";
+import {
+  OpenAPIDocumentSchema as OpenAPIDocumentSchemaStrict
+} from "./schemas/v3.1/strict/openapi-document.js";
+import { measureAsync, measureSync } from "@scalar/helpers/testing/measure";
 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 { Value } from "@sinclair/typebox/value";
 const defaultConfig = {
   "x-scalar-reference-config": defaultReferenceConfig
 };
@@ -28,11 +35,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: {},
@@ -51,7 +66,7 @@ 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) {
@@ -61,87 +76,137 @@ const createWorkspaceStore = (workspaceProps) => {
     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;
   }
   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 temporaryDocument = createMagicProxy({ ...inputDocument, ...meta });
+    if (temporaryDocument[extensions.document.navigation] === void 0) {
+      await measureAsync(
+        "bundle",
+        async () => await bundle(getRaw(temporaryDocument), {
+          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(temporaryDocument))
+      );
+      measureAsync("mergeObjects", async () => mergeObjects(temporaryDocument, coerced));
+    }
+    const isValid = Value.Check(OpenAPIDocumentSchemaStrict, temporaryDocument);
+    let errors = null;
+    if (!isValid) {
+      const validationErrors = Array.from(Value.Errors(OpenAPIDocumentSchemaStrict, temporaryDocument));
+      errors = validationErrors.map((error) => ({
+        message: error.message,
+        path: error.path,
+        schema: error.schema,
+        value: error.value
+      }));
     }
-    if (document[extensions.document.navigation] === void 0) {
-      await bundle(input.document, { treeShake: false, plugins: [fetchUrls()] });
+    const strictDocument = isValid ? temporaryDocument : temporaryDocument;
+    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(createMagicProxy({ ...document, ...meta }), input.overrides);
+    workspace.documents[name] = createOverridesProxy(strictDocument, input.overrides);
+    return {
+      errors,
+      document: workspace.documents[name]
+    };
   }
   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;
-    }
-    await addInMemoryDocument({ ...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;
+      }
+      const { errors } = await addInMemoryDocument({
+        ...input,
+        document: resolve.data,
+        documentSource: getDocumentSource(input)
+      });
+      if (errors) {
+        console.warn("OpenAPI Document Validation Errors", errors);
+      }
+    });
   }
+  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) {
@@ -149,41 +214,25 @@ 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);
+      const { errors } = 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
+      });
+      if (errors) {
+        console.warn("OpenAPI Document Validation Errors", errors);
+      }
     },
-    /**
-     * 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);
@@ -196,74 +245,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,
-    /**
-     * 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) {
@@ -274,78 +264,25 @@ 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 = getRaw(workspaceDocument);
-      if (!intermediateDocument || !updatedDocument) {
-        return;
+      const { errors } = await addInMemoryDocument({
+        name: documentName,
+        document: intermediate,
+        initialize: false
+      });
+      if (errors) {
+        console.warn("OpenAPI Document Validation Errors", errors);
       }
-      applySelectiveUpdates(updatedDocument, intermediateDocument);
     },
-    /**
-     * 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: {
@@ -354,7 +291,7 @@ 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)
             ])
           )
         },
@@ -362,54 +299,28 @@ const createWorkspaceStore = (workspaceProps) => {
         documentConfigs,
         originalDocuments,
         intermediateDocuments,
-        overrides
+        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);
@@ -419,28 +330,8 @@ const createWorkspaceStore = (workspaceProps) => {
         )
       );
     },
-    /**
-     * Rebases a document in the workspace with a new origin, resolving conflicts if provided.
-     *
-     * This method is used to rebase a document (e.g., after pulling remote changes) by applying the changes
-     * from the new origin and merging them with local edits. If there are conflicts, they can be resolved
-     * by providing a list of resolved conflicts.
-     *
-     * @param documentName - The name of the document to rebase.
-     * @param newDocumentOrigin - The new origin document (as an object) to rebase onto.
-     * @param resolvedConflicts - (Optional) An array of resolved conflicts to apply.
-     * @returns If there are unresolved conflicts and no resolution is provided, returns the list of conflicts.
-     *
-     * @example
-     * // Example: Rebase a document with a new origin and resolve conflicts
-     * const conflicts = store.rebaseDocument('api', newOriginDoc)
-     * if (conflicts && conflicts.length > 0) {
-     *   // User resolves conflicts here...
-     *   store.rebaseDocument('api', newOriginDoc, userResolvedConflicts)
-     * }
-     */
     rebaseDocument: (documentName, newDocumentOrigin, resolvedConflicts) => {
-      const newOrigin = coerceValue(OpenAPIDocumentSchema, upgrade(newDocumentOrigin).specification);
+      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;
@@ -461,7 +352,10 @@ const createWorkspaceStore = (workspaceProps) => {
       const changelogBB = diff(intermediateDocument, activeDocument);
       const changesB = merge(changelogBA, changelogBB);
       const changesetB = changesB.diffs.concat(changesB.conflicts.flatMap((it) => it[0]));
-      const newActiveDocument = apply(deepClone(newIntermediateDocument), changesetB);
+      const newActiveDocument = coerceValue(
+        OpenAPIDocumentSchemaStrict,
+        apply(deepClone(newIntermediateDocument), changesetB)
+      );
       workspace.documents[documentName] = createOverridesProxy(
         createMagicProxy({ ...newActiveDocument }),
         overrides[documentName]