@scalar/workspace-store 0.40.2 → 0.40.3

package/dist/plugins/bundler/index.js

@@ -1,179 +1,313 @@
-import { HTTP_METHODS } from "@scalar/helpers/http/http-methods";
-import { isObject } from "@scalar/helpers/object/is-object";
-import { isLocalRef } from "../../helpers/general.js";
-import {
-  syncParametersForPathChange
-} from "../../mutators/operation/helpers/sync-path-parameters.js";
-import { getResolvedRef } from "../../plugins/bundler/helpers.js";
-const loadingStatus = () => {
-  return {
-    type: "lifecycle",
-    onResolveStart: (node) => {
-      node["$status"] = "loading";
-    },
-    onResolveError: (node) => {
-      node["$status"] = "error";
-    },
-    onResolveSuccess: (node) => {
-      delete node["$status"];
-    }
-  };
+/**
+ * This file contains a collection of plugins used for the bundler.
+ * Plugins defined here can extend or modify the behavior of the bundling process,
+ * such as adding lifecycle hooks or custom processing logic.
+ */
+import { HTTP_METHODS } from '@scalar/helpers/http/http-methods';
+import { isObject } from '@scalar/helpers/object/is-object';
+import { isLocalRef } from '../../helpers/general.js';
+import { syncParametersForPathChange, } from '../../mutators/operation/helpers/sync-path-parameters.js';
+import { getResolvedRef } from '../../plugins/bundler/helpers.js';
+/**
+ * A lifecycle plugin that adds a `$status` property to nodes during resolution.
+ * - Sets `$status` to 'loading' when resolution starts.
+ * - Sets `$status` to 'error' if resolution fails.
+ * - Removes `$status` when resolution succeeds.
+ */
+export const loadingStatus = () => {
+    return {
+        type: 'lifecycle',
+        onResolveStart: (node) => {
+            node['$status'] = 'loading';
+        },
+        onResolveError: (node) => {
+            node['$status'] = 'error';
+        },
+        onResolveSuccess: (node) => {
+            delete node['$status'];
+        },
+    };
 };
-const externalValueResolver = () => {
-  return {
-    type: "lifecycle",
-    onAfterNodeProcess: async (node, context) => {
-      const externalValue = node["externalValue"];
-      const cache = context.resolutionCache;
-      if (typeof externalValue !== "string") {
-        return;
-      }
-      const loader = context.loaders.find((it) => it.validate(externalValue));
-      if (!loader) {
-        return;
-      }
-      if (!cache.has(externalValue)) {
-        cache.set(externalValue, loader.exec(externalValue));
-      }
-      const result = await cache.get(externalValue);
-      if (result?.ok) {
-        node["value"] = result.data;
-      }
-    }
-  };
+/**
+ * Lifecycle plugin to resolve and embed external content referenced by an 'externalValue' property in a node.
+ *
+ * When a node contains an 'externalValue' property (as a string), this plugin will:
+ *   - Fetch the external resource (such as a URL or file) using the fetchUrls plugin.
+ *   - If the fetch is successful, assign the fetched data to the node's 'value' property.
+ *
+ * This is useful for inlining external content (like examples or schemas) into the OpenAPI document during bundling.
+ *
+ * @param node - The node being processed, which may contain an 'externalValue' property.
+ */
+export const externalValueResolver = () => {
+    return {
+        type: 'lifecycle',
+        onAfterNodeProcess: async (node, context) => {
+            const externalValue = node['externalValue'];
+            const cache = context.resolutionCache;
+            // Only process if 'externalValue' is a string
+            if (typeof externalValue !== 'string') {
+                return;
+            }
+            const loader = context.loaders.find((it) => it.validate(externalValue));
+            // We can not process the external value
+            if (!loader) {
+                return;
+            }
+            if (!cache.has(externalValue)) {
+                cache.set(externalValue, loader.exec(externalValue));
+            }
+            const result = await cache.get(externalValue);
+            // If fetch is successful, assign the data to the node's 'value' property
+            if (result?.ok) {
+                node['value'] = result.data;
+            }
+        },
+    };
 };
-const refsEverywhere = () => {
-  return {
-    type: "lifecycle",
-    onBeforeNodeProcess: async (node, context) => {
-      const { path, resolutionCache, parentNode } = context;
-      const ref = node["$ref"];
-      if (typeof ref !== "string") {
-        return;
-      }
-      if (!parentNode || !path.length) {
-        return;
-      }
-      const loader = context.loaders.find((it) => it.validate(ref));
-      if (!loader) {
-        return;
-      }
-      if (path[0] === "info") {
-        if (!resolutionCache.has(ref)) {
-          resolutionCache.set(ref, loader.exec(ref));
-        }
-        const result = await resolutionCache.get(ref);
-        if (result?.ok) {
-          parentNode[path.at(-1)] = result.data;
-        }
-      }
-    }
-  };
+/**
+ * Lifecycle plugin to resolve $ref on any object, including non-standard locations like the info object.
+ *
+ * This plugin will:
+ *   - Detect if a node contains a $ref property (as a string).
+ *   - If the node is under the 'info' path, attempt to resolve the reference using fetchUrls.
+ *   - Replace the node's properties with the resolved data if successful.
+ *
+ * Note: This currently only supports refs on the 'info' object and does not handle primitive types.
+ */
+export const refsEverywhere = () => {
+    return {
+        type: 'lifecycle',
+        onBeforeNodeProcess: async (node, context) => {
+            const { path, resolutionCache, parentNode } = context;
+            const ref = node['$ref'];
+            // Only process nodes that have a $ref property as a string
+            if (typeof ref !== 'string') {
+                return;
+            }
+            // Can not resolve top level refs
+            if (!parentNode || !path.length) {
+                return;
+            }
+            const loader = context.loaders.find((it) => it.validate(ref));
+            // Can not load the external ref
+            if (!loader) {
+                return;
+            }
+            // Support resolving $ref on the info object
+            if (path[0] === 'info') {
+                // Use the cache to avoid duplicate fetches
+                if (!resolutionCache.has(ref)) {
+                    resolutionCache.set(ref, loader.exec(ref));
+                }
+                const result = await resolutionCache.get(ref);
+                if (result?.ok) {
+                    // Replace the ref with the resolved data
+                    parentNode[path.at(-1)] = result.data;
+                }
+            }
+        },
+    };
 };
-const restoreOriginalRefs = () => {
-  return {
-    type: "lifecycle",
-    onBeforeNodeProcess: (node, context) => {
-      const ref = node["$ref"];
-      const root = context.rootNode;
-      const extUrls = root["x-ext-urls"];
-      if (typeof ref !== "string" || typeof extUrls !== "object" || extUrls === null || !isLocalRef(ref)) {
-        return;
-      }
-      const segments = ref.split("/");
-      const key = segments.at(-1) ?? "";
-      node["$ref"] = extUrls[key] ?? ref;
-    }
-  };
+/**
+ * Lifecycle plugin to restore original $ref values after processing.
+ *
+ * This plugin is intended to be used as a "lifecycle" plugin in the bundling process.
+ * It operates in the `onAfterNodeProcess` hook, and its main purpose is to restore
+ * the original $ref values for external references that may have been replaced or
+ * rewritten during the bundling process.
+ *
+ * How it works:
+ * - For each node processed, if the node contains a $ref property (as a string),
+ *   and the root document contains an "x-ext-urls" mapping object,
+ *   the plugin will attempt to restore the original $ref value.
+ * - The "x-ext-urls" object is expected to be a mapping from the rewritten $ref
+ *   (e.g., a hashed or compressed reference) back to the original external URL or path.
+ * - If a mapping exists for the current $ref, the plugin replaces the $ref value
+ *   with the original value from the mapping. If no mapping exists (e.g., for local refs),
+ *   the $ref value is left unchanged.
+ *
+ * This is useful for scenarios where you want to present or export the bundled document
+ * with the original external $ref values, rather than the internal or rewritten ones.
+ *
+ * @returns {LifecyclePlugin} The plugin object for use in the bundler.
+ */
+export const restoreOriginalRefs = () => {
+    return {
+        type: 'lifecycle',
+        onBeforeNodeProcess: (node, context) => {
+            const ref = node['$ref'];
+            const root = context.rootNode;
+            const extUrls = root['x-ext-urls'];
+            // Only process if $ref is a string and x-ext-urls is a valid object
+            if (typeof ref !== 'string' || typeof extUrls !== 'object' || extUrls === null || !isLocalRef(ref)) {
+                return;
+            }
+            // Working with local refs
+            const segments = ref.split('/');
+            const key = segments.at(-1) ?? '';
+            // Replace the $ref with the original version from the mapping,
+            // or keep the current version if there is no mapping (e.g., for local refs)
+            node['$ref'] = extUrls[key] ?? ref;
+        },
+    };
 };
-const normalizeAuthSchemes = () => {
-  return {
-    type: "lifecycle",
-    onAfterNodeProcess: (node, context) => {
-      const { path } = context;
-      if (path.length === 3 && path[0] === "components" && path[1] === "securitySchemes") {
-        const targetNode = getResolvedRef(node, context);
-        if (typeof targetNode === "object" && targetNode !== null && "scheme" in targetNode && typeof targetNode["scheme"] === "string" && targetNode["scheme"].toLowerCase() !== targetNode["scheme"]) {
-          targetNode["scheme"] = targetNode["scheme"].toLowerCase();
-        }
-      }
-    }
-  };
+/**
+ * Lifecycle plugin to normalize the `scheme` property in securitySchemes to lowercase.
+ *
+ * Our typebox schemas require the `scheme` property to be a lowercase string.
+ * This plugin ensures that any `scheme` field under `components.securitySchemes` is normalized to lowercase, fixing
+ * potential user input errors such as "Bearer" or "BASIC".
+ *
+ * Example:
+ * ```yaml
+ * Before normalization:
+ *   components:
+ *     securitySchemes:
+ *       bearerAuth:
+ *         type: http
+ *         scheme: Bearer
+ * ```
+ * After normalization:
+ * ```yaml
+ *   components:
+ *     securitySchemes:
+ *       bearerAuth:
+ *         type: http
+ *         scheme: bearer
+ * ```
+ */
+export const normalizeAuthSchemes = () => {
+    return {
+        type: 'lifecycle',
+        onAfterNodeProcess: (node, context) => {
+            const { path } = context;
+            // Check if we're at components.securitySchemes.{schemeName}
+            if (path.length === 3 && path[0] === 'components' && path[1] === 'securitySchemes') {
+                const targetNode = getResolvedRef(node, context);
+                // If the scheme exists and is a string, normalize to lowercase if not already
+                if (typeof targetNode === 'object' &&
+                    targetNode !== null &&
+                    'scheme' in targetNode &&
+                    typeof targetNode['scheme'] === 'string' &&
+                    targetNode['scheme'].toLowerCase() !== targetNode['scheme']) {
+                    targetNode['scheme'] = targetNode['scheme'].toLowerCase();
+                }
+            }
+        },
+    };
 };
-const normalizeRefs = () => {
-  return {
-    type: "lifecycle",
-    onBeforeNodeProcess: (node, context) => {
-      const { path } = context;
-      if (typeof node["$ref"] === "string" && !(path[0] === "components" && path[1] === "schemas")) {
-        const keepProperties = /* @__PURE__ */ new Set(["$ref", "summary", "description", "$status"]);
-        Object.keys(node).forEach((key) => {
-          if (!keepProperties.has(key)) {
-            delete node[key];
-          }
-        });
-      }
-    }
-  };
+/**
+ * Lifecycle plugin to normalize $ref nodes:
+ * Ensures that for any non-schema object containing a $ref, only $ref,
+ * summary, description, and $status properties are preserved.
+ * This keeps $ref references clean and predictable for downstream consumers.
+ */
+export const normalizeRefs = () => {
+    return {
+        type: 'lifecycle',
+        onBeforeNodeProcess: (node, context) => {
+            const { path } = context;
+            // If the node is a $ref and we are not on the schema object, we need to normalize the $ref
+            if (typeof node['$ref'] === 'string' && !(path[0] === 'components' && path[1] === 'schemas')) {
+                // Remove any other properties from the node and only keep the '$ref', 'summary', 'description' and '$status'
+                const keepProperties = new Set(['$ref', 'summary', 'description', '$status']);
+                Object.keys(node).forEach((key) => {
+                    if (!keepProperties.has(key)) {
+                        delete node[key];
+                    }
+                });
+            }
+        },
+    };
 };
-const syncPathParameters = () => {
-  return {
-    type: "lifecycle",
-    onBeforeNodeProcess: (node, context) => {
-      const { path } = context;
-      if (path.length !== 2 || path[0] !== "paths" || typeof path[1] !== "string") {
-        return;
-      }
-      const pathString = path[1];
-      for (const method of HTTP_METHODS) {
-        const operation = getResolvedRef(node[method], context);
-        if (!isObject(operation)) {
-          continue;
-        }
-        const isParameterNode = (param) => {
-          const resolved = getResolvedRef(param, context);
-          return isObject(resolved) && "name" in resolved && typeof resolved.name === "string" && "in" in resolved && typeof resolved.in === "string";
-        };
-        const isPathParameterNode = (param) => {
-          const resolved = getResolvedRef(param, context);
-          return isParameterNode(resolved) && resolved.in === "path";
-        };
-        const existingParameters = ("parameters" in operation && Array.isArray(operation.parameters) ? operation.parameters : []).filter(isParameterNode);
-        const existingPathParameters = new Set(
-          existingParameters.map((param) => getResolvedRef(param, context)).filter(isPathParameterNode).map((param) => param.name)
-        );
-        const pathItemParameters = "parameters" in node && Array.isArray(node.parameters) ? node.parameters : [];
-        const pathItemPathParameters = pathItemParameters.filter((param) => {
-          const resolved = getResolvedRef(param, context);
-          if (!isPathParameterNode(resolved)) {
-            return false;
-          }
-          const result2 = !existingPathParameters.has(resolved.name);
-          if (result2) {
-            existingPathParameters.add(resolved.name);
-          }
-          return result2;
-        });
-        const result = syncParametersForPathChange(
-          pathString,
-          pathString,
-          [...existingParameters, ...pathItemPathParameters],
-          (node2) => getResolvedRef(node2, context)
-        );
-        if (result.length > 0) {
-          operation.parameters = result;
-        }
-      }
-    }
-  };
+/**
+ * Lifecycle plugin to sync path parameters for all operations under a path item.
+ *
+ * When processing a path item (e.g., '/users/{id}'), this plugin will:
+ *   - Extract path variables from the path string
+ *   - For each HTTP method operation (get, post, put, delete, etc.)
+ *   - Sync the operation's parameters to match the path variables
+ *   - Preserve existing parameter configurations when possible
+ *
+ * This ensures that path parameters are always in sync with the path string,
+ * even after bundling or other transformations.
+ */
+export const syncPathParameters = () => {
+    return {
+        type: 'lifecycle',
+        onBeforeNodeProcess: (node, context) => {
+            const { path } = context;
+            // Only process path items (e.g., paths -> /users/{id} -> operations)
+            if (path.length !== 2 || path[0] !== 'paths' || typeof path[1] !== 'string') {
+                return;
+            }
+            const pathString = path[1];
+            // Sync parameters for each operation method
+            for (const method of HTTP_METHODS) {
+                const operation = getResolvedRef(node[method], context);
+                if (!isObject(operation)) {
+                    continue;
+                }
+                const isParameterNode = (param) => {
+                    const resolved = getResolvedRef(param, context);
+                    return (isObject(resolved) &&
+                        'name' in resolved &&
+                        typeof resolved.name === 'string' &&
+                        'in' in resolved &&
+                        typeof resolved.in === 'string');
+                };
+                const isPathParameterNode = (param) => {
+                    const resolved = getResolvedRef(param, context);
+                    return isParameterNode(resolved) && resolved.in === 'path';
+                };
+                const existingParameters = ('parameters' in operation && Array.isArray(operation.parameters) ? operation.parameters : []).filter(isParameterNode);
+                const existingPathParameters = new Set(existingParameters
+                    .map((param) => getResolvedRef(param, context))
+                    .filter(isPathParameterNode)
+                    .map((param) => param.name));
+                // Include path-item level path parameters as fallbacks for any that the operation does not declare.
+                // Without this, syncParametersForPathChange would create bare `{ name, in: 'path' }` params,
+                // losing description, schema, required, etc. from the path-item definition.
+                const pathItemParameters = 'parameters' in node && Array.isArray(node.parameters) ? node.parameters : [];
+                const pathItemPathParameters = pathItemParameters.filter((param) => {
+                    const resolved = getResolvedRef(param, context);
+                    if (!isPathParameterNode(resolved)) {
+                        return false;
+                    }
+                    const result = !existingPathParameters.has(resolved.name);
+                    if (result) {
+                        existingPathParameters.add(resolved.name);
+                    }
+                    return result;
+                });
+                const result = syncParametersForPathChange(pathString, pathString, [...existingParameters, ...pathItemPathParameters], (node) => getResolvedRef(node, context));
+                if (result.length > 0) {
+                    operation.parameters = result;
+                }
+            }
+        },
+    };
 };
-export {
-  externalValueResolver,
-  loadingStatus,
-  normalizeAuthSchemes,
-  normalizeRefs,
-  refsEverywhere,
-  restoreOriginalRefs,
-  syncPathParameters
+// A list of nested internal keys that should be removed from nodes at any level.
+const NESTED_INTERNAL_KEYS = ['__scalar_', '$status'];
+/**
+ * Lifecycle plugin to remove extra Scalar internal keys from nodes.
+ *
+ * This plugin is used to remove extra Scalar internal keys from nodes during the bundling process.
+ * These keys are used for internal purposes and are not needed in the final bundled document.
+ */
+export const removeExtraScalarKeys = () => {
+    return {
+        type: 'lifecycle',
+        onBeforeNodeProcess: (node) => {
+            if (isObject(node)) {
+                for (const key of NESTED_INTERNAL_KEYS) {
+                    if (key in node) {
+                        delete node[key];
+                    }
+                }
+            }
+        },
+    };
 };
-//# sourceMappingURL=index.js.map

package/dist/plugins/client/index.js

@@ -1,5 +1 @@
-import { persistencePlugin } from "./persistence.js";
-export {
-  persistencePlugin
-};
-//# sourceMappingURL=index.js.map
+export { persistencePlugin } from './persistence.js';