@scalar/openapi-to-markdown 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @scalar/openapi-to-markdown
 
+## 1.5.1
+
+### Patch Changes
+
+- [#10457](https://github.com/scalar/scalar/pull/10457): Render a selected operation, model, tag or webhook in time proportional to the selection instead of the whole document.
+
 ## 1.5.0
 
 ### Minor Changes

package/dist/create-markdown-from-openapi.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAkB,MAAM,mBAAmB,CAAA;AAE7E,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAOvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA"}
+{"version":3,"file":"create-markdown-from-openapi.d.ts","sourceRoot":"","sources":["../src/create-markdown-from-openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8DAA8D,CAAA;AAInG,OAAO,EAAE,KAAK,oBAAoB,EAAwC,MAAM,mBAAmB,CAAA;AAEnG,KAAK,WAAW,GAAG,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAA;AACrE,0FAA0F;AAC1F,MAAM,MAAM,uBAAuB,GAAG;IACpC,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5D,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GAAU,OAAO,WAAW,KAAG,OAAO,CAAC,uBAAuB,CAQvG,CAAA;AAED,qFAAqF;AACrF,eAAO,MAAM,yBAAyB,GACpC,OAAO,WAAW,EAClB,UAAU,oBAAoB,KAC7B,OAAO,CAAC,MAAM,CAGhB,CAAA"}

package/dist/create-markdown-from-openapi.js

@@ -1,6 +1,6 @@
 import { loadDocument } from './load-document.js';
 import { createDocumentRenderer } from './render-document.js';
-import { selectDocument } from './select-document.js';
+import { createDocumentLookup, selectDocument } from './select-document.js';
 /**
  * Load and resolve an API description once, then render any number of selections.
  * Each renderer owns its document; create a new renderer to pick up source changes.
@@ -8,7 +8,8 @@ import { selectDocument } from './select-document.js';
 export const createOpenApiMarkdownRenderer = async (input) => {
     const content = await loadDocument(input);
     const renderDocument = createDocumentRenderer();
-    const render = async (options) => await renderDocument(selectDocument(content, options), options);
+    const lookup = createDocumentLookup(content);
+    const render = async (options) => await renderDocument(selectDocument(content, options, lookup), options);
     return { render };
 };
 /** Generate Markdown from an API description, optionally scoped to a single page. */

package/dist/select-document.d.ts

@@ -1,5 +1,5 @@
 import type { OperationMethod } from '@scalar/workspace-store/schemas/navigation';
-import type { OpenApiDocument } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
+import type { OpenApiDocument, PathItemObject } from '@scalar/workspace-store/schemas/v3.2/strict/openapi-document';
 /** Identify one operation by path and method, operation ID, or JSON pointer. */
 export type OperationSelector = {
     path: string;
@@ -40,7 +40,33 @@ type PageSelectors = {
     };
     introduction: true;
 };
-/** Scope after resolving references and migrating older documents. */
-export declare const selectDocument: (document: OpenApiDocument, options?: OpenApiRenderOptions) => OpenApiDocument;
+type OperationMatch = {
+    path: string;
+    method: OperationMethod;
+};
+type TaggedPathItem = {
+    path: string;
+    pathItem: PathItemObject;
+    methods: string[];
+};
+/**
+ * Lookups that every selection from one document shares, built on first use.
+ * The document must not change while its lookup is in use.
+ */
+type DocumentLookup = {
+    /** Operations by operation ID, in document order. */
+    operationsById: () => ReadonlyMap<string, OperationMatch[]>;
+    /** Path items with the methods that carry each tag, in document order. */
+    operationsByTag: () => ReadonlyMap<string, TaggedPathItem[]>;
+    /** The position of each schema in `components.schemas`. */
+    schemaPositions: () => ReadonlyMap<string, number>;
+};
+/** Index a document once so that each selection costs time in proportion to what it selects. */
+export declare const createDocumentLookup: (document: OpenApiDocument) => DocumentLookup;
+/**
+ * Scope after resolving references and migrating older documents.
+ * Pass the same lookup to every selection from one document to reuse its indexes.
+ */
+export declare const selectDocument: (document: OpenApiDocument, options?: OpenApiRenderOptions, lookup?: DocumentLookup) => OpenApiDocument;
 export {};
 //# sourceMappingURL=select-document.d.ts.map

package/dist/select-document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GACvD,CACI;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GACrF,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CAC3B,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAA;AAEH,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4GAA4G;IAC5G,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAA;QACd,oFAAoF;QACpF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,GAAG,SAAS,CAAA;QAC7E;;;WAGG;QACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AAyKD,sEAAsE;AACtE,eAAO,MAAM,cAAc,GAAI,UAAU,eAAe,EAAE,UAAS,oBAAyB,KAAG,eA4N9F,CAAA"}
+{"version":3,"file":"select-document.d.ts","sourceRoot":"","sources":["../src/select-document.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAA;AAEnH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;CACxB,GACD;IACE,WAAW,EAAE,MAAM,CAAA;CACpB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AACL,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,sBAAsB,GACvD,CACI;KACG,GAAG,IAAI,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GACrF,IAAI,CAAC,aAAa,EAAE,GAAG,CAAC;CAC3B,CAAC,MAAM,aAAa,CAAC,GACtB,OAAO,CAAC,MAAM,CAAC,MAAM,aAAa,EAAE,KAAK,CAAC,CAAC,CAC9C,CAAA;AAEH,mFAAmF;AACnF,MAAM,MAAM,sBAAsB,GAAG;IACnC,4GAA4G;IAC5G,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,QAAQ,CAAA;QACd,oFAAoF;QACpF,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,KAAK,MAAM,GAAG,SAAS,CAAA;QAC7E;;;WAGG;QACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAC3B,CAAA;CACF,CAAA;AAED,KAAK,aAAa,GAAG;IACnB,SAAS,EAAE,iBAAiB,CAAA;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,eAAe,CAAA;KAAE,CAAA;IAClD,YAAY,EAAE,IAAI,CAAA;CACnB,CAAA;AACD,KAAK,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAA;AA+G/D,KAAK,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEnF;;;GAGG;AACH,KAAK,cAAc,GAAG;IACpB,qDAAqD;IACrD,cAAc,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;IAC3D,0EAA0E;IAC1E,eAAe,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;IAC5D,2DAA2D;IAC3D,eAAe,EAAE,MAAM,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACnD,CAAA;AA8BD,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,GAAI,UAAU,eAAe,KAAG,cAWhE,CAAA;AAwDD;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,eAAe,EACzB,UAAS,oBAAyB,EAClC,SAAQ,cAA+C,KACtD,eA2NF,CAAA"}

package/dist/select-document.js

@@ -78,16 +78,43 @@ const findOperationByPathAndMethod = (document, selector) => {
         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) => {
+const indexOperations = (document) => {
+    const byId = new Map();
+    const byTag = new Map();
+    for (const [path, pathItem] of getPathEntries(document)) {
+        forEachPathItemOperation(pathItem, (method, operationRef) => {
+            const operation = getResolvedRef(operationRef);
+            if (typeof operation?.operationId === 'string') {
+                const matches = byId.get(operation.operationId) ?? [];
+                matches.push({ path, method });
+                byId.set(operation.operationId, matches);
+            }
+            for (const tag of new Set(operation?.tags)) {
+                const entries = byTag.get(tag) ?? [];
+                const last = entries.at(-1);
+                if (last?.path === path) {
+                    last.methods.push(method);
+                }
+                else {
+                    entries.push({ path, pathItem, methods: [method] });
+                }
+                byTag.set(tag, entries);
+            }
+        });
+    }
+    return { byId, byTag };
+};
+/** Index a document once so that each selection costs time in proportion to what it selects. */
+export const createDocumentLookup = (document) => {
+    let operations;
+    let schemaPositions;
+    return {
+        operationsById: () => (operations ??= indexOperations(document)).byId,
+        operationsByTag: () => (operations ??= indexOperations(document)).byTag,
+        schemaPositions: () => (schemaPositions ??= new Map(Object.keys(document.components?.schemas ?? {}).map((name, position) => [name, position]))),
+    };
+};
+const resolveOperationMatch = (document, selector, lookup) => {
     if ('pointer' in selector) {
         const match = getOperationSelectorFromPointer(selector.pointer);
         if (!getPathItemOperation(document.paths?.[match.path], match.method)) {
@@ -96,7 +123,7 @@ const resolveOperationMatch = (document, selector) => {
         return match;
     }
     if ('operationId' in selector) {
-        const matches = findOperationsByOperationId(document, selector.operationId);
+        const matches = lookup.operationsById().get(selector.operationId) ?? [];
         if (!matches.length) {
             throw new Error(`Operation with operationId "${selector.operationId}" was not found`);
         }
@@ -108,9 +135,9 @@ const resolveOperationMatch = (document, selector) => {
     }
     return findOperationByPathAndMethod(document, selector);
 };
-const filterDocumentByOperation = (document, selector) => {
-    const match = resolveOperationMatch(document, selector);
-    const pathItem = getPathEntries(document).find(([path]) => path === match.path)?.[1];
+const filterDocumentByOperation = (document, selector, lookup) => {
+    const match = resolveOperationMatch(document, selector, lookup);
+    const pathItem = getResolvedPathItem(document.paths?.[match.path]);
     if (!pathItem) {
         throw new Error(`Operation not found for path "${match.path}" and method "${match.method.toUpperCase()}"`);
     }
@@ -121,8 +148,11 @@ const filterDocumentByOperation = (document, selector) => {
         },
     };
 };
-/** Scope after resolving references and migrating older documents. */
-export const selectDocument = (document, options = {}) => {
+/**
+ * Scope after resolving references and migrating older documents.
+ * Pass the same lookup to every selection from one document to reuse its indexes.
+ */
+export const selectDocument = (document, options = {}, lookup = createDocumentLookup(document)) => {
     if (!isObject(options)) {
         throw new Error('Render options must be an object');
     }
@@ -159,7 +189,7 @@ export const selectDocument = (document, options = {}) => {
     const selected = { ...document, paths: {}, webhooks: {}, tags: [] };
     const modelRoots = [];
     if (options.operation) {
-        selected.paths = filterDocumentByOperation(document, options.operation).paths;
+        selected.paths = filterDocumentByOperation(document, options.operation, lookup).paths;
     }
     if (options.tag !== undefined) {
         const metadata = document.tags?.filter((tag) => tag.name === options.tag) ?? [];
@@ -167,16 +197,8 @@ export const selectDocument = (document, options = {}) => {
             throw new Error(`Multiple tags found for "${options.tag}"`);
         }
         selected.tags = metadata.length ? metadata : [{ name: options.tag }];
-        for (const [path, item] of getPathEntries(document)) {
-            const methods = [];
-            forEachPathItemOperation(item, (method, operation) => {
-                if (getResolvedRef(operation)?.tags?.includes(options.tag)) {
-                    methods.push(method);
-                }
-            });
-            if (methods.length) {
-                selected.paths[path] = filterPathItemOperations(item, methods);
-            }
+        for (const { path, pathItem, methods } of lookup.operationsByTag().get(options.tag) ?? []) {
+            selected.paths[path] = filterPathItemOperations(pathItem, methods);
         }
         if (!metadata.length && !Object.keys(selected.paths ?? {}).length) {
             throw new Error(`Tag "${options.tag}" was not found`);
@@ -327,9 +349,14 @@ export const selectDocument = (document, options = {}) => {
             visit(root);
         }
     }
+    const positions = lookup.schemaPositions();
     selected.components = {
         ...document.components,
-        schemas: Object.fromEntries(Object.entries(schemas).filter(([name]) => needed.has(name))),
+        // Keep the document's schema order, which decides the order of the page's model sections.
+        schemas: Object.fromEntries([...needed]
+            .filter((name) => positions.has(name))
+            .sort((a, b) => positions.get(a) - positions.get(b))
+            .map((name) => [name, schemas[name]])),
         securitySchemes: Object.fromEntries(Object.entries(document.components?.securitySchemes ?? {}).filter(([name]) => securityNames.has(name))),
     };
     return selected;

package/package.json

@@ -16,7 +16,7 @@
     "llm",
     "swagger"
   ],
-  "version": "1.5.0",
+  "version": "1.5.1",
   "engines": {
     "node": ">=22"
   },
@@ -40,11 +40,11 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@scalar/code-highlight": "0.4.7",
+    "@scalar/code-highlight": "0.4.8",
     "@scalar/helpers": "0.16.0",
-    "@scalar/json-magic": "0.15.3",
+    "@scalar/json-magic": "0.15.4",
     "@scalar/openapi-upgrader": "0.4.1",
-    "@scalar/workspace-store": "0.67.2",
+    "@scalar/workspace-store": "0.68.0",
     "rehype-parse": "^9.0.1",
     "rehype-remark": "^10.0.1",
     "rehype-sanitize": "^6.0.0",
@@ -54,7 +54,7 @@
     "unified": "^11.0.5"
   },
   "devDependencies": {
-    "@scalar/components": "0.30.5",
+    "@scalar/components": "0.30.6",
     "@scalar/galaxy": "0.7.1",
     "@scalar/themes": "0.18.1",
     "@tailwindcss/vite": "^4.3.3",