@scalar/workspace-store 0.40.2 → 0.40.4

package/dist/mutators/operation/parameters.js

@@ -1,100 +1,164 @@
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-import { unpackProxyObject } from "../../helpers/unpack-proxy.js";
-const upsertOperationParameter = (document, { meta, type, payload, originalParameter }) => {
-  if (originalParameter) {
-    const param = originalParameter;
-    param.name = payload.name;
-    if (!param.examples) {
-      param.examples = {};
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
+/**
+ * Updates an existing parameter of a given `type` by its index within that
+ * type subset (e.g. the N-th query parameter). Supports updating name, value,
+ * and enabled state for the targeted example.
+ * Safely no-ops if the document, operation, or parameter does not exist.
+ *
+ * Example:
+ * ```ts
+ * updateOperationParameter({
+ *   document,
+ *   type: 'query',
+ *   index: 0,
+ *   meta: { method: 'get', path: '/search', exampleKey: 'default' },
+ *   payload: { value: 'alice', isDisabled: false },
+ * })
+ * ```
+ */
+export const upsertOperationParameter = (document, { meta, type, payload, originalParameter }) => {
+    // We are editing an existing parameter
+    if (originalParameter) {
+        // To support content-type parameters in the API client, we just assume an
+        // examples property can be set.
+        const param = originalParameter;
+        param.name = payload.name;
+        if (!param.examples) {
+            param.examples = {};
+        }
+        // Create the example if it doesn't exist
+        if (!param.examples[meta.exampleKey]) {
+            param.examples[meta.exampleKey] = {};
+        }
+        const example = getResolvedRef(param.examples[meta.exampleKey]);
+        // Update the example value and disabled state
+        example.value = payload.value;
+        example['x-disabled'] = payload.isDisabled;
+        return;
     }
-    if (!param.examples[meta.exampleKey]) {
-      param.examples[meta.exampleKey] = {};
+    // We are adding a new parameter
+    const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
+    if (!operation) {
+        console.error('Operation not found', { meta, document });
+        return;
     }
-    const example = getResolvedRef(param.examples[meta.exampleKey]);
-    example.value = payload.value;
-    example["x-disabled"] = payload.isDisabled;
+    operation.parameters ||= [];
+    operation.parameters.push({
+        name: payload.name,
+        in: type,
+        required: type === 'path' ? true : false,
+        examples: {
+            [meta.exampleKey]: {
+                value: payload.value,
+                // We always want a new parameter to be enabled by default
+                'x-disabled': false,
+            },
+        },
+    });
     return;
-  }
-  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
-  if (!operation) {
-    console.error("Operation not found", { meta, document });
-    return;
-  }
-  operation.parameters ||= [];
-  operation.parameters.push({
-    name: payload.name,
-    in: type,
-    required: type === "path" ? true : false,
-    examples: {
-      [meta.exampleKey]: {
-        value: payload.value,
-        // We always want a new parameter to be enabled by default
-        "x-disabled": false
-      }
-    }
-  });
-  return;
 };
-const updateOperationExtraParameters = (document, { type, meta, payload, in: location }) => {
-  if (!document) {
-    return;
-  }
-  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
-  if (!operation) {
-    return;
-  }
-  if (!operation["x-scalar-disable-parameters"]) {
-    operation["x-scalar-disable-parameters"] = {};
-  }
-  const mapping = {
-    global: { cookie: "global-cookies" },
-    default: { header: "default-headers" }
-  };
-  const key = mapping[type]?.[location];
-  if (!key) {
-    return;
-  }
-  if (!operation["x-scalar-disable-parameters"][key]) {
-    operation["x-scalar-disable-parameters"][key] = {};
-  }
-  operation["x-scalar-disable-parameters"][key][meta.exampleKey] = {
-    ...operation["x-scalar-disable-parameters"][key][meta.exampleKey] ?? {},
-    [meta.name]: payload.isDisabled ?? false
-  };
-};
-const deleteOperationParameter = (document, { meta, originalParameter }) => {
-  const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
-  const operationIndex = operation?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
-  if (operation && operationIndex >= 0) {
-    operation.parameters = unpackProxyObject(
-      operation.parameters?.filter((_, i) => i !== operationIndex),
-      { depth: 1 }
-    );
-    return;
-  }
-  const path = getResolvedRef(document?.paths?.[meta.path]);
-  const pathIndex = path?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
-  if (path && pathIndex >= 0) {
-    path.parameters = unpackProxyObject(
-      path.parameters?.filter((_, i) => i !== pathIndex),
-      { depth: 1 }
-    );
-  }
+/**
+ * Updates the disabled state of a default parameter for an operation.
+ * Default parameters are inherited from higher-level configurations (like collection or server defaults)
+ * and this allows individual operations to selectively disable them without removing them entirely.
+ *
+ * The disabled state is stored in the `x-scalar-disable-parameters` extension object, organized by
+ * parameter type and example key. Missing objects are initialized automatically.
+ *
+ * @param document - The current workspace document
+ * @param type - The parameter type (e.g., 'header'). Determines the storage key ('default-headers' for headers)
+ * @param meta.path - Path of the operation (e.g., '/users')
+ * @param meta.method - HTTP method of the operation (e.g., 'get')
+ * @param meta.exampleKey - Key identifying the relevant example
+ * @param meta.key - The specific parameter key being updated
+ * @param payload.isDisabled - Whether the parameter should be disabled
+ */
+export const updateOperationExtraParameters = (document, { type, meta, payload, in: location }) => {
+    // Ensure there's a valid document
+    if (!document) {
+        return;
+    }
+    // Resolve the referenced operation from the document using the path and method
+    const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+    if (!operation) {
+        return;
+    }
+    // Initialize the 'x-scalar-disable-parameters' object if it doesn't exist
+    if (!operation['x-scalar-disable-parameters']) {
+        operation['x-scalar-disable-parameters'] = {};
+    }
+    /**
+     * Maps parameter type and location to the corresponding config key.
+     * Only valid combinations are defined here.
+     */
+    const mapping = {
+        global: { cookie: 'global-cookies' },
+        default: { header: 'default-headers' },
+    };
+    const key = mapping[type]?.[location];
+    if (!key) {
+        return;
+    }
+    // Initialize the 'default-headers' object within 'x-scalar-disable-parameters' if it doesn't exist
+    if (!operation['x-scalar-disable-parameters'][key]) {
+        operation['x-scalar-disable-parameters'][key] = {};
+    }
+    // Update (or create) the entry for the specific example and key, preserving any existing settings
+    operation['x-scalar-disable-parameters'][key][meta.exampleKey] = {
+        ...(operation['x-scalar-disable-parameters'][key][meta.exampleKey] ?? {}),
+        [meta.name]: payload.isDisabled ?? false,
+    };
 };
-const deleteAllOperationParameters = (document, { meta, type }) => {
-  if (!document) {
-    return;
-  }
-  const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
-  if (!operation) {
-    return;
-  }
-  operation.parameters = operation.parameters?.filter((it) => getResolvedRef(it).in !== type) ?? [];
+/**
+ * Removes a parameter from the operation OR path
+ *
+ * Example:
+ * ```ts
+ * deleteOperationParameter({
+ *   document,
+ *   originalParameter,
+ *   meta: { method: 'get', path: '/users', exampleKey: 'default' },
+ * })
+ * ```
+ */
+export const deleteOperationParameter = (document, { meta, originalParameter }) => {
+    const operation = getResolvedRef(document?.paths?.[meta.path]?.[meta.method]);
+    // Lets check if its on the operation first as its more likely
+    const operationIndex = operation?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
+    // We cannot call splice on a proxy object, so we unwrap the array and filter it
+    if (operation && operationIndex >= 0) {
+        operation.parameters = unpackProxyObject(operation.parameters?.filter((_, i) => i !== operationIndex), { depth: 1 });
+        return;
+    }
+    // If it wasn't on the operation it might be on the path
+    const path = getResolvedRef(document?.paths?.[meta.path]);
+    const pathIndex = path?.parameters?.findIndex((it) => getResolvedRef(it) === originalParameter) ?? -1;
+    if (path && pathIndex >= 0) {
+        path.parameters = unpackProxyObject(path.parameters?.filter((_, i) => i !== pathIndex), { depth: 1 });
+    }
 };
-export {
-  deleteAllOperationParameters,
-  deleteOperationParameter,
-  updateOperationExtraParameters,
-  upsertOperationParameter
+/**
+ * Deletes all parameters of a given `type` from the operation.
+ * Safely no-ops if the document or operation does not exist.
+ *
+ * Example:
+ * ```ts
+ * deleteAllOperationParameters({
+ *   document,
+ *   type: 'cookie',
+ *   meta: { method: 'get', path: '/users' },
+ * })
+ * ```
+ */
+export const deleteAllOperationParameters = (document, { meta, type }) => {
+    if (!document) {
+        return;
+    }
+    const operation = getResolvedRef(document.paths?.[meta.path]?.[meta.method]);
+    if (!operation) {
+        return;
+    }
+    // Filter out parameters of the specified type
+    operation.parameters = operation.parameters?.filter((it) => getResolvedRef(it).in !== type) ?? [];
 };
-//# sourceMappingURL=parameters.js.map

package/dist/mutators/server.js

@@ -1,166 +1,227 @@
-import { findVariables } from "@scalar/helpers/regex/find-variables";
-import { getResolvedRef } from "../helpers/get-resolved-ref.js";
-import { unpackProxyObject } from "../helpers/unpack-proxy.js";
-import { coerceValue } from "../schemas/typebox-coerce.js";
-import { ServerObjectSchema } from "../schemas/v3.1/strict/openapi-document.js";
+import { findVariables } from '@scalar/helpers/regex/find-variables';
+import { getResolvedRef } from '../helpers/get-resolved-ref.js';
+import { unpackProxyObject } from '../helpers/unpack-proxy.js';
+import { coerceValue } from '../schemas/typebox-coerce.js';
+import { ServerObjectSchema } from '../schemas/v3.1/strict/openapi-document.js';
+/**
+ * Resolves the server target (document or operation) from meta.
+ * Document-level servers live on the document; operation-level servers on the operation object.
+ */
 const getServerTarget = (document, meta) => {
-  if (!document) {
-    return null;
-  }
-  if (meta.type === "document") {
-    return document;
-  }
-  return getResolvedRef(document.paths?.[meta.path]?.[meta.method]) ?? null;
-};
-const initializeServers = (document, { meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target) {
-    console.error("Target not found", meta);
-    return void 0;
-  }
-  target.servers = [];
-  return target.servers;
+    if (!document) {
+        return null;
+    }
+    if (meta.type === 'document') {
+        return document;
+    }
+    return getResolvedRef(document.paths?.[meta.path]?.[meta.method]) ?? null;
 };
-const addServer = (document, { meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target) {
-    console.error("Target not found", meta);
-    return void 0;
-  }
-  const parsed = coerceValue(ServerObjectSchema, {});
-  if (!target.servers) {
+/**
+ * Initializes the servers for the document or operation based on meta.
+ *
+ * @param document - The document to initialize the servers for
+ * @param meta - Target context (document or operation)
+ */
+export const initializeServers = (document, { meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target) {
+        console.error('Target not found', meta);
+        return undefined;
+    }
     target.servers = [];
-  }
-  target.servers.push(parsed);
-  return parsed;
+    return target.servers;
 };
+/**
+ * Adds a new ServerObject to the document or operation based on meta.
+ *
+ * @param document - The document to add the server to
+ * @returns the new server object or undefined if the target is not found
+ */
+export const addServer = (document, { meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target) {
+        console.error('Target not found', meta);
+        return undefined;
+    }
+    const parsed = coerceValue(ServerObjectSchema, {});
+    if (!target.servers) {
+        target.servers = [];
+    }
+    target.servers.push(parsed);
+    return parsed;
+};
+/**
+ * Creates a map of variable names to their character positions in a URL.
+ * Used to detect renamed variables by position matching.
+ */
 const getVariablePositions = (url, variables) => {
-  const positions = {};
-  for (const varName of variables) {
-    const position = url.indexOf(`{${varName}}`);
-    if (position !== -1) {
-      positions[varName] = position;
-    }
-  }
-  return positions;
+    const positions = {};
+    for (const varName of variables) {
+        const position = url.indexOf(`{${varName}}`);
+        if (position !== -1) {
+            positions[varName] = position;
+        }
+    }
+    return positions;
 };
+/**
+ * Syncs server variables when the URL changes.
+ *
+ * Preserves variable configurations by:
+ * 1. Keeping variables with matching names
+ * 2. Renaming variables at the same position
+ * 3. Creating new variables with empty defaults
+ */
 const syncVariablesForUrlChange = (newUrl, oldUrl, existingVariables) => {
-  const oldVariables = findVariables(oldUrl, { includePath: true, includeEnv: false }).filter(
-    (v) => v !== void 0
-  );
-  const newVariables = findVariables(newUrl, { includePath: true, includeEnv: false }).filter(
-    (v) => v !== void 0
-  );
-  const oldPositions = getVariablePositions(oldUrl, oldVariables);
-  const newPositions = getVariablePositions(newUrl, newVariables);
-  const usedOldVariables = /* @__PURE__ */ new Set();
-  const syncedVariables = {};
-  for (const newVar of newVariables) {
-    if (existingVariables[newVar]) {
-      syncedVariables[newVar] = existingVariables[newVar];
-      usedOldVariables.add(newVar);
-      continue;
-    }
-    const newVarPosition = newPositions[newVar];
-    const oldVarAtPosition = oldVariables.find(
-      (oldVar) => oldPositions[oldVar] === newVarPosition && !usedOldVariables.has(oldVar)
-    );
-    if (oldVarAtPosition && existingVariables[oldVarAtPosition]) {
-      syncedVariables[newVar] = existingVariables[oldVarAtPosition];
-      usedOldVariables.add(oldVarAtPosition);
-      continue;
-    }
-    syncedVariables[newVar] = { default: "" };
-  }
-  return syncedVariables;
-};
-const updateServer = (document, { index, server, meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target) {
-    return void 0;
-  }
-  const oldServer = unpackProxyObject(target.servers?.[index], { depth: 1 });
-  if (!oldServer) {
-    console.error("Server not found at index:", index);
-    return void 0;
-  }
-  const oldUrl = oldServer.url;
-  const updatedServer = coerceValue(ServerObjectSchema, { ...oldServer, ...server });
-  const hasUrlChanged = oldUrl && oldUrl !== updatedServer.url;
-  if (hasUrlChanged) {
-    const existingVariables = updatedServer.variables ?? {};
-    updatedServer.variables = syncVariablesForUrlChange(updatedServer.url, oldUrl, existingVariables);
-    if (target["x-scalar-selected-server"] === oldUrl) {
-      target["x-scalar-selected-server"] = updatedServer.url;
-    }
-  }
-  if (!target.servers) {
-    target.servers = [updatedServer];
-  } else {
-    target.servers[index] = updatedServer;
-  }
-  return updatedServer;
+    // Filter out undefined values from findVariables results
+    const oldVariables = findVariables(oldUrl, { includePath: true, includeEnv: false }).filter((v) => v !== undefined);
+    const newVariables = findVariables(newUrl, { includePath: true, includeEnv: false }).filter((v) => v !== undefined);
+    const oldPositions = getVariablePositions(oldUrl, oldVariables);
+    const newPositions = getVariablePositions(newUrl, newVariables);
+    const usedOldVariables = new Set();
+    const syncedVariables = {};
+    for (const newVar of newVariables) {
+        // Case 1: Variable with same name exists - preserve its config
+        if (existingVariables[newVar]) {
+            syncedVariables[newVar] = existingVariables[newVar];
+            usedOldVariables.add(newVar);
+            continue;
+        }
+        // Case 2: Check for variable at same position (likely a rename)
+        const newVarPosition = newPositions[newVar];
+        const oldVarAtPosition = oldVariables.find((oldVar) => oldPositions[oldVar] === newVarPosition && !usedOldVariables.has(oldVar));
+        if (oldVarAtPosition && existingVariables[oldVarAtPosition]) {
+            // Rename: transfer the old variable's config to the new name
+            syncedVariables[newVar] = existingVariables[oldVarAtPosition];
+            usedOldVariables.add(oldVarAtPosition);
+            continue;
+        }
+        // Case 3: New variable - create with empty default
+        syncedVariables[newVar] = { default: '' };
+    }
+    return syncedVariables;
 };
-const deleteServer = (document, { index, meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target?.servers) {
-    return;
-  }
-  const url = target.servers[index]?.url;
-  target.servers.splice(index, 1);
-  if (target["x-scalar-selected-server"] === url) {
-    target["x-scalar-selected-server"] = target.servers[0]?.url ?? void 0;
-  }
+/**
+ * Updates a ServerObject in the document or operation based on meta.
+ * When the URL changes, intelligently syncs variables by preserving configurations
+ * for renamed variables (detected by position) and existing variables.
+ *
+ * @param document - The document containing the server to update
+ * @param index - The index of the server to update
+ * @param server - The partial server object with fields to update
+ * @param meta - Target context (document or operation)
+ * @returns the updated server object or undefined if the server is not found
+ */
+export const updateServer = (document, { index, server, meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target) {
+        return undefined;
+    }
+    const oldServer = unpackProxyObject(target.servers?.[index], { depth: 1 });
+    if (!oldServer) {
+        console.error('Server not found at index:', index);
+        return undefined;
+    }
+    const oldUrl = oldServer.url;
+    const updatedServer = coerceValue(ServerObjectSchema, { ...oldServer, ...server });
+    const hasUrlChanged = oldUrl && oldUrl !== updatedServer.url;
+    if (hasUrlChanged) {
+        const existingVariables = updatedServer.variables ?? {};
+        updatedServer.variables = syncVariablesForUrlChange(updatedServer.url, oldUrl, existingVariables);
+        if (target['x-scalar-selected-server'] === oldUrl) {
+            target['x-scalar-selected-server'] = updatedServer.url;
+        }
+    }
+    if (!target.servers) {
+        target.servers = [updatedServer];
+    }
+    else {
+        target.servers[index] = updatedServer;
+    }
+    return updatedServer;
 };
-const clearServers = (document, { meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target) {
-    return;
-  }
-  target.servers = void 0;
-  target["x-scalar-selected-server"] = void 0;
+/**
+ * Deletes a ServerObject at the specified index from the document or operation based on meta.
+ *
+ * @param document - The document to delete the server from
+ * @param index - The index of the server to delete
+ * @param meta - Target context (document or operation)
+ */
+export const deleteServer = (document, { index, meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target?.servers) {
+        return;
+    }
+    const url = target.servers[index]?.url;
+    target.servers.splice(index, 1);
+    if (target['x-scalar-selected-server'] === url) {
+        target['x-scalar-selected-server'] = target.servers[0]?.url ?? undefined;
+    }
 };
-const updateServerVariables = (document, { index, key, value, meta }) => {
-  const target = getServerTarget(document, meta);
-  const variable = target?.servers?.[index]?.variables?.[key];
-  if (!variable) {
-    console.error("Variable not found", key, index);
-    return;
-  }
-  variable.default = value;
-  return variable;
+/**
+ * Clears all servers from the document or operation based on meta.
+ *
+ * @param document - The document to clear the servers from
+ * @param meta - Target context (document or operation)
+ */
+export const clearServers = (document, { meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target) {
+        return;
+    }
+    // Remove the servers array
+    target.servers = undefined;
+    // Clear the selected server
+    target['x-scalar-selected-server'] = undefined;
 };
-const updateSelectedServer = (document, { url, meta }) => {
-  const target = getServerTarget(document, meta);
-  if (!target) {
-    return;
-  }
-  if (url === "") {
-    target["x-scalar-selected-server"] = "";
-    return "";
-  }
-  target["x-scalar-selected-server"] = target["x-scalar-selected-server"] === url ? "" : url;
-  return target["x-scalar-selected-server"];
+/**
+ * Updates a server variable for the document or operation based on meta.
+ *
+ * @param document - The document to update the server variables in
+ * @param index - The index of the server to update
+ * @param key - The key of the variable to update
+ * @param value - The new value of the variable
+ * @param meta - Target context (document or operation)
+ * @returns the updated variable or undefined if the variable is not found
+ */
+export const updateServerVariables = (document, { index, key, value, meta }) => {
+    const target = getServerTarget(document, meta);
+    const variable = target?.servers?.[index]?.variables?.[key];
+    if (!variable) {
+        console.error('Variable not found', key, index);
+        return;
+    }
+    variable.default = value;
+    return variable;
 };
-const serverMutatorsFactory = ({ document }) => {
-  return {
-    initializeServers: (payload) => initializeServers(document, payload),
-    addServer: (payload) => addServer(document, payload),
-    updateServer: (payload) => updateServer(document, payload),
-    deleteServer: (payload) => deleteServer(document, payload),
-    clearServers: (payload) => clearServers(document, payload),
-    updateServerVariables: (payload) => updateServerVariables(document, payload),
-    updateSelectedServer: (payload) => updateSelectedServer(document, payload)
-  };
+/**
+ * Updates the selected server for the document or operation based on meta.
+ *
+ * @param document - The document to update the selected server in
+ * @param url - The URL of the server to select (or '' to clear)
+ * @param meta - Target context (document or operation)
+ * @returns the url of the selected server or undefined if the target is not found
+ */
+export const updateSelectedServer = (document, { url, meta }) => {
+    const target = getServerTarget(document, meta);
+    if (!target) {
+        return;
+    }
+    if (url === '') {
+        target['x-scalar-selected-server'] = '';
+        return '';
+    }
+    target['x-scalar-selected-server'] = target['x-scalar-selected-server'] === url ? '' : url;
+    return target['x-scalar-selected-server'];
 };
-export {
-  addServer,
-  clearServers,
-  deleteServer,
-  initializeServers,
-  serverMutatorsFactory,
-  updateSelectedServer,
-  updateServer,
-  updateServerVariables
+export const serverMutatorsFactory = ({ document }) => {
+    return {
+        initializeServers: (payload) => initializeServers(document, payload),
+        addServer: (payload) => addServer(document, payload),
+        updateServer: (payload) => updateServer(document, payload),
+        deleteServer: (payload) => deleteServer(document, payload),
+        clearServers: (payload) => clearServers(document, payload),
+        updateServerVariables: (payload) => updateServerVariables(document, payload),
+        updateSelectedServer: (payload) => updateSelectedServer(document, payload),
+    };
 };
-//# sourceMappingURL=server.js.map