@scalar/openapi-to-markdown 1.1.0 → 1.3.0

package/dist/select-document.js

@@ -1,6 +1,6 @@
 import { HTTP_METHODS } from '@scalar/helpers/http/http-methods';
 import { isObject } from '@scalar/helpers/object/is-object';
-import { getPathItemOperation, getResolvedPathItem } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
+import { forEachPathItemOperation, getPathItemOperation, getResolvedPathItem, setPathItemOperation, } from '@scalar/workspace-store/helpers/for-each-path-item-operation';
 import { getResolvedRef } from '@scalar/workspace-store/helpers/get-resolved-ref';
 const HTTP_METHOD_SET = new Set(HTTP_METHODS);
 const normalizeHttpMethod = (method) => {
@@ -28,17 +28,18 @@ const parseJsonPointer = (pointer) => normalizeJsonPointer(pointer)
     .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
 const getOperationSelectorFromPointer = (pointer) => {
     const segments = parseJsonPointer(pointer);
-    if (segments.length !== 3 || segments[0] !== 'paths') {
+    if (segments[0] !== 'paths' ||
+        !(segments.length === 3 || (segments.length === 4 && segments[2] === 'additionalOperations'))) {
         throw new Error(`JSON pointer "${pointer}" must target an operation object under "/paths/{path}/{method}"`);
     }
     const path = segments[1];
-    const method = segments[2];
-    if (!path || !method) {
+    const method = segments.length === 4 ? segments[3] : segments[2];
+    if (!path || !method || (segments.length === 3 ? !HTTP_METHOD_SET.has(method) : HTTP_METHOD_SET.has(method))) {
         throw new Error(`JSON pointer "${pointer}" must target an operation object under "/paths/{path}/{method}"`);
     }
     return {
         path,
-        method: method,
+        method,
     };
 };
 const getPathEntries = (document) => {
@@ -51,12 +52,20 @@ const getPathEntries = (document) => {
         return pathItem ? [[path, pathItem]] : [];
     });
 };
-const filterPathItemToSingleOperation = (pathItem, selectedMethod) => Object.fromEntries(Object.entries(pathItem).filter(([key]) => {
-    const method = normalizeHttpMethod(key);
-    return !method || method === selectedMethod;
-}));
+/** Keep path metadata while excluding every unselected fixed or additional operation. */
+const filterPathItemOperations = (pathItem, methods) => {
+    const selected = Object.fromEntries(Object.entries(pathItem).filter(([key]) => !HTTP_METHOD_SET.has(key) && key !== 'additionalOperations'));
+    forEachPathItemOperation(pathItem, (method, operation) => {
+        if (methods.includes(method)) {
+            setPathItemOperation(selected, method, operation);
+        }
+    });
+    return selected;
+};
+/** Exact authored methods take precedence over the legacy uppercase fixed-method aliases. */
+const resolveMethod = (pathItem, method) => getPathItemOperation(pathItem, method) ? method : normalizeHttpMethod(method);
 const findOperationByPathAndMethod = (document, selector) => {
-    const method = normalizeHttpMethod(selector.method);
+    const method = resolveMethod(getResolvedPathItem(document.paths?.[selector.path]), selector.method);
     if (!method) {
         throw new Error(`Invalid HTTP method "${selector.method}". Supported methods: ${HTTP_METHODS.join(', ')}`);
     }
@@ -69,20 +78,22 @@ const findOperationByPathAndMethod = (document, selector) => {
         method,
     };
 };
-const findOperationsByOperationId = (document, operationId) => getPathEntries(document).flatMap(([path, pathItem]) => Object.entries(pathItem).flatMap(([methodKey, operation]) => {
-    const method = normalizeHttpMethod(methodKey);
-    if (!method || !isObject(operation)) {
-        return [];
-    }
-    const candidateOperationId = 'operationId' in operation && typeof operation.operationId === 'string' ? operation.operationId : undefined;
-    if (candidateOperationId !== operationId) {
-        return [];
-    }
-    return [{ path, method }];
-}));
+const findOperationsByOperationId = (document, operationId) => getPathEntries(document).flatMap(([path, pathItem]) => {
+    const matches = [];
+    forEachPathItemOperation(pathItem, (method, operation) => {
+        if (getResolvedRef(operation)?.operationId === operationId) {
+            matches.push({ path, method });
+        }
+    });
+    return matches;
+});
 const resolveOperationMatch = (document, selector) => {
     if ('pointer' in selector) {
-        return findOperationByPathAndMethod(document, getOperationSelectorFromPointer(selector.pointer));
+        const match = getOperationSelectorFromPointer(selector.pointer);
+        if (!getPathItemOperation(document.paths?.[match.path], match.method)) {
+            throw new Error(`Operation not found at JSON pointer "${selector.pointer}"`);
+        }
+        return match;
     }
     if ('operationId' in selector) {
         const matches = findOperationsByOperationId(document, selector.operationId);
@@ -106,7 +117,7 @@ const filterDocumentByOperation = (document, selector) => {
     return {
         ...document,
         paths: {
-            [match.path]: filterPathItemToSingleOperation(pathItem, match.method),
+            [match.path]: filterPathItemOperations(pathItem, [match.method]),
         },
     };
 };
@@ -157,9 +168,14 @@ export const selectDocument = (document, options = {}) => {
         }
         selected.tags = metadata.length ? metadata : [{ name: options.tag }];
         for (const [path, item] of getPathEntries(document)) {
-            const methods = HTTP_METHODS.filter((method) => getPathItemOperation(item, method)?.tags?.includes(options.tag));
+            const methods = [];
+            forEachPathItemOperation(item, (method, operation) => {
+                if (getResolvedRef(operation)?.tags?.includes(options.tag)) {
+                    methods.push(method);
+                }
+            });
             if (methods.length) {
-                selected.paths[path] = Object.fromEntries(Object.entries(item).filter(([key]) => !HTTP_METHOD_SET.has(key) || methods.includes(key)));
+                selected.paths[path] = filterPathItemOperations(item, methods);
             }
         }
         if (!metadata.length && !Object.keys(selected.paths ?? {}).length) {
@@ -182,26 +198,31 @@ export const selectDocument = (document, options = {}) => {
             Object.keys(selector).length !== 2) {
             throw new Error('Invalid webhook selector. Use { name, method }');
         }
-        const method = normalizeHttpMethod(selector.method);
+        const item = getResolvedPathItem(document.webhooks?.[selector.name]);
+        const method = resolveMethod(item, selector.method);
         if (!method) {
             throw new Error(`Invalid HTTP method "${selector.method}"`);
         }
-        const item = getResolvedPathItem(document.webhooks?.[selector.name]);
         if (!item || !getPathItemOperation(item, method)) {
             throw new Error(`Webhook "${selector.name}" with method "${method.toUpperCase()}" was not found`);
         }
-        selected.webhooks = { [selector.name]: filterPathItemToSingleOperation(item, method) };
+        selected.webhooks = { [selector.name]: filterPathItemOperations(item, [method]) };
     }
     const securityNames = new Set();
     const tagNames = new Set();
     for (const items of [selected.paths, selected.webhooks]) {
         for (const [path, itemRef] of Object.entries(items ?? {})) {
             const item = getResolvedPathItem(itemRef);
-            const scoped = { ...item, parameters: undefined, servers: undefined };
-            for (const method of HTTP_METHODS) {
-                const operation = getPathItemOperation(item, method);
+            const scoped = {
+                ...item,
+                additionalOperations: item.additionalOperations ? { ...item.additionalOperations } : undefined,
+                parameters: undefined,
+                servers: undefined,
+            };
+            forEachPathItemOperation(item, (method, operationRef) => {
+                const operation = getResolvedRef(operationRef);
                 if (!operation) {
-                    continue;
+                    return;
                 }
                 const parameters = new Map();
                 for (const ref of [...(item.parameters ?? []), ...(operation.parameters ?? [])]) {
@@ -219,14 +240,14 @@ export const selectDocument = (document, options = {}) => {
                 for (const name of operation.tags ?? []) {
                     tagNames.add(name);
                 }
-                scoped[method] = {
+                setPathItemOperation(scoped, method, {
                     ...operation,
                     parameters: [...parameters.values()],
                     servers: operation.servers ?? item.servers ?? document.servers,
                     security,
                     tags: options.tag !== undefined ? [options.tag] : operation.tags,
-                };
-            }
+                });
+            });
             items[path] = scoped;
         }
     }

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.1.0",
+  "version": "1.3.0",
   "engines": {
     "node": ">=22"
   },
@@ -41,10 +41,10 @@
   ],
   "dependencies": {
     "@scalar/code-highlight": "0.4.7",
-    "@scalar/helpers": "0.13.0",
-    "@scalar/json-magic": "0.15.0",
-    "@scalar/openapi-upgrader": "0.3.0",
-    "@scalar/workspace-store": "0.65.0",
+    "@scalar/helpers": "0.15.0",
+    "@scalar/json-magic": "0.15.2",
+    "@scalar/openapi-upgrader": "0.4.0",
+    "@scalar/workspace-store": "0.67.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",