@kubb/adapter-oas 5.0.0-beta.2 → 5.0.0-beta.21

package/src/discriminator.ts

@@ -1,29 +1,23 @@
 import { ast } from '@kubb/core'
+import type { SchemaNodeByType } from '@kubb/ast'
 
-type DiscriminatorTarget = {
+export type DiscriminatorTarget = {
   propertyName: string
   enumValues: Array<string | number | boolean>
 }
 
 /**
- * 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')
@@ -50,8 +44,8 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
       const intersectionNode = ast.narrowSchema(member, 'intersection')
       if (!intersectionNode?.members) continue
 
-      let refNode: ReturnType<typeof ast.narrowSchema<'ref'>> | undefined
-      let objNode: ReturnType<typeof ast.narrowSchema<'object'>> | undefined
+      let refNode: SchemaNodeByType['ref'] | null = null
+      let objNode: SchemaNodeByType['object'] | null = null
 
       for (const m of intersectionNode.members) {
         refNode ??= ast.narrowSchema(m, 'ref')
@@ -61,24 +55,61 @@ export function applyDiscriminatorInheritance(root: ast.InputNode): ast.InputNod
       if (!refNode?.name || !objNode) continue
 
       const prop = objNode.properties.find((p) => p.name === discriminatorPropertyName)
-      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : undefined
+      const enumNode = prop ? ast.narrowSchema(prop.schema, 'enum') : null
       if (!enumNode?.enumValues?.length) continue
 
       const enumValues = enumNode.enumValues.filter((v): v is string | number | boolean => v !== null)
       if (!enumValues.length) continue
 
       const existing = childMap.get(refNode.name)
-      if (existing) {
-        existing.enumValues.push(...enumValues)
-      } else {
-        childMap.set(refNode.name, {
-          propertyName: discriminatorPropertyName,
-          enumValues: [...enumValues],
-        })
+      if (!existing) {
+        childMap.set(refNode.name, { propertyName: discriminatorPropertyName, enumValues: [...enumValues] })
+        continue
       }
+      existing.enumValues.push(...enumValues)
     }
   }
 
+  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 +119,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/factory.ts

@@ -74,10 +74,7 @@ export async function parseDocument(pathOrApi: string | Document, { canBundle =
  * ```
  */
 export async function mergeDocuments(pathOrApi: Array<string | Document>): Promise<Document> {
-  const documents: Document[] = []
-  for (const p of pathOrApi) {
-    documents.push(await parseDocument(p, { enablePaths: false, canBundle: false }))
-  }
+  const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { enablePaths: false, canBundle: false })))
 
   if (documents.length === 0) {
     throw new Error('No OAS documents provided for merging.')

package/src/index.ts

@@ -1,6 +1,6 @@
 export { adapterOas, adapterOasName } from './adapter.ts'
-export type { ParseOptions, ValidateDocumentOptions } from './factory.ts'
-export { mergeDocuments, parseDocument, parseFromConfig, validateDocument } from './factory.ts'
+export type { ValidateDocumentOptions } from './factory.ts'
+export { mergeDocuments } from './factory.ts'
 export type {
   AdapterOas,
   AdapterOasOptions,

package/src/parser.ts

@@ -30,6 +30,16 @@ export type OasParserContext = {
   contentType?: ContentType
 }
 
+/**
+ * The object returned by {@link createSchemaParser}.
+ * Contains parser functions bound to a specific document.
+ */
+export type SchemaParser = {
+  parseSchema: (entry: { schema: SchemaObject; name?: string | null }, options?: Partial<ast.ParserOptions>) => ast.SchemaNode
+  parseOperation: (options: ast.ParserOptions, operation: Operation) => ast.OperationNode
+  parseParameter: (options: ast.ParserOptions, param: Record<string, unknown>) => ast.ParameterNode
+}
+
 /**
  * Pre-computed per-schema context passed to every schema converter.
  *
@@ -76,9 +86,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.
@@ -89,6 +99,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.
+   *
+   * 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 | null>()
+
   /**
    * Converts a `$ref` schema into a `RefSchemaNode`.
    *
@@ -98,19 +122,23 @@ function createSchemaParser(ctx: OasParserContext) {
    * Circular refs are detected via `resolvingRefs` and leave `schema` as `undefined`.
    */
   function convertRef({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): ast.SchemaNode {
-    let resolvedSchema: ast.SchemaNode | undefined
+    let resolvedSchema: ast.SchemaNode | null = null
     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)) {
+        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)
       }
+      resolvedSchema = resolvedRefCache.get(refPath) ?? null
     }
 
     return ast.createSchema({
@@ -150,6 +178,7 @@ function createSchemaParser(ctx: OasParserContext) {
         default: mergedDefault,
         example: schema.example ?? memberNode.example,
         pattern: schema.pattern ?? ('pattern' in memberNode ? memberNode.pattern : undefined),
+        format: schema.format ?? memberNode.format,
       } as ast.DistributiveOmit<ast.SchemaNode, 'kind'>)
     }
 
@@ -226,7 +255,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),
     })
   }
@@ -340,6 +369,7 @@ function createSchemaParser(ctx: OasParserContext) {
         title: schema.title,
         description: schema.description,
         deprecated: schema.deprecated,
+        format: schema.format,
       })
     }
 
@@ -470,6 +500,7 @@ function createSchemaParser(ctx: OasParserContext) {
       writeOnly: schema.writeOnly,
       default: enumDefault,
       example: schema.example,
+      format: schema.format,
     }
 
     const extensionKey = enumExtensionKeys.find((key) => key in schema)
@@ -517,15 +548,17 @@ function createSchemaParser(ctx: OasParserContext) {
 
           const resolvedChildName = ast.childName(name, propName)
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
-          let schemaNode = ast.setEnumName(propNode, name, propName, options.enumSuffix)
-
-          const tupleNode = ast.narrowSchema(schemaNode, 'tuple')
-          if (tupleNode?.items) {
-            const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix))
-            if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
-              schemaNode = { ...tupleNode, items: namedItems }
+          const schemaNode = (() => {
+            const node = ast.setEnumName(propNode, name, propName, options.enumSuffix)
+            const tupleNode = ast.narrowSchema(node, 'tuple')
+            if (tupleNode?.items) {
+              const namedItems = tupleNode.items.map((item) => ast.setEnumName(item, name, propName, options.enumSuffix))
+              if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
+                return { ...tupleNode, items: namedItems }
+              }
             }
-          }
+            return node
+          })()
 
           return ast.createProperty({
             name: propName,
@@ -539,18 +572,15 @@ function createSchemaParser(ctx: OasParserContext) {
       : []
 
     const additionalProperties = schema.additionalProperties
-    let additionalPropertiesNode: ast.SchemaNode | boolean | undefined
-    if (additionalProperties === true) {
-      additionalPropertiesNode = true
-    } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
-    } else if (additionalProperties === false) {
-      additionalPropertiesNode = false
-    } else if (additionalProperties) {
-      additionalPropertiesNode = ast.createSchema({
-        type: typeOptionMap.get(options.unknownType)!,
-      })
-    }
+    const additionalPropertiesNode: ast.SchemaNode | boolean | undefined = (() => {
+      if (additionalProperties === true) return true
+      if (additionalProperties === false) return false
+      if (additionalProperties && Object.keys(additionalProperties).length > 0) {
+        return parseSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
+      }
+      if (additionalProperties) return ast.createSchema({ type: typeOptionMap.get(options.unknownType)! })
+      return undefined
+    })()
 
     const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
 
@@ -616,7 +646,7 @@ function createSchemaParser(ctx: OasParserContext) {
    */
   function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): ast.SchemaNode {
     const rawItems = schema.items as SchemaObject | undefined
-    const itemName = rawItems?.enum?.length && name ? ast.enumPropName(undefined, name, options.enumSuffix) : undefined
+    const itemName = rawItems?.enum?.length && name ? ast.enumPropName(null, name, options.enumSuffix) : undefined
     const items = rawItems ? [parseSchema({ schema: rawItems, name: itemName }, rawOptions)] : []
 
     return ast.createSchema({
@@ -683,6 +713,7 @@ function createSchemaParser(ctx: OasParserContext) {
       description: schema.description,
       deprecated: schema.deprecated,
       nullable,
+      format: schema.format,
     })
   }
 
@@ -776,6 +807,7 @@ function createSchemaParser(ctx: OasParserContext) {
       name,
       title: schema.title,
       description: schema.description,
+      format: schema.format,
     })
   }
 
@@ -839,8 +871,8 @@ function createSchemaParser(ctx: OasParserContext) {
    * Collects property names whose schema has a truthy boolean flag (`readOnly` or `writeOnly`).
    * `$ref` entries are skipped since their flags live on the dereferenced target.
    */
-  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | undefined {
-    if (!schema?.properties) return undefined
+  function collectPropertyKeysByFlag(schema: SchemaObject | null, flag: 'readOnly' | 'writeOnly'): string[] | null {
+    if (!schema?.properties) return null
 
     const keys: string[] = []
     for (const key in schema.properties) {
@@ -849,7 +881,7 @@ function createSchemaParser(ctx: OasParserContext) {
         keys.push(key)
       }
     }
-    return keys.length ? keys : undefined
+    return keys.length ? keys : null
   }
 
   /**
@@ -990,7 +1022,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),

package/src/refs.ts

@@ -1,6 +1,8 @@
 import { isReference } from './guards.ts'
 import type { Document } from './types.ts'
 
+const _refCache = new WeakMap<Document, Map<string, unknown>>()
+
 /**
  * Resolves a local JSON pointer reference from a document.
  *
@@ -18,11 +20,19 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
   if ($ref === '') {
     return null
   }
-  if ($ref.startsWith('#')) {
-    $ref = globalThis.decodeURIComponent($ref.substring(1))
-  } else {
-    return null
+  if (!$ref.startsWith('#')) return null
+  $ref = globalThis.decodeURIComponent($ref.substring(1))
+
+  let docCache = _refCache.get(document)
+  if (!docCache) {
+    docCache = new Map()
+    _refCache.set(document, docCache)
   }
+
+  if (docCache.has($ref)) {
+    return docCache.get($ref) as T
+  }
+
   const current = $ref
     .split('/')
     .filter(Boolean)
@@ -31,6 +41,8 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
   if (!current) {
     throw new Error(`Could not find a definition for ${origRef}.`)
   }
+
+  docCache.set($ref, current)
   return current as T
 }
 

package/src/resolvers.ts

@@ -305,27 +305,25 @@ export function extractSchemaFromContent(content: Record<string, unknown> | unde
 /**
  * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
  */
-function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
+function* collectRefs(schema: unknown): Generator<string, void, undefined> {
   if (Array.isArray(schema)) {
-    for (const item of schema) collectRefs(item, refs)
-    return refs
+    for (const item of schema) yield* collectRefs(item)
+    return
   }
 
   if (schema && typeof schema === 'object') {
     for (const key in schema) {
       const value = (schema as Record<string, unknown>)[key]
-      if (key === '$ref' && typeof value === 'string') {
-        if (value.startsWith(SCHEMA_REF_PREFIX)) {
-          const name = value.slice(SCHEMA_REF_PREFIX.length)
-          if (name) refs.add(name)
-        }
-      } else {
-        collectRefs(value, refs)
+      if (!(key === '$ref' && typeof value === 'string')) {
+        yield* collectRefs(value)
+        continue
+      }
+      if (value.startsWith(SCHEMA_REF_PREFIX)) {
+        const name = value.slice(SCHEMA_REF_PREFIX.length)
+        if (name) yield name
       }
     }
   }
-
-  return refs
 }
 
 /**
@@ -344,7 +342,7 @@ export function sortSchemas(schemas: Record<string, SchemaObject>): Record<strin
   const deps = new Map<string, string[]>()
 
   for (const [name, schema] of Object.entries(schemas)) {
-    deps.set(name, Array.from(collectRefs(schema)))
+    deps.set(name, [...new Set(collectRefs(schema))])
   }
 
   const sorted: string[] = []
@@ -514,6 +512,7 @@ export function buildSchemaNode(schema: SchemaObject, name: string | null | unde
     writeOnly: schema.writeOnly,
     default: defaultValue,
     example: schema.example,
+    format: schema.format,
   } as const
 }
 

package/src/stream.ts

@@ -0,0 +1,175 @@
+import { ast } from '@kubb/core'
+import type BaseOas from 'oas'
+import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
+import type { SchemaParser } from './parser.ts'
+import { resolveServerUrl } from './resolvers.ts'
+import type { DiscriminatorTarget } from './discriminator.ts'
+import type { AdapterOas, Document, SchemaObject } from './types.ts'
+
+export type PreScanResult = {
+  refAliasMap: Map<string, ast.SchemaNode>
+  enumNames: string[]
+  circularNames: string[]
+  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+}
+
+/**
+ * Reads the server URL from the document's `servers` array at `serverIndex`,
+ * interpolating any `serverVariables` into the URL template.
+ *
+ * Returns `null` when `serverIndex` is omitted or out of range.
+ *
+ * @example Resolve the first server
+ * `resolveBaseUrl({ document, serverIndex: 0 })`
+ *
+ * @example Override a path variable
+ * `resolveBaseUrl({ document, serverIndex: 0, serverVariables: { version: 'v2' } })`
+ */
+export function resolveBaseUrl({
+  document,
+  serverIndex,
+  serverVariables,
+}: {
+  document: Document
+  serverIndex?: number
+  serverVariables?: Record<string, string>
+}): string | null {
+  const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
+  return server?.url ? resolveServerUrl(server, serverVariables) : null
+}
+
+/**
+ * Parses every schema once to build the lookup structures that streaming needs upfront.
+ *
+ * Three things happen in this single pass:
+ * - `refAliasMap` records schemas that are pure `$ref` aliases so the streaming pass can inline them.
+ * - `enumNames` collects the names of every enum schema so plugins skip re-scanning the stream.
+ * - `circularNames` runs cycle detection, which requires all nodes in memory simultaneously.
+ *   The `allNodes` array is local and drops out of scope as soon as this function returns.
+ *
+ * After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
+ * Both are proportional to the number of aliases or discriminator parents, not total schema count.
+ *
+ * Each schema is parsed again during the streaming pass — this is intentional.
+ * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
+ *
+ * @example
+ * ```ts
+ * const { refAliasMap, enumNames, circularNames } = preScan({
+ *   schemas,
+ *   parseSchema,
+ *   parserOptions,
+ *   discriminator: 'strict',
+ * })
+ * ```
+ */
+export function preScan({
+  schemas,
+  parseSchema,
+  parserOptions,
+  discriminator,
+}: {
+  schemas: Record<string, SchemaObject>
+  parseSchema: (entry: { schema: SchemaObject; name: string }, options: ast.ParserOptions) => ast.SchemaNode
+  parserOptions: ast.ParserOptions
+  discriminator: AdapterOas['options']['discriminator']
+}): PreScanResult {
+  const allNodes: ast.SchemaNode[] = []
+  const refAliasMap = new Map<string, ast.SchemaNode>()
+  const enumNames: string[] = []
+  const discriminatorParentNodes: ast.SchemaNode[] = []
+
+  for (const [name, schema] of Object.entries(schemas)) {
+    const node = parseSchema({ schema, name }, parserOptions)
+    allNodes.push(node)
+    if (node.type === 'ref' && node.name && node.name !== name) {
+      refAliasMap.set(name, node)
+    }
+    if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) {
+      enumNames.push(node.name)
+    }
+    if (discriminator === 'inherit' && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) {
+      discriminatorParentNodes.push(node)
+    }
+  }
+
+  const circularNames = [...ast.findCircularSchemas(allNodes)]
+  const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
+
+  return { refAliasMap, enumNames, circularNames, discriminatorChildMap }
+}
+
+/**
+ * Creates a lazy `InputStreamNode` from already-resolved adapter state.
+ *
+ * The schema and operation iterables each start a fresh parse pass on every
+ * `[Symbol.asyncIterator]()` call. This lets multiple plugins consume the same
+ * stream object independently without sharing a cursor or holding all nodes in memory.
+ *
+ * Ref aliases in `refAliasMap` are inlined during iteration: an alias entry is replaced
+ * with its target's parsed node (but keeps the alias name) so plugins never receive bare `ref` nodes.
+ *
+ * @example
+ * ```ts
+ * const streamNode = createInputStream({ schemas, parseSchema, parseOperation, baseOas, parserOptions, refAliasMap, discriminatorChildMap, meta })
+ * for await (const schema of streamNode.schemas) {
+ *   // each call to for-await restarts from the first schema
+ * }
+ * ```
+ */
+export function createInputStream({
+  schemas,
+  parseSchema,
+  parseOperation,
+  baseOas,
+  parserOptions,
+  refAliasMap,
+  discriminatorChildMap,
+  meta,
+}: {
+  schemas: Record<string, SchemaObject>
+  parseSchema: SchemaParser['parseSchema']
+  parseOperation: SchemaParser['parseOperation']
+  baseOas: BaseOas
+  parserOptions: ast.ParserOptions
+  refAliasMap: Map<string, ast.SchemaNode>
+  discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+  meta: ast.InputMeta
+}): ast.InputStreamNode {
+  const schemasIterable: AsyncIterable<ast.SchemaNode> = {
+    [Symbol.asyncIterator]() {
+      return (async function* () {
+        for (const [name, schema] of Object.entries(schemas)) {
+          // Inline ref aliases: replace the alias entry with its target's parsed node
+          // (keeping the alias name). Skip the first parse entirely for alias entries
+          // since that result is never used.
+          const alias = refAliasMap.get(name)
+          if (alias?.name && schemas[alias.name]) {
+            yield { ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name }
+            continue
+          }
+
+          const parsed = parseSchema({ schema, name }, parserOptions)
+          const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)!) : parsed
+          yield node
+        }
+      })()
+    },
+  }
+
+  const operationsIterable: AsyncIterable<ast.OperationNode> = {
+    [Symbol.asyncIterator]() {
+      return (async function* () {
+        for (const methods of Object.values(baseOas.getPaths())) {
+          for (const operation of Object.values(methods)) {
+            if (!operation) continue
+            const node = parseOperation(parserOptions, operation)
+            if (node) yield node
+          }
+        }
+      })()
+    },
+  }
+
+  return ast.createStreamInput(schemasIterable, operationsIterable, meta)
+}