@scalar/workspace-store 0.40.2 → 0.40.4

package/dist/mutators/workspace.js

@@ -1,48 +1,78 @@
-const updateActiveProxy = (workspace, payload) => {
-  if (!workspace) {
-    return;
-  }
-  workspace["x-scalar-active-proxy"] = payload;
+/**
+ * Updates the active proxy for the given workspace.
+ *
+ * @param workspace - The workspace to update
+ * @param payload - The new active proxy value
+ */
+export const updateActiveProxy = (workspace, payload) => {
+    // If workspace is null, exit early
+    if (!workspace) {
+        return;
+    }
+    // Set or clear the active proxy in the workspace object
+    workspace['x-scalar-active-proxy'] = payload;
 };
-const updateColorMode = (workspace, payload) => {
-  if (!workspace) {
-    return;
-  }
-  workspace["x-scalar-color-mode"] = payload;
+/**
+ * Updates the color mode for the given workspace.
+ *
+ * @param workspace - The workspace to update
+ * @param payload - The new color mode value
+ */
+export const updateColorMode = (workspace, payload) => {
+    // If workspace is null, do nothing
+    if (!workspace) {
+        return;
+    }
+    // Set the color mode in the workspace object
+    workspace['x-scalar-color-mode'] = payload;
 };
-const updateTheme = (workspace, payload) => {
-  if (!workspace) {
-    return;
-  }
-  workspace["x-scalar-theme"] = payload;
+/**
+ * Updates the theme for the given workspace.
+ *
+ * @param workspace - The workspace to update
+ * @param payload - The new theme value
+ */
+export const updateTheme = (workspace, payload) => {
+    // If workspace is null, exit early
+    if (!workspace) {
+        return;
+    }
+    // Set the theme in the workspace object
+    workspace['x-scalar-theme'] = payload;
 };
-const updateActiveEnvironment = (workspace, payload) => {
-  if (!workspace) {
-    return;
-  }
-  workspace["x-scalar-active-environment"] = payload ?? void 0;
+/**
+ * Updates the active environment for the given workspace.
+ *
+ * @param workspace - The workspace to update
+ * @param payload - The new active environment value
+ */
+export const updateActiveEnvironment = (workspace, payload) => {
+    // If workspace is null, exit early
+    if (!workspace) {
+        return;
+    }
+    // Set the active environment in the workspace object
+    workspace['x-scalar-active-environment'] = payload ?? undefined;
 };
-const updateSelectedClient = (workspace, payload) => {
-  if (!workspace) {
-    return;
-  }
-  workspace["x-scalar-default-client"] = payload;
+/**
+ * Updates the selected http client on the workspace
+ *
+ * @param workspace - The workspace to update the selected http client in
+ * @param payload - The payload to update the selected client with
+ * @returns
+ */
+export const updateSelectedClient = (workspace, payload) => {
+    if (!workspace) {
+        return;
+    }
+    workspace['x-scalar-default-client'] = payload;
 };
-const workspaceMutatorsFactory = ({ workspace }) => {
-  return {
-    updateActiveProxy: (payload) => updateActiveProxy(workspace, payload),
-    updateColorMode: (payload) => updateColorMode(workspace, payload),
-    updateTheme: (payload) => updateTheme(workspace, payload),
-    updateSelectedClient: (payload) => updateSelectedClient(workspace, payload),
-    updateActiveEnvironment: (payload) => updateActiveEnvironment(workspace, payload)
-  };
+export const workspaceMutatorsFactory = ({ workspace }) => {
+    return {
+        updateActiveProxy: (payload) => updateActiveProxy(workspace, payload),
+        updateColorMode: (payload) => updateColorMode(workspace, payload),
+        updateTheme: (payload) => updateTheme(workspace, payload),
+        updateSelectedClient: (payload) => updateSelectedClient(workspace, payload),
+        updateActiveEnvironment: (payload) => updateActiveEnvironment(workspace, payload),
+    };
 };
-export {
-  updateActiveEnvironment,
-  updateActiveProxy,
-  updateColorMode,
-  updateSelectedClient,
-  updateTheme,
-  workspaceMutatorsFactory
-};
-//# sourceMappingURL=workspace.js.map

package/dist/navigation/get-navigation-options.js

@@ -1,85 +1,98 @@
-import { slug } from "github-slugger";
-const getNavigationOptions = (documentName, options) => {
-  const generateId = (props) => {
-    const documentId = `${slug(documentName)}`;
-    if (props.type === "text") {
-      if (options?.generateHeadingSlug) {
-        return options?.generateHeadingSlug({ slug: props.slug });
-      }
-      if (props.slug) {
-        return `${documentId}/description/${props.slug}`;
-      }
-      return `${documentId}/`;
-    }
-    if (props.type === "tag") {
-      if (options?.generateTagSlug) {
-        return `${documentId}/tag/${options.generateTagSlug(props.tag)}`;
-      }
-      return `${documentId}/tag/${slug(props.tag.name ?? "")}`;
-    }
-    if (props.type === "operation") {
-      const prefixTag = props.parentTag ? `${generateId({
-        type: "tag",
-        tag: props.parentTag.tag,
-        parentId: props.parentTag.id
-      })}/` : `${documentId}/`;
-      if (options?.generateOperationSlug) {
-        return `${prefixTag}${options.generateOperationSlug({
-          path: props.path,
-          operationId: props.operation.operationId,
-          method: props.method.toUpperCase(),
-          summary: props.operation.summary
-        })}`;
-      }
-      return `${prefixTag}${props.method.toUpperCase()}${props.path}`;
-    }
-    if (props.type === "webhook") {
-      const prefixTag = props.parentTag ? `${generateId({
-        type: "tag",
-        parentId: props.parentTag.id,
-        tag: props.parentTag.tag
-      })}/` : `${documentId}/`;
-      if (options?.generateWebhookSlug) {
-        return `${prefixTag}webhook/${options.generateWebhookSlug({
-          name: props.name,
-          method: props.method?.toUpperCase()
-        })}`;
-      }
-      return `${prefixTag}webhook/${props.method?.toUpperCase()}/${slug(props.name)}`;
-    }
-    if (props.type === "model") {
-      if (!props.name) {
-        return `${documentId}/models`;
-      }
-      const prefixTag = props.parentTag ? `${generateId({
-        type: "tag",
-        parentId: props.parentTag.id,
-        tag: props.parentTag.tag
-      })}/` : `${documentId}/`;
-      if (options?.generateModelSlug) {
-        return `${prefixTag}model/${options.generateModelSlug({
-          name: props.name
-        })}`;
-      }
-      return `${prefixTag}model/${slug(props.name, true)}`;
-    }
-    if (props.type === "example") {
-      return `${props.parentId}/example/${slug(props.name)}`;
-    }
-    if (props.type === "document") {
-      return documentId;
-    }
-    console.warn("[WARNING]: unhandled id generation for navigation item:", props);
-    return "unknown-id";
-  };
-  return {
-    hideModels: options?.hideModels ?? false,
-    operationsSorter: options?.operationsSorter,
-    tagsSorter: options?.tagsSorter,
-    generateId
-  };
+import { slug } from 'github-slugger';
+/**
+ * Returns options for traversing an OpenAPI document, allowing customization of
+ * how IDs and slugs are generated for tags, headings, models, operations, and webhooks.
+ * The returned options can be influenced by the provided DocumentConfiguration
+ */
+export const getNavigationOptions = (documentName, options) => {
+    const generateId = (props) => {
+        const documentId = `${slug(documentName)}`;
+        // -------- Default text id generation logic --------
+        if (props.type === 'text') {
+            if (options?.generateHeadingSlug) {
+                return options?.generateHeadingSlug({ slug: props.slug });
+            }
+            if (props.slug) {
+                return `${documentId}/description/${props.slug}`;
+            }
+            return `${documentId}/`;
+        }
+        // -------- Default tag id generation logic --------
+        if (props.type === 'tag') {
+            if (options?.generateTagSlug) {
+                return `${documentId}/tag/${options.generateTagSlug(props.tag)}`;
+            }
+            return `${documentId}/tag/${slug(props.tag.name ?? '')}`;
+        }
+        // -------- Default operation id generation logic --------
+        if (props.type === 'operation') {
+            const prefixTag = props.parentTag
+                ? `${generateId({
+                    type: 'tag',
+                    tag: props.parentTag.tag,
+                    parentId: props.parentTag.id,
+                })}/`
+                : `${documentId}/`;
+            if (options?.generateOperationSlug) {
+                return `${prefixTag}${options.generateOperationSlug({
+                    path: props.path,
+                    operationId: props.operation.operationId,
+                    method: props.method.toUpperCase(),
+                    summary: props.operation.summary,
+                })}`;
+            }
+            return `${prefixTag}${props.method.toUpperCase()}${props.path}`;
+        }
+        // -------- Default webhook id generation logic --------
+        if (props.type === 'webhook') {
+            const prefixTag = props.parentTag
+                ? `${generateId({
+                    type: 'tag',
+                    parentId: props.parentTag.id,
+                    tag: props.parentTag.tag,
+                })}/`
+                : `${documentId}/`;
+            if (options?.generateWebhookSlug) {
+                return `${prefixTag}webhook/${options.generateWebhookSlug({
+                    name: props.name,
+                    method: props.method?.toUpperCase(),
+                })}`;
+            }
+            return `${prefixTag}webhook/${props.method?.toUpperCase()}/${slug(props.name)}`;
+        }
+        // -------- Default model id generation logic --------
+        if (props.type === 'model') {
+            if (!props.name) {
+                return `${documentId}/models`;
+            }
+            const prefixTag = props.parentTag
+                ? `${generateId({
+                    type: 'tag',
+                    parentId: props.parentTag.id,
+                    tag: props.parentTag.tag,
+                })}/`
+                : `${documentId}/`;
+            if (options?.generateModelSlug) {
+                return `${prefixTag}model/${options.generateModelSlug({
+                    name: props.name,
+                })}`;
+            }
+            return `${prefixTag}model/${slug(props.name, true)}`;
+        }
+        if (props.type === 'example') {
+            return `${props.parentId}/example/${slug(props.name)}`;
+        }
+        if (props.type === 'document') {
+            // -------- Default document id generation logic --------
+            return documentId;
+        }
+        console.warn('[WARNING]: unhandled id generation for navigation item:', props);
+        return 'unknown-id';
+    };
+    return {
+        hideModels: options?.hideModels ?? false,
+        operationsSorter: options?.operationsSorter,
+        tagsSorter: options?.tagsSorter,
+        generateId,
+    };
 };
-export {
-  getNavigationOptions
-};
-//# sourceMappingURL=get-navigation-options.js.map

package/dist/navigation/helpers/get-openapi-object.js

@@ -1,31 +1,48 @@
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-import { getParentEntry } from "./get-parent-entry.js";
-const canHaveOrder = (entry) => entry.type === "document" || entry.type === "tag" || entry.type === "operation";
-const getOpenapiObject = ({
-  store,
-  entry
-}) => {
-  const documentEntry = getParentEntry("document", entry);
-  if (!documentEntry) {
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { getParentEntry } from './get-parent-entry.js';
+/** Type guard which checks if the entry has an x-scalar-order property */
+export const canHaveOrder = (entry) => entry.type === 'document' || entry.type === 'tag' || entry.type === 'operation';
+/**
+ * Retrieves the corresponding OpenAPI object (document, tag, or operation) from the workspace store based on the provided entry.
+ *
+ * This helper abstracts the common lookup logic for working with sidebar/drag-and-drop entries and their associated OpenAPI objects.
+ * Returns `null` when the lookup cannot be completed (e.g., document/tag/operation not found).
+ *
+ * @template Entry Either TraversedDocument, TraversedTag, or TraversedOperation.
+ * @param store - The workspace store containing loaded documents.
+ * @param entry - The sidebar entry (document, tag, or operation).
+ * @returns The corresponding OpenAPI object (WorkspaceDocument, TagObject, or OperationObject) or `null` if not found.
+ *
+ * @example
+ * // For a Document entry:
+ * const document = getOpenapiObject({ store, entry: documentEntry })
+ *
+ * // For a Tag entry:
+ * const tag = getOpenapiObject({ store, entry: tagEntry })
+ *
+ * // For an Operation entry:
+ * const operation = getOpenapiObject({ store, entry: operationEntry })
+ */
+export const getOpenapiObject = ({ store, entry, }) => {
+    const documentEntry = getParentEntry('document', entry);
+    if (!documentEntry) {
+        return null;
+    }
+    const document = store.workspace.documents[documentEntry.name];
+    if (!document) {
+        return null;
+    }
+    if (entry.type === 'document') {
+        return document;
+    }
+    if (entry.type === 'tag') {
+        // Find the tag by name in the document's tags array
+        return document.tags?.find((tag) => tag.name === entry.name) ?? null;
+    }
+    if (entry.type === 'operation') {
+        // Fetch and resolve the referenced operation object at the given path/method
+        return getResolvedRef(document.paths?.[entry.path]?.[entry.method]) ?? null;
+    }
+    // If entry type is unknown, return null
     return null;
-  }
-  const document = store.workspace.documents[documentEntry.name];
-  if (!document) {
-    return null;
-  }
-  if (entry.type === "document") {
-    return document;
-  }
-  if (entry.type === "tag") {
-    return document.tags?.find((tag) => tag.name === entry.name) ?? null;
-  }
-  if (entry.type === "operation") {
-    return getResolvedRef(document.paths?.[entry.path]?.[entry.method]) ?? null;
-  }
-  return null;
-};
-export {
-  canHaveOrder,
-  getOpenapiObject
 };
-//# sourceMappingURL=get-openapi-object.js.map

package/dist/navigation/helpers/get-operation-entries.js

@@ -1,33 +1,73 @@
-const getOperationEntries = (document) => {
-  const map = /* @__PURE__ */ new Map();
-  const addToMap = (key, entry) => {
-    const existing = map.get(key);
-    if (existing) {
-      existing.push(entry);
-    } else {
-      map.set(key, [entry]);
-    }
-  };
-  const traverse = (entries, parent) => {
-    if (!entries) {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.type === "operation") {
-        const key = `${entry.path}|${entry.method}`;
-        addToMap(key, { ...entry, parent });
-      } else if (entry.type === "webhook") {
-        const key = `${entry.name}|${entry.method}`;
-        addToMap(key, { ...entry, parent });
-      } else if ("children" in entry && entry.children) {
-        traverse(entry.children, { ...entry, parent });
-      }
-    }
-  };
-  traverse(document.children, document);
-  return map;
+/**
+ * Builds a map of all operations and webhooks in a document, indexed by path/name and method.
+ *
+ * This function recursively traverses the document structure and collects all operation and webhook
+ * entries. Multiple entries can share the same path|method key (for example, when operations are
+ * duplicated across different tags or groups).
+ *
+ * ~Performance note: If this function is called frequently, consider generating this map once when
+ * creating the sidebar state rather than recalculating it in mutators.~
+ * Update: we are now generating it features/operation and its drilled down from there
+ *
+ * @param document - The traversed OpenAPI document to extract operations from
+ * @returns A map where keys are `path|method` (for operations) or `name|method` (for webhooks),
+ *          and values are arrays of matching entries. The pipe separator is used to create a
+ *          unique composite key from the two parts.
+ *
+ * @example
+ * const entries = getOperationEntries(document)
+ * const getUsers = entries.get('/users|get') // Array of all GET /users operations
+ */
+export const getOperationEntries = (document) => {
+    const map = new Map();
+    /**
+     * Helper function to add an entry to the map under the specified key.
+     * If the key already exists, appends to the array; otherwise creates a new array.
+     *
+     * @param key - The composite key (path|method or name|method)
+     * @param entry - The operation or webhook entry to add (with parent information)
+     */
+    const addToMap = (key, entry) => {
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            map.set(key, [entry]);
+        }
+    };
+    /**
+     * Recursively traverses the document tree to find all operations and webhooks.
+     * Handles three entry types:
+     * - operations: collected into the map using path|method as key
+     * - webhooks: collected into the map using name|method as key
+     * - containers (tags, groups): recursively traversed for their children
+     *
+     * @param entries - Array of entries to traverse (may be undefined for empty sections)
+     * @param parent - The parent entry of the current entries (if any)
+     */
+    const traverse = (entries, parent) => {
+        if (!entries) {
+            return;
+        }
+        for (const entry of entries) {
+            // Handle operations - use path and method to create unique key
+            if (entry.type === 'operation') {
+                const key = `${entry.path}|${entry.method}`;
+                addToMap(key, { ...entry, parent });
+            }
+            // Handle webhooks - use name and method to create unique key
+            else if (entry.type === 'webhook') {
+                const key = `${entry.name}|${entry.method}`;
+                addToMap(key, { ...entry, parent });
+            }
+            // Handle containers - recursively traverse children, passing current entry as parent
+            else if ('children' in entry && entry.children) {
+                traverse(entry.children, { ...entry, parent });
+            }
+        }
+    };
+    // Start traversal from document root
+    traverse(document.children, document);
+    return map;
 };
-export {
-  getOperationEntries
-};
-//# sourceMappingURL=get-operation-entries.js.map

package/dist/navigation/helpers/get-parent-entry.js

@@ -1,13 +1,17 @@
-const getParentEntry = (type, node) => {
-  if (!node) {
-    return void 0;
-  }
-  if (node.type === type) {
-    return node;
-  }
-  return getParentEntry(type, node.parent);
+/**
+ * Traverses up the tree to find and return the closest parent node (including self) of a specified type.
+ *
+ * @template Type - The type of node to look for.
+ * @param type - The type to match in the parent chain.
+ * @param node - The node from which traversal begins.
+ * @returns The closest parent node of the specified type, or undefined if not found.
+ */
+export const getParentEntry = (type, node) => {
+    if (!node) {
+        return undefined;
+    }
+    if (node.type === type) {
+        return node;
+    }
+    return getParentEntry(type, node.parent);
 };
-export {
-  getParentEntry
-};
-//# sourceMappingURL=get-parent-entry.js.map

package/dist/navigation/helpers/get-tag-entries.js

@@ -1,30 +1,57 @@
-const getTagEntries = (document) => {
-  const map = /* @__PURE__ */ new Map();
-  const addToMap = (key, entry) => {
-    const existing = map.get(key);
-    if (existing) {
-      existing.push(entry);
-    } else {
-      map.set(key, [entry]);
-    }
-  };
-  const traverse = (entries, parent) => {
-    if (!entries) {
-      return;
-    }
-    for (const entry of entries) {
-      if (entry.type === "tag") {
-        addToMap(entry.name, { ...entry, parent });
-        traverse(entry.children, { ...entry, parent });
-      } else if ("children" in entry && entry.children) {
-        traverse(entry.children, { ...entry, parent });
-      }
-    }
-  };
-  traverse(document.children, document);
-  return map;
+/**
+ * Builds a map of all tag entries in a document, indexed by tag name.
+ *
+ * Tags with the same name can appear more than once (for example, when the same tag
+ * is referenced in multiple x-tagGroups), so each key maps to an array of matches.
+ *
+ * This is the tag-side counterpart to `getOperationEntries`. Keep them separate so
+ * callers only pay for the traversal they actually need.
+ *
+ * @param document - The traversed OpenAPI document to extract tags from
+ * @returns A map where keys are tag names and values are arrays of matching tag entries,
+ *          each decorated with a `parent` reference for walking up the tree.
+ *
+ * @example
+ * const tags = getTagEntries(document)
+ * const userTagEntries = tags.get('Users') // All tag entries named "Users"
+ */
+export const getTagEntries = (document) => {
+    const map = new Map();
+    /**
+     * Appends an entry to the array stored at `key`, creating the array if needed.
+     */
+    const addToMap = (key, entry) => {
+        const existing = map.get(key);
+        if (existing) {
+            existing.push(entry);
+        }
+        else {
+            map.set(key, [entry]);
+        }
+    };
+    /**
+     * Recursively walks the document tree collecting tag entries.
+     * Tags can be nested (e.g. inside x-tagGroups), so we recurse into their children too.
+     *
+     * @param entries - The current level of entries to walk (may be undefined)
+     * @param parent - The parent entry or document at this level
+     */
+    const traverse = (entries, parent) => {
+        if (!entries) {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.type === 'tag') {
+                // Record this tag entry, then keep walking its children — tags can be nested
+                addToMap(entry.name, { ...entry, parent });
+                traverse(entry.children, { ...entry, parent });
+            }
+            else if ('children' in entry && entry.children) {
+                // Non-tag containers (models, documents) may still hold tags inside them
+                traverse(entry.children, { ...entry, parent });
+            }
+        }
+    };
+    traverse(document.children, document);
+    return map;
 };
-export {
-  getTagEntries
-};
-//# sourceMappingURL=get-tag-entries.js.map

package/dist/navigation/helpers/get-tag.js

@@ -1,24 +1,23 @@
-const getTag = ({
-  tagsMap,
-  name,
-  documentId,
-  generateId
-}) => {
-  if (!tagsMap.get(name)) {
-    tagsMap.set(name, {
-      id: generateId({
-        type: "tag",
-        tag: { name },
-        parentId: documentId
-      }),
-      parentId: documentId,
-      entries: [],
-      tag: { name }
-    });
-  }
-  return tagsMap.get(name);
+/**
+ * Gets or creates a tag in the tags dictionary.
+ * If the tag doesn't exist, it creates a new tag object with the given name.
+ *
+ * @param tagsDict - Map of tag names to tag objects
+ * @param name - Name of the tag to get or create
+ * @returns The tag object for the given name
+ */
+export const getTag = ({ tagsMap, name, documentId, generateId, }) => {
+    if (!tagsMap.get(name)) {
+        tagsMap.set(name, {
+            id: generateId({
+                type: 'tag',
+                tag: { name },
+                parentId: documentId,
+            }),
+            parentId: documentId,
+            entries: [],
+            tag: { name },
+        });
+    }
+    return tagsMap.get(name); // We can safely assert non-null since we just set the value if it didn't exist
 };
-export {
-  getTag
-};
-//# sourceMappingURL=get-tag.js.map