@scalar/workspace-store 0.40.2 → 0.40.4

package/dist/navigation/helpers/get-x-keys.js

@@ -1,10 +1,14 @@
-const getXKeysFromObject = (object) => {
-  if (!object) {
-    return {};
-  }
-  return Object.fromEntries(Object.entries(object).filter(([key]) => key.startsWith("x-")));
+/**
+ * Utility function to extract all keys starting with 'x-' (OpenAPI extensions) from an object.
+ *
+ * @param object - The object from which to extract extension keys.
+ * @returns An object containing only the entries whose keys start with 'x-'.
+ */
+export const getXKeysFromObject = (object) => {
+    if (!object) {
+        // Return an empty object if input is undefined or null
+        return {};
+    }
+    // Filter and return only the entries whose keys start with 'x-'
+    return Object.fromEntries(Object.entries(object).filter(([key]) => key.startsWith('x-')));
 };
-export {
-  getXKeysFromObject
-};
-//# sourceMappingURL=get-x-keys.js.map

package/dist/navigation/helpers/traverse-description.js

@@ -1,78 +1,96 @@
-import { getHeadingsFromMarkdown, getLowestHeadingLevel } from "../../navigation/helpers/utils.js";
+import { getHeadingsFromMarkdown, getLowestHeadingLevel } from '../../navigation/helpers/utils.js';
 const DEFAULT_DESCRIPTION_ENTRY = {
-  TITLE: "Introduction",
-  SLUG: "introduction"
+    TITLE: 'Introduction',
+    SLUG: 'introduction',
 };
-const traverseDescription = ({
-  generateId,
-  parentId,
-  info
-}) => {
-  const description = info.description?.trim();
-  if (!description) {
-    return [];
-  }
-  const headings = getHeadingsFromMarkdown(description);
-  const lowestLevel = getLowestHeadingLevel(headings);
-  const entries = [];
-  let descriptionHeadingsEntry = null;
-  let currentParent = null;
-  if (!description.startsWith("#")) {
-    const heading = {
-      depth: 1,
-      value: DEFAULT_DESCRIPTION_ENTRY.TITLE,
-      slug: DEFAULT_DESCRIPTION_ENTRY.SLUG
-    };
-    const id = generateId({
-      type: "text",
-      depth: heading.depth,
-      slug: heading.slug,
-      parentId,
-      info,
-      value: heading.value
-    });
-    const entry = {
-      id,
-      title: heading.value,
-      type: "text"
-    };
-    entries.push(entry);
-    descriptionHeadingsEntry = entry;
-  }
-  for (const heading of headings) {
-    if (heading.depth !== lowestLevel && heading.depth !== lowestLevel + 1) {
-      continue;
+/**
+ * Creates a hierarchical navigation structure from markdown headings in an OpenAPI description.
+ *
+ * The function processes markdown headings to create a two-level navigation tree:
+ * - Level 1: Main sections (based on the lowest heading level found)
+ * - Level 2: Subsections (one level deeper than the main sections)
+ *
+ * If the description starts with content rather than a heading, an "Introduction" section
+ * is automatically added as the first entry.
+ *
+ * @param description - The markdown description text to process
+ * @param generateId - Function to generate unique IDs for headings
+ * @param parentId - The ID of the parent entry
+ * @param info - OpenAPI Info Object
+ *
+ * @returns Array of TraversedDescription entries with their hierarchy
+ */
+export const traverseDescription = ({ generateId, parentId, info, }) => {
+    const description = info.description?.trim();
+    // No description, return empty array
+    if (!description) {
+        return [];
     }
-    const entry = {
-      id: generateId({
-        type: "text",
-        depth: heading.depth,
-        slug: heading.slug,
-        parentId,
-        info,
-        value: heading.value
-      }),
-      title: heading.value,
-      type: "text"
-    };
-    if (heading.depth === lowestLevel) {
-      entry.children = [];
-      if (descriptionHeadingsEntry) {
-        if (!descriptionHeadingsEntry.children) {
-          descriptionHeadingsEntry.children = [];
-        }
-        descriptionHeadingsEntry.children.push(entry);
-      } else {
+    const headings = getHeadingsFromMarkdown(description);
+    const lowestLevel = getLowestHeadingLevel(headings);
+    const entries = [];
+    let descriptionHeadingsEntry = null;
+    let currentParent = null;
+    // Add "Introduction" as the first heading
+    if (!description.startsWith('#')) {
+        const heading = {
+            depth: 1,
+            value: DEFAULT_DESCRIPTION_ENTRY.TITLE,
+            slug: DEFAULT_DESCRIPTION_ENTRY.SLUG,
+        };
+        const id = generateId({
+            type: 'text',
+            depth: heading.depth,
+            slug: heading.slug,
+            parentId: parentId,
+            info,
+            value: heading.value,
+        });
+        const entry = {
+            id,
+            title: heading.value,
+            type: 'text',
+        };
+        // Push to entries
         entries.push(entry);
-      }
-      currentParent = entry;
-    } else if (currentParent) {
-      currentParent.children?.push(entry);
+        descriptionHeadingsEntry = entry;
     }
-  }
-  return entries;
-};
-export {
-  traverseDescription
+    // Go through each heading
+    for (const heading of headings) {
+        // Skip if not a main or sub heading
+        if (heading.depth !== lowestLevel && heading.depth !== lowestLevel + 1) {
+            continue;
+        }
+        const entry = {
+            id: generateId({
+                type: 'text',
+                depth: heading.depth,
+                slug: heading.slug,
+                parentId: parentId,
+                info: info,
+                value: heading.value,
+            }),
+            title: heading.value,
+            type: 'text',
+        };
+        if (heading.depth === lowestLevel) {
+            entry.children = [];
+            // Add to description headings to the 'Introduction' entry
+            if (descriptionHeadingsEntry) {
+                if (!descriptionHeadingsEntry.children) {
+                    descriptionHeadingsEntry.children = [];
+                }
+                descriptionHeadingsEntry.children.push(entry);
+            }
+            // If no 'Introduction' entry, add to entries
+            else {
+                entries.push(entry);
+            }
+            currentParent = entry;
+        }
+        else if (currentParent) {
+            currentParent.children?.push(entry);
+        }
+    }
+    return entries;
 };
-//# sourceMappingURL=traverse-description.js.map

package/dist/navigation/helpers/traverse-document.js

@@ -1,102 +1,115 @@
-import { unpackProxyObject } from "../../helpers/unpack-proxy.js";
-import { getNavigationOptions } from "../../navigation/get-navigation-options.js";
-import { traverseDescription } from "./traverse-description.js";
-import { traversePaths } from "./traverse-paths.js";
-import { traverseSchemas } from "./traverse-schemas.js";
-import { traverseTags } from "./traverse-tags.js";
-import { traverseWebhooks } from "./traverse-webhooks.js";
-const traverseDocument = (documentName, document, options) => {
-  const { hideModels, tagsSorter, operationsSorter, generateId } = getNavigationOptions(documentName, options);
-  const documentId = generateId({
-    type: "document",
-    info: document.info,
-    name: documentName
-  });
-  const tagsMap = new Map(
-    document.tags?.map((tag) => [
-      tag.name ?? "Untitled Tag",
-      { id: generateId({ type: "tag", tag, parentId: documentId }), parentId: documentId, tag, entries: [] }
-    ]) ?? []
-  );
-  const entries = traverseDescription({
-    generateId,
-    parentId: documentId,
-    info: document.info
-  });
-  const { untaggedOperations } = traversePaths({ document, tagsMap, generateId, documentId });
-  const untaggedWebhooksParentId = generateId({
-    type: "webhook",
-    name: "",
-    parentId: documentId
-  });
-  const untaggedWebhooks = traverseWebhooks({
-    document,
-    generateId,
-    tagsMap,
-    untaggedWebhooksParentId,
-    documentId
-  });
-  const tagsEntries = traverseTags({
-    document,
-    tagsMap,
-    documentId,
-    options: { tagsSorter, operationsSorter, generateId }
-  });
-  entries.push(...tagsEntries);
-  entries.push(...untaggedOperations);
-  if (untaggedWebhooks.length) {
-    entries.push({
-      type: "tag",
-      id: untaggedWebhooksParentId,
-      title: "Webhooks",
-      name: "Webhooks",
-      children: untaggedWebhooks,
-      isGroup: false,
-      isWebhooks: true
+import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
+import { getNavigationOptions } from '../../navigation/get-navigation-options.js';
+import { traverseDescription } from './traverse-description.js';
+import { traversePaths } from './traverse-paths.js';
+import { traverseSchemas } from './traverse-schemas.js';
+import { traverseTags } from './traverse-tags.js';
+import { traverseWebhooks } from './traverse-webhooks.js';
+/**
+ * Traverses an OpenAPI Document to generate navigation structure and metadata.
+ *
+ * This function processes the OpenAPI document to create:
+ * - A hierarchical navigation structure for the sidebar
+ * - A mapping of IDs to titles for mobile header navigation
+ * - Tag-based organization of operations and webhooks
+ * - Optional schema/model documentation
+ */
+export const traverseDocument = (documentName, document, options) => {
+    const { hideModels, tagsSorter, operationsSorter, generateId } = getNavigationOptions(documentName, options);
+    const documentId = generateId({
+        type: 'document',
+        info: document.info,
+        name: documentName,
     });
-  }
-  if (!hideModels && document.components?.schemas) {
-    const untaggedModels = traverseSchemas({
-      documentId,
-      document,
-      generateId,
-      tagsMap
+    /** Map of tags and their entries */
+    const tagsMap = new Map(document.tags?.map((tag) => [
+        tag.name ?? 'Untitled Tag',
+        { id: generateId({ type: 'tag', tag, parentId: documentId }), parentId: documentId, tag, entries: [] },
+    ]) ?? []);
+    /** Generate entries for the document info description field */
+    const entries = traverseDescription({
+        generateId,
+        parentId: documentId,
+        info: document.info,
     });
-    if (untaggedModels.length) {
-      entries.push({
-        type: "models",
-        id: generateId({
-          type: "model",
-          parentId: documentId
-        }),
-        title: "Models",
-        name: "Models",
-        children: untaggedModels
-      });
-    }
-  }
-  const sortOrder = document["x-scalar-order"];
-  if (sortOrder) {
-    entries.sort((a, b) => {
-      const indexA = sortOrder.indexOf(a.id);
-      const indexB = sortOrder.indexOf(b.id);
-      const safeIndexA = indexA === -1 ? Number.POSITIVE_INFINITY : indexA;
-      const safeIndexB = indexB === -1 ? Number.POSITIVE_INFINITY : indexB;
-      return safeIndexA - safeIndexB;
+    /** Traverse all the document path  */
+    const { untaggedOperations } = traversePaths({ document, tagsMap, generateId, documentId });
+    const untaggedWebhooksParentId = generateId({
+        type: 'webhook',
+        name: '',
+        parentId: documentId,
     });
-  }
-  document["x-scalar-order"] = unpackProxyObject(entries.map((entry) => entry.id));
-  const documentTitle = document.info?.title?.trim() || "Untitled Document";
-  return {
-    id: documentId,
-    type: "document",
-    title: documentTitle,
-    name: documentName,
-    children: entries,
-    icon: document["x-scalar-icon"]
-  };
-};
-export {
-  traverseDocument
+    const untaggedWebhooks = traverseWebhooks({
+        document,
+        generateId,
+        tagsMap,
+        untaggedWebhooksParentId,
+        documentId,
+    });
+    const tagsEntries = traverseTags({
+        document,
+        tagsMap,
+        documentId,
+        options: { tagsSorter, operationsSorter, generateId },
+    });
+    // Add tagged operations, webhooks and tagGroups
+    entries.push(...tagsEntries);
+    // Add untagged operations
+    entries.push(...untaggedOperations);
+    // Add untagged webhooks
+    if (untaggedWebhooks.length) {
+        entries.push({
+            type: 'tag',
+            id: untaggedWebhooksParentId,
+            title: 'Webhooks',
+            name: 'Webhooks',
+            children: untaggedWebhooks,
+            isGroup: false,
+            isWebhooks: true,
+        });
+    }
+    // Add models if they are not hidden
+    if (!hideModels && document.components?.schemas) {
+        const untaggedModels = traverseSchemas({
+            documentId,
+            document,
+            generateId,
+            tagsMap,
+        });
+        if (untaggedModels.length) {
+            entries.push({
+                type: 'models',
+                id: generateId({
+                    type: 'model',
+                    parentId: documentId,
+                }),
+                title: 'Models',
+                name: 'Models',
+                children: untaggedModels,
+            });
+        }
+    }
+    const sortOrder = document['x-scalar-order'];
+    // Try to sort the entries using the x-scalar-order
+    if (sortOrder) {
+        entries.sort((a, b) => {
+            const indexA = sortOrder.indexOf(a.id);
+            const indexB = sortOrder.indexOf(b.id);
+            // If an id is not found, treat it as "infinity" so those items go last.
+            const safeIndexA = indexA === -1 ? Number.POSITIVE_INFINITY : indexA;
+            const safeIndexB = indexB === -1 ? Number.POSITIVE_INFINITY : indexB;
+            return safeIndexA - safeIndexB;
+        });
+    }
+    // Now update the sort order of the entries
+    document['x-scalar-order'] = unpackProxyObject(entries.map((entry) => entry.id));
+    const documentTitle = document.info?.title?.trim() || 'Untitled Document';
+    return {
+        id: documentId,
+        type: 'document',
+        title: documentTitle,
+        name: documentName,
+        children: entries,
+        icon: document['x-scalar-icon'],
+    };
 };
-//# sourceMappingURL=traverse-document.js.map

package/dist/navigation/helpers/traverse-examples.js

@@ -1,34 +1,38 @@
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-const traverseOperationExamples = (operation) => {
-  const examples = new Set(operation["x-draft-examples"] ?? []);
-  if (operation.requestBody) {
-    const requestBody = getResolvedRef(operation.requestBody);
-    Object.values(requestBody.content ?? {}).forEach((mediaType) => {
-      Object.keys(mediaType.examples ?? {}).forEach((key) => {
-        examples.add(key);
-      });
-    });
-  }
-  if (operation.parameters) {
-    operation.parameters.forEach((_parameter) => {
-      const parameter = getResolvedRef(_parameter) ?? {};
-      if ("content" in parameter && parameter.content) {
-        Object.values(parameter.content).forEach((mediaType) => {
-          Object.keys(mediaType.examples ?? {}).forEach((key) => {
-            examples.add(key);
-          });
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+/**
+ * Traverse the OpenAPI operation object and extract all example values.
+ *
+ * @param operation - The OpenAPI operation object to extract examples from
+ */
+export const traverseOperationExamples = (operation) => {
+    // Add all examples from draft examples
+    const examples = new Set(operation['x-draft-examples'] ?? []);
+    // Add all examples from request bodies
+    if (operation.requestBody) {
+        const requestBody = getResolvedRef(operation.requestBody);
+        Object.values(requestBody.content ?? {}).forEach((mediaType) => {
+            Object.keys(mediaType.examples ?? {}).forEach((key) => {
+                examples.add(key);
+            });
         });
-      }
-      if ("examples" in parameter && parameter.examples) {
-        Object.keys(parameter.examples ?? {}).forEach((key) => {
-          examples.add(key);
+    }
+    // Add all examples from parameters
+    if (operation.parameters) {
+        operation.parameters.forEach((_parameter) => {
+            const parameter = getResolvedRef(_parameter) ?? {};
+            if ('content' in parameter && parameter.content) {
+                Object.values(parameter.content).forEach((mediaType) => {
+                    Object.keys(mediaType.examples ?? {}).forEach((key) => {
+                        examples.add(key);
+                    });
+                });
+            }
+            if ('examples' in parameter && parameter.examples) {
+                Object.keys(parameter.examples ?? {}).forEach((key) => {
+                    examples.add(key);
+                });
+            }
         });
-      }
-    });
-  }
-  return Array.from(examples);
+    }
+    return Array.from(examples);
 };
-export {
-  traverseOperationExamples
-};
-//# sourceMappingURL=traverse-examples.js.map