@kubb/adapter-oas 5.0.0-beta.19 → 5.0.0-beta.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.19",
+  "version": "5.0.0-beta.20",
   "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.19"
+    "@kubb/core": "5.0.0-beta.20"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.bench.ts

@@ -48,10 +48,9 @@ describe.skipIf(!hasStripe)('Stripe spec — batch vs streaming (1,385 schemas)'
   )
 
   bench(
-    'streaming — adapter.count() + stream() drain',
+    'streaming — adapter.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 */

package/src/adapter.ts

@@ -1,11 +1,12 @@
+import { once } from '@internals/utils'
 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, buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
 import { parseDocument, parseFromConfig, validateDocument } from './factory.ts'
-import { createSchemaParser, parseOas } from './parser.ts'
-import { getSchemas, resolveServerUrl } from './resolvers.ts'
+import { createSchemaParser } from './parser.ts'
+import { getSchemas } from './resolvers.ts'
+import { createInputStream, preScan, resolveBaseUrl } from './stream.ts'
 import type { AdapterOas, Document } from './types.ts'
 
 /**
@@ -57,40 +58,52 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
 
   let nameMapping = new Map<string, string>()
   let parsedDocument: Document | null = null
-  let schemaObjects: ReturnType<typeof getSchemas>['schemas'] | null = null
-  let baseOasInstance: BaseOas | null = null
-  let schemaParserInstance: ReturnType<typeof createSchemaParser> | 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
+  // `once` collapses concurrent callers (e.g. a build's `stream()` racing with `openInStudio()`'s `parse()`) onto one in-flight promise.
+  const ensureDocument = once(async (source: AdapterSource): Promise<Document> => {
     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
-  }
-
-  function ensureBaseOas(document: Document): BaseOas {
-    if (!baseOasInstance) baseOasInstance = new BaseOas(document)
-    return baseOasInstance
-  }
-
-  function ensureSchemaParser(document: Document): ReturnType<typeof createSchemaParser> {
-    if (!schemaParserInstance) schemaParserInstance = createSchemaParser({ document, contentType })
-    return schemaParserInstance
+  })
+
+  const ensureSchemas = once(async (document: Document) => {
+    const result = getSchemas(document, { contentType })
+    nameMapping = result.nameMapping
+    return result.schemas
+  })
+
+  const ensureBaseOas = once((document: Document) => new BaseOas(document))
+
+  const ensureSchemaParser = once((document: Document) => createSchemaParser({ document, contentType }))
+
+  const ensurePreScan = once((schemas: Awaited<ReturnType<typeof ensureSchemas>>, parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema']) =>
+    preScan({ schemas, parseSchema, parserOptions, discriminator }),
+  )
+
+  async function createStream(source: AdapterSource): Promise<ast.InputStreamNode> {
+    const document = await ensureDocument(source)
+    const schemas = await ensureSchemas(document)
+    const { parseSchema, parseOperation } = ensureSchemaParser(document)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap } = ensurePreScan(schemas, parseSchema)
+
+    return createInputStream({
+      schemas,
+      parseSchema,
+      parseOperation,
+      baseOas: ensureBaseOas(document),
+      parserOptions,
+      refAliasMap,
+      discriminatorChildMap,
+      meta: {
+        title: document.info?.title,
+        description: document.info?.description,
+        version: document.info?.version,
+        baseURL: resolveBaseUrl({ document, serverIndex, serverVariables }),
+        circularNames,
+        enumNames,
+      },
+    })
   }
 
   return {
@@ -130,98 +143,18 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
       })
     },
     async parse(source) {
-      const document = await ensureDocument(source)
-
-      const { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-        contentType,
-        dateType,
-        integerType,
-        unknownType,
-        emptySchemaType,
-        enumSuffix,
-      })
-
-      const node = discriminator === 'inherit' ? applyDiscriminatorInheritance(parsedRoot) : parsedRoot
-
-      // This must happen after parseOas() because legacy enum remapping is finalized there.
-      nameMapping = parsedNameMapping
-
-      return ast.createInput({
-        ...node,
-        meta: {
-          title: document.info?.title,
-          description: document.info?.description,
-          version: document.info?.version,
-          baseURL: resolveBaseURL(document),
-        },
-      })
-    },
-    async count(source) {
-      const document = await ensureDocument(source)
-      const schemas = await ensureSchemas(document)
-
-      const baseOas = ensureBaseOas(document)
-      const operationCount = Object.values(baseOas.getPaths()).flatMap(Object.values).filter(Boolean).length
+      const streamNode = await createStream(source)
 
-      return { schemas: Object.keys(schemas).length, operations: operationCount }
-    },
-    async stream(source) {
-      const document = await ensureDocument(source)
-      const schemas = await ensureSchemas(document)
-
-      const discriminatorChildMap: Awaited<ReturnType<typeof buildDiscriminatorChildMap>> | null = (() => {
-        if (discriminator !== 'inherit') return null
-        const { parseSchema: _preParser } = ensureSchemaParser(document)
-        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))
-          }
-        }
-        return parentNodes.length > 0 ? buildDiscriminatorChildMap(parentNodes) : null
-      })()
-
-      // Each [Symbol.asyncIterator]() call returns a fresh generator so multiple
-      // plugins can do independent `for await` passes without shared state.
-      // The underlying parser and BaseOas instance are cached at adapter scope.
-      const schemasIterable: AsyncIterable<ast.SchemaNode> = {
-        [Symbol.asyncIterator]() {
-          return (async function* () {
-            const { parseSchema: _parseSchema } = ensureSchemaParser(document)
-            for (const [name, schema] of Object.entries(schemas)) {
-              const parsedNode = _parseSchema({ schema, name }, parserOptions)
-              const entry = discriminatorChildMap?.get(name)
-              const node = entry ? patchDiscriminatorNode(parsedNode, entry) : parsedNode
-              yield node
-            }
-          })()
-        },
+      const collect = async <T>(iter: AsyncIterable<T>): Promise<T[]> => {
+        const out: T[] = []
+        for await (const item of iter) out.push(item)
+        return out
       }
 
-      const operationsIterable: AsyncIterable<ast.OperationNode> = {
-        [Symbol.asyncIterator]() {
-          return (async function* () {
-            const { parseOperation: _parseOperation } = ensureSchemaParser(document)
-            const baseOas = ensureBaseOas(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
-              }
-            }
-          })()
-        },
-      }
+      const [schemas, operations] = await Promise.all([collect(streamNode.schemas), collect(streamNode.operations)])
 
-      return ast.createStreamInput(schemasIterable, operationsIterable, {
-        title: document.info?.title,
-        description: document.info?.description,
-        version: document.info?.version,
-        baseURL: resolveBaseURL(document),
-      })
+      return ast.createInput({ schemas, operations, meta: streamNode.meta })
     },
+    stream: createStream,
   }
 })

package/src/discriminator.ts

@@ -1,6 +1,7 @@
 import { ast } from '@kubb/core'
+import type { SchemaNodeByType } from '@kubb/ast'
 
-type DiscriminatorTarget = {
+export type DiscriminatorTarget = {
   propertyName: string
   enumValues: Array<string | number | boolean>
 }
@@ -43,8 +44,8 @@ export function buildDiscriminatorChildMap(schemas: ast.SchemaNode[]): Map<strin
       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'] | undefined
+      let objNode: SchemaNodeByType['object'] | undefined
 
       for (const m of intersectionNode.members) {
         refNode ??= ast.narrowSchema(m, 'ref')

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.
  *

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 `undefined` 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 | undefined {
+  const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
+  return server?.url ? resolveServerUrl(server, serverVariables) : undefined
+}
+
+/**
+ * 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)
+}