@kubb/adapter-oas 5.0.0-beta.3 → 5.0.0-beta.30

package/src/adapter.ts

@@ -1,21 +1,27 @@
+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 } from './discriminator.ts'
-import { parseFromConfig, validateDocument } from './factory.ts'
-import { parseOas } from './parser.ts'
-import { resolveServerUrl } from './resolvers.ts'
+import { parseDocument, parseFromConfig, validateDocument } from './factory.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'
 
 /**
- * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
+ * Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
  */
 export const adapterOasName = 'oas' satisfies AdapterOas['name']
 
 /**
- * Creates the default OpenAPI / Swagger adapter for Kubb.
+ * Default Kubb adapter for OpenAPI 2.0, 3.0, and 3.1 specifications. Reads the
+ * file at `input.path`, validates it, resolves the base URL, and converts every
+ * schema and operation into the universal AST that every downstream plugin
+ * consumes.
  *
- * Parses the spec, optionally validates it, resolves the base URL, and converts
- * everything into an `InputNode` that downstream plugins consume.
+ * Configure once on `defineConfig`. The adapter's choices (date representation,
+ * integer width, server URL) apply to every plugin in the build.
  *
  * @example
  * ```ts
@@ -24,8 +30,13 @@ export const adapterOasName = 'oas' satisfies AdapterOas['name']
  * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
- *   input: { path: './openapi.yaml' },
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas({
+ *     serverIndex: 0,
+ *     discriminator: 'inherit',
+ *     dateType: 'date',
+ *   }),
  *   plugins: [pluginTs()],
  * })
  * ```
@@ -44,10 +55,64 @@ 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).
+  const parserOptions: ast.ParserOptions = {
+    ...DEFAULT_PARSER_OPTIONS,
+    dateType,
+    integerType,
+    unknownType,
+    emptySchemaType,
+    enumSuffix,
+  }
+
   let nameMapping = new Map<string, string>()
-  let parsedDocument: Document | null
-  let inputNode: ast.InputNode | null
+  let parsedDocument: Document | null = null
+
+  // `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
+  })
+
+  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 {
     name: adapterOasName,
@@ -69,8 +134,9 @@ 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)
     },
     getImports(node, resolve) {
       return ast.collectImports({
@@ -78,49 +144,25 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
         nameMapping,
         resolve: (schemaName) => {
           const result = resolve(schemaName)
-          if (!result) return
+          if (!result) return null
 
           return ast.createImport({ name: [result.name], path: result.path })
         },
       })
     },
     async parse(source) {
-      const document = await parseFromConfig(source)
+      const streamNode = await createStream(source)
 
-      if (validate) {
-        await validateDocument(document)
+      const collect = async <T>(iter: AsyncIterable<T>): Promise<Array<T>> => {
+        const out: Array<T> = []
+        for await (const item of iter) out.push(item)
+        return out
       }
 
-      const server = serverIndex !== undefined ? document.servers?.at(serverIndex) : undefined
-      const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
-
-      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
-      // Expose the raw document so consumers (e.g. plugin-redoc) can access it.
-      parsedDocument = document
-
-      inputNode = ast.createInput({
-        ...node,
-        meta: {
-          title: document.info?.title,
-          description: document.info?.description,
-          version: document.info?.version,
-          baseURL,
-        },
-      })
+      const [schemas, operations] = await Promise.all([collect(streamNode.schemas), collect(streamNode.operations)])
 
-      return inputNode
+      return ast.createInput({ schemas, operations, meta: streamNode.meta })
     },
+    stream: createStream,
   }
 })

package/src/dialect.ts

@@ -0,0 +1,38 @@
+import { ast } from '@kubb/core'
+import { isDiscriminator, isNullable, isReference } from './guards.ts'
+import { resolveRef } from './refs.ts'
+import type { SchemaObject } from './types.ts'
+
+/**
+ * The OpenAPI / Swagger dialect — the default used by `@kubb/adapter-oas`.
+ *
+ * Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
+ * decisions that differ between specs (nullability, `$ref`, discriminator, binary,
+ * ref resolution) so the converter pipeline and dispatch rules stay shared. A
+ * future adapter (e.g. AsyncAPI) ships its own dialect — `type: ['null', …]`
+ * nullability, no discriminator object, binary via `contentEncoding` — and reuses
+ * the rest unchanged.
+ *
+ * Formats (`uuid`, `email`, dates, …) are intentionally NOT here: they are shared
+ * JSON Schema vocabulary, so the converters keep that common case.
+ *
+ * @example
+ * ```ts
+ * const parser = createSchemaParser(context)             // uses oasDialect
+ * const parser = createSchemaParser(context, oasDialect) // explicit
+ * ```
+ */
+export const oasDialect = ast.defineSchemaDialect({
+  name: 'oas',
+  isNullable,
+  isReference,
+  isDiscriminator,
+  isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+  resolveRef,
+})
+
+/**
+ * The concrete dialect type for `@kubb/adapter-oas`. Keeps the OAS guard predicates
+ * (`isReference`, `isDiscriminator`) intact so converters narrow schemas after a check.
+ */
+export type OasDialect = typeof oasDialect

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: Array<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,