@scalar/workspace-store 0.40.2 → 0.40.3

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

@@ -1,111 +1,123 @@
-import { isHttpMethod } from "@scalar/helpers/http/is-http-method";
-import { objectKeys } from "@scalar/helpers/object/object-keys";
-import { escapeJsonPointer } from "@scalar/json-magic/helpers/escape-json-pointer";
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-import { traverseOperationExamples } from "../../navigation/helpers/traverse-examples.js";
-import { XScalarStabilityValues } from "../../schemas/extensions/operation/index.js";
-import { getTag } from "./get-tag.js";
-const isDeprecatedOperation = (operation) => {
-  return operation.deprecated || operation["x-scalar-stability"] === XScalarStabilityValues.Deprecated;
+import { isHttpMethod } from '@scalar/helpers/http/is-http-method';
+import { objectKeys } from '@scalar/helpers/object/object-keys';
+import { escapeJsonPointer } from '@scalar/json-magic/helpers/escape-json-pointer';
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { traverseOperationExamples } from '../../navigation/helpers/traverse-examples.js';
+import { XScalarStabilityValues } from '../../schemas/extensions/operation/index.js';
+import { getTag } from './get-tag.js';
+export const isDeprecatedOperation = (operation) => {
+    return operation.deprecated || operation['x-scalar-stability'] === XScalarStabilityValues.Deprecated;
 };
-const createOperationEntry = ({
-  ref,
-  operation,
-  method,
-  path,
-  generateId,
-  parentId,
-  parentTag
-}) => {
-  const id = generateId({
-    type: "operation",
-    operation,
-    parentTag,
-    method,
-    path,
-    parentId
-  });
-  const title = operation.summary?.trim() ? operation.summary : path;
-  const isDeprecated = isDeprecatedOperation(operation);
-  const examples = traverseOperationExamples(operation).map((example) => ({
-    type: "example",
-    id: generateId({
-      type: "example",
-      parentId: id,
-      name: example
-    }),
-    title: example,
-    name: example
-  }));
-  const entry = {
-    id,
-    title,
-    path,
-    method,
-    ref,
-    type: "operation",
-    isDeprecated,
-    children: examples.length ? examples : void 0
-  };
-  return entry;
+/**
+ * Creates a traversed operation entry from an OpenAPI operation object.
+ *
+ * @param ref - JSON pointer reference to the operation in the OpenAPI document
+ * @param operation - The OpenAPI operation object
+ * @param method - HTTP method of the operation
+ * @param path - API path of the operation, defaults to 'Unknown'
+ * @param tag - Tag object associated with the operation
+ * @param entitiesMap - Map to store operation IDs and titles for mobile header navigation
+ * @param getOperationId - Function to generate unique IDs for operations
+ * @returns A traversed operation entry with ID, title, path, method and reference
+ */
+const createOperationEntry = ({ ref, operation, method, path, generateId, parentId, parentTag, }) => {
+    const id = generateId({
+        type: 'operation',
+        operation,
+        parentTag,
+        method: method,
+        path: path,
+        parentId: parentId,
+    });
+    const title = operation.summary?.trim() ? operation.summary : path;
+    const isDeprecated = isDeprecatedOperation(operation);
+    const examples = traverseOperationExamples(operation).map((example) => ({
+        type: 'example',
+        id: generateId({
+            type: 'example',
+            parentId: id,
+            name: example,
+        }),
+        title: example,
+        name: example,
+    }));
+    const entry = {
+        id,
+        title,
+        path,
+        method,
+        ref,
+        type: 'operation',
+        isDeprecated,
+        children: examples.length ? examples : undefined,
+    };
+    return entry;
 };
-const traversePaths = ({
-  document,
-  tagsMap,
-  generateId,
-  documentId
-}) => {
-  const untaggedOperations = [];
-  Object.entries(document.paths ?? {}).forEach(([path, pathItemObject]) => {
-    const pathKeys = objectKeys(pathItemObject ?? {}).filter((key) => isHttpMethod(key));
-    pathKeys.forEach((method) => {
-      const _operation = pathItemObject?.[method];
-      const operation = getResolvedRef(_operation);
-      if (!operation) {
-        return;
-      }
-      if (operation["x-internal"] || operation["x-scalar-ignore"] || !isHttpMethod(method)) {
-        return;
-      }
-      const ref = `#/paths/${escapeJsonPointer(path)}/${method}`;
-      if (operation.tags?.length) {
-        operation.tags.forEach((tagName) => {
-          const { tag, id: tagId } = getTag({
-            tagsMap,
-            name: tagName,
-            documentId,
-            generateId
-          });
-          tagsMap.get(tagName)?.entries.push(
-            createOperationEntry({
-              ref,
-              operation,
-              method,
-              path,
-              parentTag: { tag, id: tagId },
-              generateId,
-              parentId: tagId
-            })
-          );
+/**
+ * Traverses the paths in an OpenAPI document to build a map of operations organized by tags.
+ *
+ * This function processes each path and its operations to:
+ * - Filter out internal operations (marked with x-internal) and operations to ignore (marked with x-scalar-ignore)
+ * - Group operations by their tags
+ * - Collect operations without tags to be added at the document level
+ * - Generate unique references and IDs for each operation
+ *
+ * TODO: filter out internal and scalar-ignore tags
+ *
+ * @param content - The OpenAPI document to traverse
+ * @param tagsDict - Dictionary mapping tag names to their OpenAPI tag objects
+ * @param entitiesMap - Map to store operation IDs and titles for mobile header navigation
+ * @param getOperationId - Function to generate unique IDs for operations
+ * @returns Object containing the tagsMap and an array of untagged operations
+ */
+export const traversePaths = ({ document, tagsMap, generateId, documentId, }) => {
+    const untaggedOperations = [];
+    // Traverse paths
+    Object.entries(document.paths ?? {}).forEach(([path, pathItemObject]) => {
+        const pathKeys = objectKeys(pathItemObject ?? {}).filter((key) => isHttpMethod(key));
+        pathKeys.forEach((method) => {
+            const _operation = pathItemObject?.[method];
+            const operation = getResolvedRef(_operation);
+            if (!operation) {
+                return;
+            }
+            // Skip if the operation is internal or scalar-ignore
+            if (operation['x-internal'] || operation['x-scalar-ignore'] || !isHttpMethod(method)) {
+                return;
+            }
+            const ref = `#/paths/${escapeJsonPointer(path)}/${method}`;
+            // Traverse tags
+            if (operation.tags?.length) {
+                operation.tags.forEach((tagName) => {
+                    const { tag, id: tagId } = getTag({
+                        tagsMap,
+                        name: tagName,
+                        documentId,
+                        generateId,
+                    });
+                    tagsMap.get(tagName)?.entries.push(createOperationEntry({
+                        ref,
+                        operation,
+                        method,
+                        path,
+                        parentTag: { tag, id: tagId },
+                        generateId,
+                        parentId: tagId,
+                    }));
+                });
+            }
+            else {
+                // Collect operations without tags (no parentTag)
+                untaggedOperations.push(createOperationEntry({
+                    ref,
+                    operation,
+                    method,
+                    path,
+                    generateId,
+                    parentId: documentId,
+                }));
+            }
         });
-      } else {
-        untaggedOperations.push(
-          createOperationEntry({
-            ref,
-            operation,
-            method,
-            path,
-            generateId,
-            parentId: documentId
-          })
-        );
-      }
     });
-  });
-  return { untaggedOperations };
-};
-export {
-  isDeprecatedOperation,
-  traversePaths
+    return { untaggedOperations };
 };
-//# sourceMappingURL=traverse-paths.js.map

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

@@ -1,67 +1,68 @@
-import { getResolvedRef } from "../../helpers/get-resolved-ref.js";
-import { getTag } from "../../navigation/helpers/get-tag.js";
-const createSchemaEntry = ({
-  ref,
-  name,
-  generateId,
-  parentTag,
-  _schema,
-  parentId
-}) => {
-  const id = generateId({ name, type: "model", parentTag, parentId, schema: _schema });
-  const schema = getResolvedRef(_schema);
-  const title = schema && "title" in schema && schema.title || name;
-  const entry = {
-    id,
-    title,
-    name,
-    ref,
-    type: "model"
-  };
-  return entry;
+import { getResolvedRef } from '../../helpers/get-resolved-ref.js';
+import { getTag } from '../../navigation/helpers/get-tag.js';
+/** Creates a traversed schema entry from an OpenAPI schema object.
+ *
+ * @param ref - JSON pointer reference to the schema in the OpenAPI document
+ * @param name - Name of the schema, defaults to 'Unknown'
+ * @param entriesMap - Map to store schema IDs and titles for mobile header navigation
+ * @param getModelId - Function to generate unique IDs for schemas
+ * @returns A traversed schema entry with ID, title, name and reference
+ */
+const createSchemaEntry = ({ ref, name, generateId, parentTag, _schema, parentId, }) => {
+    const id = generateId({ name, type: 'model', parentTag, parentId, schema: _schema });
+    const schema = getResolvedRef(_schema);
+    // Use schema.title if available, otherwise fall back to name
+    // @see https://json-schema.org/draft/2020-12/json-schema-core#section-4.3.5
+    const title = (schema && 'title' in schema && schema.title) || name;
+    const entry = {
+        id,
+        title,
+        name,
+        ref,
+        type: 'model',
+    };
+    return entry;
 };
-const traverseSchemas = ({
-  document,
-  tagsMap,
-  generateId,
-  documentId
-}) => {
-  const schemas = document.components?.schemas ?? {};
-  const untagged = [];
-  for (const name in schemas) {
-    const schema = getResolvedRef(schemas[name]);
-    if (schema?.["x-internal"] || schema?.["x-scalar-ignore"] || !Object.hasOwn(schemas, name)) {
-      continue;
+/** Traverses the schemas in an OpenAPI document to build an array of model entries.
+ *
+ * This function processes each schema in components.schemas to:
+ * - Filter out internal schemas (marked with x-internal) and schemas to ignore (marked with x-scalar-ignore)
+ * - Create model entries with unique references and IDs
+ * - Store model IDs and titles for mobile header navigation
+ */
+export const traverseSchemas = ({ document, tagsMap, generateId, documentId, }) => {
+    const schemas = document.components?.schemas ?? {};
+    const untagged = [];
+    // biome-ignore lint/suspicious/useGuardForIn: we do have an if statement after de-ref
+    for (const name in schemas) {
+        const schema = getResolvedRef(schemas[name]);
+        if (schema?.['x-internal'] || schema?.['x-scalar-ignore'] || !Object.hasOwn(schemas, name)) {
+            continue;
+        }
+        const ref = `#/components/schemas/${name}`;
+        // Add to tags
+        if (schema?.['x-tags']) {
+            schema['x-tags'].forEach((tagName) => {
+                const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
+                tagsMap.get(tagName)?.entries.push(createSchemaEntry({
+                    ref,
+                    name,
+                    generateId,
+                    parentTag: { tag, id: tagId },
+                    parentId: documentId,
+                }));
+            });
+        }
+        // Add to untagged
+        else {
+            untagged.push(createSchemaEntry({
+                ref,
+                name,
+                generateId,
+                _schema: getResolvedRef(schemas[name]),
+                parentId: documentId,
+            }));
+        }
     }
-    const ref = `#/components/schemas/${name}`;
-    if (schema?.["x-tags"]) {
-      schema["x-tags"].forEach((tagName) => {
-        const { tag, id: tagId } = getTag({ tagsMap, name: tagName, documentId, generateId });
-        tagsMap.get(tagName)?.entries.push(
-          createSchemaEntry({
-            ref,
-            name,
-            generateId,
-            parentTag: { tag, id: tagId },
-            parentId: documentId
-          })
-        );
-      });
-    } else {
-      untagged.push(
-        createSchemaEntry({
-          ref,
-          name,
-          generateId,
-          _schema: getResolvedRef(schemas[name]),
-          parentId: documentId
-        })
-      );
-    }
-  }
-  return untagged;
-};
-export {
-  traverseSchemas
+    return untagged;
 };
-//# sourceMappingURL=traverse-schemas.js.map

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

@@ -1,137 +1,166 @@
-import { sortByOrder } from "@scalar/object-utils/arrays";
-import { unpackProxyObject } from "../../helpers/unpack-proxy.js";
-import { getXKeysFromObject } from "../../navigation/helpers/get-x-keys.js";
-import { getTag } from "./get-tag.js";
-const createTagEntry = ({
-  tag,
-  generateId,
-  children,
-  isGroup = false,
-  parentId
-}) => {
-  const id = generateId({
-    type: "tag",
-    tag,
-    parentId
-  });
-  const title = tag["x-displayName"] ?? tag.name ?? "Untitled Tag";
-  tag["x-scalar-order"] = children.map((child) => child.id);
-  const entry = {
-    id,
-    title,
-    name: tag.name || title,
-    description: tag.description,
-    children,
-    isGroup,
-    isWebhooks: false,
-    type: "tag",
-    xKeys: getXKeysFromObject(unpackProxyObject(tag))
-  };
-  return entry;
+import { sortByOrder } from '@scalar/object-utils/arrays';
+import { unpackProxyObject } from '../../helpers/unpack-proxy.js';
+import { getXKeysFromObject } from '../../navigation/helpers/get-x-keys.js';
+import { getTag } from './get-tag.js';
+/** Creates a traversed tag entry from an OpenAPI tag object.
+ *
+ * @param tag - The OpenAPI tag object
+ * @param entriesMap - Map to store tag IDs and titles for mobile header navigation
+ * @param getTagId - Function to generate unique IDs for tags
+ * @param children - Array of child entries (operations, webhooks, etc.)
+ * @param isGroup - Whether this tag represents a group of tags
+ * @returns A traversed tag entry with ID, title, name and children
+ */
+const createTagEntry = ({ tag, generateId, children, isGroup = false, parentId, }) => {
+    const id = generateId({
+        type: 'tag',
+        tag,
+        parentId,
+    });
+    const title = tag['x-displayName'] ?? tag.name ?? 'Untitled Tag';
+    // Update the order of the children based on the items
+    // This will ensure that the sort order is always in sync with the items
+    tag['x-scalar-order'] = children.map((child) => child.id);
+    const entry = {
+        id,
+        title,
+        name: tag.name || title,
+        description: tag.description,
+        children,
+        isGroup,
+        isWebhooks: false,
+        type: 'tag',
+        xKeys: getXKeysFromObject(unpackProxyObject(tag)),
+    };
+    return entry;
 };
-const getSortedTagEntries = ({
-  _keys,
-  tagsMap,
-  options: { tagsSorter, operationsSorter, generateId },
-  documentId,
-  sortOrder
-}) => {
-  const entries = _keys.flatMap((key) => {
-    const { tag, entries: entries2 } = getTag({ tagsMap, name: key, documentId, generateId });
-    if (tag["x-internal"] || tag["x-scalar-ignore"]) {
-      return [];
+/** Sorts and processes tags to create a hierarchical structure of tag entries.
+ *
+ * This function handles:
+ * - Sorting tags alphabetically or using a custom sort function
+ * - Sorting operations within tags by title, method, or custom function
+ * - Filtering out internal and ignored tags
+ * - Creating tag entries with their associated operations
+ *
+ * @param _keys - Array of tag keys to process
+ * @param tagsMap - Map of tags and their entries
+ * @param tagsDict - Dictionary of OpenAPI tags by name
+ * @param titlesMap - Map of titles for the mobile header
+ * @param options - Sorting and ID generation options
+ * @returns Array of processed and sorted tag entries
+ */
+/** Sorts tags and returns entries */
+const getSortedTagEntries = ({ _keys, tagsMap, options: { tagsSorter, operationsSorter, generateId }, documentId, sortOrder, }) => {
+    /**
+     * Process each tag and its entries:
+     * - Skip internal and ignored tags
+     * - Sort operations within tags
+     * - Create tag entries with sorted operations
+     */
+    const entries = _keys.flatMap((key) => {
+        const { tag, entries } = getTag({ tagsMap, name: key, documentId, generateId });
+        // Skip if the tag is internal or scalar-ignore
+        if (tag['x-internal'] || tag['x-scalar-ignore']) {
+            return [];
+        }
+        const sortOrder = tag['x-scalar-order'];
+        if (sortOrder === undefined) {
+            // Alpha sort
+            if (operationsSorter === 'alpha') {
+                entries.sort((a, b) => (a.type === 'operation' && b.type === 'operation' ? a.title.localeCompare(b.title) : 0));
+            }
+            // Method sort
+            else if (operationsSorter === 'method') {
+                entries.sort((a, b) => a.type === 'operation' && b.type === 'operation' ? a.method.localeCompare(b.method) : 0);
+            }
+            // Custom sort
+            else if (typeof operationsSorter === 'function') {
+                entries.sort((a, b) => {
+                    // Guard against tags
+                    if (!(a.type === 'operation' || a.type === 'webhook') || !(b.type === 'operation' || b.type === 'webhook')) {
+                        return 0;
+                    }
+                    // Handle webhooks as well as operations
+                    const pathA = a.type === 'operation' ? a.path : a.name;
+                    const pathB = b.type === 'operation' ? b.path : b.name;
+                    return operationsSorter({ method: a.method, path: pathA, ref: a.ref, httpVerb: a.method }, { method: b.method, path: pathB, ref: b.ref, httpVerb: b.method });
+                });
+            }
+        }
+        return createTagEntry({
+            tag,
+            generateId,
+            children: sortOrder ? sortByOrder(entries, sortOrder, 'id') : entries,
+            parentId: documentId,
+            isGroup: false,
+        });
+    });
+    // If a custom 'x-scalar-order' is specified in the tag, sort the entries by this order using sortByOrder
+    if (sortOrder) {
+        return sortByOrder(entries, sortOrder, 'id');
     }
-    const sortOrder2 = tag["x-scalar-order"];
-    if (sortOrder2 === void 0) {
-      if (operationsSorter === "alpha") {
-        entries2.sort((a, b) => a.type === "operation" && b.type === "operation" ? a.title.localeCompare(b.title) : 0);
-      } else if (operationsSorter === "method") {
-        entries2.sort(
-          (a, b) => a.type === "operation" && b.type === "operation" ? a.method.localeCompare(b.method) : 0
-        );
-      } else if (typeof operationsSorter === "function") {
-        entries2.sort((a, b) => {
-          if (!(a.type === "operation" || a.type === "webhook") || !(b.type === "operation" || b.type === "webhook")) {
-            return 0;
-          }
-          const pathA = a.type === "operation" ? a.path : a.name;
-          const pathB = b.type === "operation" ? b.path : b.name;
-          return operationsSorter(
-            { method: a.method, path: pathA, ref: a.ref, httpVerb: a.method },
-            { method: b.method, path: pathB, ref: b.ref, httpVerb: b.method }
-          );
+    // Alpha sort
+    if (tagsSorter === 'alpha') {
+        entries.sort((a, b) => {
+            const nameA = getTag({
+                tagsMap,
+                name: a.title,
+                documentId,
+                generateId,
+            }).tag['x-displayName'] ||
+                a.title ||
+                'Untitled Tag';
+            const nameB = getTag({ tagsMap, name: b.title, documentId, generateId }).tag['x-displayName'] || b.title || 'Untitled Tag';
+            return nameA.localeCompare(nameB);
         });
-      }
     }
-    return createTagEntry({
-      tag,
-      generateId,
-      children: sortOrder2 ? sortByOrder(entries2, sortOrder2, "id") : entries2,
-      parentId: documentId,
-      isGroup: false
-    });
-  });
-  if (sortOrder) {
-    return sortByOrder(entries, sortOrder, "id");
-  }
-  if (tagsSorter === "alpha") {
-    entries.sort((a, b) => {
-      const nameA = getTag({
-        tagsMap,
-        name: a.title,
-        documentId,
-        generateId
-      }).tag["x-displayName"] || a.title || "Untitled Tag";
-      const nameB = getTag({ tagsMap, name: b.title, documentId, generateId }).tag["x-displayName"] || b.title || "Untitled Tag";
-      return nameA.localeCompare(nameB);
-    });
-  } else if (typeof tagsSorter === "function") {
-    entries.sort(
-      (a, b) => tagsSorter(
-        getTag({ tagsMap, name: a.name, documentId, generateId }).tag,
-        getTag({ tagsMap, name: b.name, documentId, generateId }).tag
-      )
-    );
-  }
-  return entries;
+    // Custom sort
+    else if (typeof tagsSorter === 'function') {
+        entries.sort((a, b) => tagsSorter(getTag({ tagsMap, name: a.name, documentId, generateId }).tag, getTag({ tagsMap, name: b.name, documentId, generateId }).tag));
+    }
+    return entries;
 };
-const traverseTags = ({
-  document,
-  tagsMap,
-  documentId,
-  options: { generateId, tagsSorter, operationsSorter }
-}) => {
-  if (document["x-tagGroups"]) {
-    const tagGroups = document["x-tagGroups"];
-    return tagGroups.flatMap((tagGroup) => {
-      const entries = getSortedTagEntries({
-        _keys: tagGroup.tags,
+/**
+ * Traverses the tags map to create navigation entries, handling both grouped and ungrouped tags.
+ *
+ * This function processes the OpenAPI document's tags to:
+ * - Handle tag groups if specified via x-tagGroups
+ * - Sort tags and their operations according to provided sorters
+ * - Create navigation entries for each tag or tag group
+ */
+export const traverseTags = ({ document, tagsMap, documentId, options: { generateId, tagsSorter, operationsSorter }, }) => {
+    // x-tagGroups
+    if (document['x-tagGroups']) {
+        const tagGroups = document['x-tagGroups'];
+        return tagGroups.flatMap((tagGroup) => {
+            const entries = getSortedTagEntries({
+                _keys: tagGroup.tags,
+                tagsMap,
+                options: { tagsSorter, operationsSorter, generateId },
+                documentId: documentId,
+                sortOrder: tagGroup['x-scalar-order'],
+            });
+            // Try to update the sort order of the tag group to keep it in sync with the items
+            tagGroup['x-scalar-order'] = entries.map((entry) => entry.id);
+            return entries.length
+                ? createTagEntry({
+                    tag: tagGroup,
+                    generateId,
+                    children: entries,
+                    parentId: documentId,
+                    isGroup: true,
+                })
+                : [];
+        });
+    }
+    // Ungrouped regular tags
+    const keys = Array.from(tagsMap.keys());
+    const tags = getSortedTagEntries({
+        _keys: keys,
         tagsMap,
-        options: { tagsSorter, operationsSorter, generateId },
-        documentId,
-        sortOrder: tagGroup["x-scalar-order"]
-      });
-      tagGroup["x-scalar-order"] = entries.map((entry) => entry.id);
-      return entries.length ? createTagEntry({
-        tag: tagGroup,
-        generateId,
-        children: entries,
-        parentId: documentId,
-        isGroup: true
-      }) : [];
+        options: { generateId, tagsSorter, operationsSorter },
+        documentId: documentId,
+        sortOrder: document['x-scalar-order'],
     });
-  }
-  const keys = Array.from(tagsMap.keys());
-  const tags = getSortedTagEntries({
-    _keys: keys,
-    tagsMap,
-    options: { generateId, tagsSorter, operationsSorter },
-    documentId,
-    sortOrder: document["x-scalar-order"]
-  });
-  return tags;
-};
-export {
-  traverseTags
+    return tags;
 };
-//# sourceMappingURL=traverse-tags.js.map