@kubb/adapter-oas 5.0.0-beta.11 → 5.0.0-beta.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.11",
+  "version": "5.0.0-beta.13",
   "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
@@ -47,7 +47,7 @@
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.11"
+    "@kubb/core": "5.0.0-beta.13"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
@@ -68,6 +68,7 @@
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",
+    "bench": "vitest bench",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"
   }

package/src/adapter.bench.ts

@@ -0,0 +1,35 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { bench, describe } from 'vitest'
+import { parseDocument } from './factory.ts'
+import { parseOas } from './parser.ts'
+import type { Document } from './types.ts'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// TODO: replace with stripe.json once the parser handles its circular-reference
+// expansion without exhausting heap (the full Stripe spec triggers exponential
+// sub-tree duplication because resolvingRefs only prevents recursion within a
+// single resolution chain, not repeated resolution of the same schema).
+const petStorePath = path.resolve(__dirname, '../mocks/petStore.yaml')
+
+let document: Document | undefined
+
+async function getDocument(): Promise<Document> {
+  if (!document) {
+    document = await parseDocument(petStorePath)
+  }
+  return document
+}
+
+describe('parseOas() performance', () => {
+  bench(
+    'petStore spec',
+    async () => {
+      const doc = await getDocument()
+      parseOas(doc)
+    },
+    { iterations: 5, warmupIterations: 1 },
+  )
+})

package/src/adapter.ts

@@ -44,10 +44,8 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
   } = options
 
-  // Let-binding so parse() can replace it with a simple reassignment (no clear+loop).
   let nameMapping = new Map<string, string>()
   let parsedDocument: Document | null
-  let inputNode: ast.InputNode | null
 
   return {
     name: adapterOasName,
@@ -69,9 +67,6 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     get document() {
       return parsedDocument
     },
-    get inputNode() {
-      return inputNode
-    },
     async validate(input, options) {
       const document = await parseDocument(input)
       await validateDocument(document, options)
@@ -114,7 +109,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
       // Expose the raw document so consumers (e.g. plugin-redoc) can access it.
       parsedDocument = document
 
-      inputNode = ast.createInput({
+      const inputNode = ast.createInput({
         ...node,
         meta: {
           title: document.info?.title,

package/src/parser.ts

@@ -89,6 +89,20 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   const resolvingRefs = new Set<string>()
 
+  /**
+   * Cache of already-resolved `$ref` schemas within this parser instance.
+   *
+   * Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
+   * every time it appears as a `$ref` in a different parent schema. In heavily
+   * cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
+   * blowup — `customer` alone may be referenced from dozens of top-level schemas,
+   * each triggering a fresh recursive expansion of its entire sub-tree.
+   *
+   * Memoising by `$ref` path reduces the overall work from O(2^depth) to O(N)
+   * where N is the number of unique schema names.
+   */
+  const resolvedRefCache = new Map<string, ast.SchemaNode | undefined>()
+
   /**
    * Converts a `$ref` schema into a `RefSchemaNode`.
    *
@@ -101,15 +115,20 @@ function createSchemaParser(ctx: OasParserContext) {
     let resolvedSchema: ast.SchemaNode | undefined
     const refPath = schema.$ref
     if (refPath && !resolvingRefs.has(refPath)) {
-      try {
-        const referenced = resolveRef<SchemaObject>(document, refPath)
-        if (referenced) {
-          resolvingRefs.add(refPath)
-          resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
-          resolvingRefs.delete(refPath)
+      if (resolvedRefCache.has(refPath)) {
+        resolvedSchema = resolvedRefCache.get(refPath)
+      } else {
+        try {
+          const referenced = resolveRef<SchemaObject>(document, refPath)
+          if (referenced) {
+            resolvingRefs.add(refPath)
+            resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
+            resolvingRefs.delete(refPath)
+          }
+        } catch {
+          // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
         }
-      } catch {
-        // Ref cannot be resolved in this document (e.g. unit tests with minimal documents).
+        resolvedRefCache.set(refPath, resolvedSchema)
       }
     }