@kubb/adapter-oas 5.0.0-beta.14 → 5.0.0-beta.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.14",
+  "version": "5.0.0-beta.16",
   "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",
@@ -43,11 +43,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.5",
+    "@redocly/openapi-core": "^2.30.6",
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.14"
+    "@kubb/core": "5.0.0-beta.16"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.bench.ts

@@ -1,35 +1,65 @@
 import path from 'node:path'
+import { existsSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { bench, describe } from 'vitest'
+import { adapterOas } from './adapter.ts'
 import { parseDocument } from './factory.ts'
 import { parseOas } from './parser.ts'
 import type { Document } from './types.ts'
+import type { AdapterSource } from '@kubb/core'
 
 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')
+const stripeSpecPath = '/tmp/kubb-stripe-spec3.json'
+const hasStripe = existsSync(stripeSpecPath)
 
-let document: Document | undefined
+let petStoreDoc: Document | undefined
 
-async function getDocument(): Promise<Document> {
-  if (!document) {
-    document = await parseDocument(petStorePath)
+async function getPetStoreDocument(): Promise<Document> {
+  if (!petStoreDoc) {
+    petStoreDoc = await parseDocument(petStorePath)
   }
-  return document
+  return petStoreDoc
 }
 
 describe('parseOas() performance', () => {
   bench(
     'petStore spec',
     async () => {
-      const doc = await getDocument()
+      const doc = await getPetStoreDocument()
       parseOas(doc)
     },
     { iterations: 5, warmupIterations: 1 },
   )
 })
+
+describe.skipIf(!hasStripe)('Stripe spec — batch vs streaming (1,385 schemas)', () => {
+  const stripeSource: AdapterSource = { type: 'path', path: stripeSpecPath }
+
+  bench(
+    'batch — adapter.parse()',
+    async () => {
+      const adapter = adapterOas({ validate: false })
+      await adapter.parse(stripeSource)
+    },
+    { iterations: 3, warmupIterations: 1 },
+  )
+
+  bench(
+    'streaming — adapter.count() + stream() drain',
+    async () => {
+      const adapter = adapterOas({ validate: false })
+      await adapter.count!(stripeSource)
+      const stream = await adapter.stream!(stripeSource)
+      for await (const _ of stream.schemas) {
+        /* drain */
+      }
+      for await (const _ of stream.operations) {
+        /* drain */
+      }
+    },
+    { iterations: 3, warmupIterations: 1 },
+  )
+})

package/src/adapter.ts

@@ -1,9 +1,11 @@
 import { ast, createAdapter } from '@kubb/core'
+import type { AdapterSource } from '@kubb/core'
+import BaseOas from 'oas'
 import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
-import { applyDiscriminatorInheritance } from './discriminator.ts'
+import { applyDiscriminatorInheritance, buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
 import { parseDocument, parseFromConfig, validateDocument } from './factory.ts'
-import { parseOas } from './parser.ts'
-import { resolveServerUrl } from './resolvers.ts'
+import { createSchemaParser, parseOas } from './parser.ts'
+import { getSchemas, resolveServerUrl } from './resolvers.ts'
 import type { AdapterOas, Document } from './types.ts'
 
 /**
@@ -44,8 +46,40 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
   } = options
 
+  const parserOptions: ast.ParserOptions = {
+    ...DEFAULT_PARSER_OPTIONS,
+    dateType,
+    integerType,
+    unknownType,
+    emptySchemaType,
+    enumSuffix,
+  }
+
   let nameMapping = new Map<string, string>()
-  let parsedDocument: Document | null
+  let parsedDocument: Document | null = null
+  let schemaObjects: ReturnType<typeof getSchemas>['schemas'] | null = null
+
+  function resolveBaseURL(document: Document): string | undefined {
+    const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
+    return server?.url ? resolveServerUrl(server, serverVariables) : undefined
+  }
+
+  async function ensureDocument(source: AdapterSource): Promise<Document> {
+    if (parsedDocument) return parsedDocument
+    const fresh = await parseFromConfig(source)
+    if (validate) await validateDocument(fresh)
+    parsedDocument = fresh
+    return fresh
+  }
+
+  async function ensureSchemas(document: Document): Promise<ReturnType<typeof getSchemas>['schemas']> {
+    if (!schemaObjects) {
+      const result = getSchemas(document, { contentType })
+      schemaObjects = result.schemas
+      nameMapping = result.nameMapping
+    }
+    return schemaObjects
+  }
 
   return {
     name: adapterOasName,
@@ -84,14 +118,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
       })
     },
     async parse(source) {
-      const document = await parseFromConfig(source)
-
-      if (validate) {
-        await validateDocument(document)
-      }
-
-      const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
-      const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
+      const document = await ensureDocument(source)
 
       const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
         contentType,
@@ -106,20 +133,84 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
 
       // This must happen after parseOas() because legacy enum remapping is finalized there.
       nameMapping = parsedNameMapping
-      // Expose the raw document so consumers (e.g. plugin-redoc) can access it.
-      parsedDocument = document
 
-      const inputNode = ast.createInput({
+      return ast.createInput({
         ...node,
         meta: {
           title: document.info?.title,
           description: document.info?.description,
           version: document.info?.version,
-          baseURL,
+          baseURL: resolveBaseURL(document),
         },
       })
+    },
+    async count(source) {
+      const document = await ensureDocument(source)
+      const schemas = await ensureSchemas(document)
+
+      const baseOas = new BaseOas(document)
+      const operationCount = Object.values(baseOas.getPaths()).flatMap(Object.values).filter(Boolean).length
 
-      return inputNode
+      return { schemas: Object.keys(schemas).length, operations: operationCount }
+    },
+    async stream(source) {
+      const document = await ensureDocument(source)
+      const schemas = await ensureSchemas(document)
+
+      let discriminatorChildMap: Awaited<ReturnType<typeof buildDiscriminatorChildMap>> | null = null
+      if (discriminator === 'inherit') {
+        const { parseSchema: _preParser } = createSchemaParser({ document, contentType })
+        const parentNodes: ast.SchemaNode[] = []
+        for (const [name, schema] of Object.entries(schemas)) {
+          if ((schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) {
+            parentNodes.push(_preParser({ schema, name }, parserOptions))
+          }
+        }
+        if (parentNodes.length > 0) {
+          discriminatorChildMap = buildDiscriminatorChildMap(parentNodes)
+        }
+      }
+
+      // Each [Symbol.asyncIterator]() call returns a fresh generator so multiple
+      // plugins can do independent `for await` passes without shared state.
+      const schemasIterable: AsyncIterable<ast.SchemaNode> = {
+        [Symbol.asyncIterator]() {
+          return (async function* () {
+            const { parseSchema: _parseSchema } = createSchemaParser({ document, contentType })
+            for (const [name, schema] of Object.entries(schemas)) {
+              let node = _parseSchema({ schema, name }, parserOptions)
+              const entry = discriminatorChildMap?.get(name)
+              if (entry) node = patchDiscriminatorNode(node, entry)
+              yield node
+            }
+          })()
+        },
+      }
+
+      const operationsIterable: AsyncIterable<ast.OperationNode> = {
+        [Symbol.asyncIterator]() {
+          return (async function* () {
+            const { parseOperation: _parseOperation } = createSchemaParser({ document, contentType })
+            const baseOas = new BaseOas(document)
+            const paths = baseOas.getPaths()
+
+            for (const methods of Object.values(paths)) {
+              for (const operation of Object.values(methods)) {
+                if (!operation) continue
+                const node = _parseOperation(parserOptions, operation)
+                if (node) yield node
+              }
+            }
+          })()
+        },
+      }
+
+      return ast.createStreamInput(schemasIterable, operationsIterable, {
+        title: document.info?.title,
+        description: document.info?.description,
+        version: document.info?.version,
+        baseURL: resolveBaseURL(document),
+      })
     },
   }
 })

package/src/discriminator.ts

@@ -6,24 +6,17 @@ type DiscriminatorTarget = {
 }
 
 /**
- * Injects discriminator enum values into child schemas so they know which value identifies them.
- *
- * Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
- * enum value each union member is mapped to, then adds (or replaces) that property on the matching
- * child object schema.
+ * Builds a map of child schema names → discriminator patch data by scanning the given
+ * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
  *
- * Returns a new `InputNode` — the original is never mutated.
- *
- * @example
- * ```ts
- * const { root } = parseOas(document, options)
- * const next = applyDiscriminatorInheritance(root)
- * ```
+ * Extracted from `applyDiscriminatorInheritance` so the streaming path can call it on a
+ * small pre-parsed subset of schemas (only the discriminator parents) rather than on all
+ * schemas at once.
  */
-export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNode {
+export function buildDiscriminatorChildMap(schemas: ast.SchemaNode[]): Map<string, DiscriminatorTarget> {
   const childMap = new Map<string, DiscriminatorTarget>()
 
-  for (const schema of root.schemas) {
+  for (const schema of schemas) {
     // Case 1: top-level schema is a union (oneOf/anyOf with discriminator)
     // Case 2: top-level schema is an intersection wrapping a union (oneOf/anyOf + shared properties)
     let unionNode = ast.narrowSchema(schema, 'union')
@@ -79,6 +72,46 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
     }
   }
 
+  return childMap
+}
+
+/**
+ * Patches a single top-level `SchemaNode` with its discriminator entry (adds or replaces
+ * the discriminant property). Used by the streaming path to apply patches inline per yield
+ * without buffering all schemas.
+ */
+export function patchDiscriminatorNode(node: ast.SchemaNode, entry: { propertyName: string; enumValues: Array<string | number | boolean> }): ast.SchemaNode {
+  const objectNode = ast.narrowSchema(node, 'object')
+  if (!objectNode) return node
+
+  const { propertyName, enumValues } = entry
+  const enumSchema = ast.createSchema({ type: 'enum', enumValues })
+  const newProp = ast.createProperty({ name: propertyName, required: true, schema: enumSchema })
+
+  const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName)
+  const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => (i === existingIdx ? newProp : p)) : [...objectNode.properties, newProp]
+
+  return { ...objectNode, properties: newProperties }
+}
+
+/**
+ * Injects discriminator enum values into child schemas so they know which value identifies them.
+ *
+ * Finds every union schema in `input.schemas` that has a `discriminatorPropertyName`, collects the
+ * enum value each union member is mapped to, then adds (or replaces) that property on the matching
+ * child object schema.
+ *
+ * Returns a new `InputNode` — the original is never mutated.
+ *
+ * @example
+ * ```ts
+ * const { root } = parseOas(document, options)
+ * const next = applyDiscriminatorInheritance(root)
+ * ```
+ */
+export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNode {
+  const childMap = buildDiscriminatorChildMap(root.schemas)
+
   if (childMap.size === 0) return root
 
   return ast.transform(root, {
@@ -88,21 +121,7 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
       const entry = childMap.get(node.name)
       if (!entry) return
 
-      const objectNode = ast.narrowSchema(node, 'object')
-      if (!objectNode) return
-
-      const { propertyName, enumValues } = entry
-      const enumSchema = ast.createSchema({ type: 'enum', enumValues })
-      const newProp = ast.createProperty({
-        name: propertyName,
-        required: true,
-        schema: enumSchema,
-      })
-
-      const existingIdx = objectNode.properties.findIndex((p) => p.name === propertyName)
-      const newProperties = existingIdx >= 0 ? objectNode.properties.map((p, i) => (i === existingIdx ? newProp : p)) : [...objectNode.properties, newProp]
-
-      return { ...objectNode, properties: newProperties }
+      return patchDiscriminatorNode(node, entry)
     },
   })
 }

package/src/parser.ts

@@ -76,9 +76,9 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
  * Each converter branch (`convertRef`, `convertAllOf`, etc.) mutually recursively calls `parseSchema`,
  * made possible by hoisting of function declarations.
  *
- * @note Not exported; called internally by `parseOas()` and `parseSchema()`.
+ * @internal
  */
-function createSchemaParser(ctx: OasParserContext) {
+export function createSchemaParser(ctx: OasParserContext) {
   const document = ctx.document
 
   // Branch handlers — each converts one OAS schema pattern to a SchemaNode.
@@ -98,7 +98,7 @@ function createSchemaParser(ctx: OasParserContext) {
    * 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)
+   * Memoizing 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>()
@@ -245,7 +245,7 @@ function createSchemaParser(ctx: OasParserContext) {
 
     return ast.createSchema({
       type: 'intersection',
-      members: [...ast.mergeAdjacentObjects(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjects(allOfMembers.slice(syntheticStart))],
+      members: [...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(0, syntheticStart)), ...ast.mergeAdjacentObjectsLazy(allOfMembers.slice(syntheticStart))],
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
   }
@@ -1009,7 +1009,7 @@ export function parseOas(
   const baseOas = new BaseOas(document)
   const paths = baseOas.getPaths()
 
-  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([_path, methods]) =>
+  const operations: Array<ast.OperationNode> = Object.entries(paths).flatMap(([, methods]) =>
     Object.entries(methods)
       .map(([, operation]) => (operation ? _parseOperation(mergedOptions, operation) : null))
       .filter((op): op is ast.OperationNode => op !== null),