@kubb/adapter-oas 5.0.0-beta.4 → 5.0.0-beta.40

package/src/adapter.ts

@@ -1,21 +1,26 @@
 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 { assertInputExists, 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 +29,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()],
  * })
  * ```
@@ -37,6 +47,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     serverIndex,
     serverVariables,
     discriminator = 'strict',
+    dedupe = true,
     dateType = DEFAULT_PARSER_OPTIONS.dateType,
     integerType = DEFAULT_PARSER_OPTIONS.integerType,
     unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
@@ -44,10 +55,115 @@ 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
+
+  // Cache per source and per document so one adapter instance reused across a `defineConfig` array
+  // parses each config's spec instead of replaying the first one. Keying the document by its source
+  // object still collapses a config's concurrent `stream()` (build) and `parse()` (studio) calls,
+  // which share one source object, onto a single parse. The document-derived caches key off the
+  // resulting document, so distinct configs (distinct documents) stay isolated.
+  const documentCache = new WeakMap<AdapterSource, Promise<Document>>()
+  const schemasCache = new WeakMap<Document, Promise<ReturnType<typeof getSchemas>['schemas']>>()
+  const baseOasCache = new WeakMap<Document, BaseOas>()
+  const schemaParserCache = new WeakMap<Document, ReturnType<typeof createSchemaParser>>()
+  const preScanCache = new WeakMap<Document, ReturnType<typeof preScan>>()
+
+  function ensureDocument(source: AdapterSource): Promise<Document> {
+    const cached = documentCache.get(source)
+    if (cached) return cached
+
+    const promise = (async () => {
+      const fresh = await parseFromConfig(source)
+      if (validate) await validateDocument(fresh)
+      parsedDocument = fresh
+      return fresh
+    })()
+    documentCache.set(source, promise)
+    return promise
+  }
+
+  function ensureSchemas(document: Document): Promise<ReturnType<typeof getSchemas>['schemas']> {
+    const cached = schemasCache.get(document)
+    if (cached) return cached
+
+    const promise = Promise.resolve().then(() => {
+      const result = getSchemas(document, { contentType })
+      nameMapping = result.nameMapping
+      return result.schemas
+    })
+    schemasCache.set(document, promise)
+    return promise
+  }
+
+  function ensureBaseOas(document: Document): BaseOas {
+    const cached = baseOasCache.get(document)
+    if (cached) return cached
+
+    const baseOas = new BaseOas(document)
+    baseOasCache.set(document, baseOas)
+    return baseOas
+  }
+
+  function ensureSchemaParser(document: Document): ReturnType<typeof createSchemaParser> {
+    const cached = schemaParserCache.get(document)
+    if (cached) return cached
+
+    const parser = createSchemaParser({ document, contentType })
+    schemaParserCache.set(document, parser)
+    return parser
+  }
+
+  function ensurePreScan(
+    document: Document,
+    schemas: ReturnType<typeof getSchemas>['schemas'],
+    parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
+    parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
+    baseOas: BaseOas,
+  ): ReturnType<typeof preScan> {
+    const cached = preScanCache.get(document)
+    if (cached) return cached
+
+    const result = preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe })
+    preScanCache.set(document, result)
+    return result
+  }
+
+  async function createStream(source: AdapterSource): Promise<ast.InputStreamNode> {
+    const document = await ensureDocument(source)
+    const schemas = await ensureSchemas(document)
+    const { parseSchema, parseOperation } = ensureSchemaParser(document)
+    const baseOas = ensureBaseOas(document)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas)
+
+    return createInputStream({
+      schemas,
+      parseSchema,
+      parseOperation,
+      baseOas,
+      parserOptions,
+      refAliasMap,
+      discriminatorChildMap,
+      dedupePlan,
+      meta: {
+        title: document.info?.title,
+        description: document.info?.description,
+        version: document.info?.version,
+        baseURL: resolveBaseUrl({ document, serverIndex, serverVariables }),
+        circularNames,
+        enumNames,
+      },
+    })
+  }
 
   return {
     name: adapterOasName,
@@ -58,6 +174,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
         serverIndex,
         serverVariables,
         discriminator,
+        dedupe,
         dateType,
         integerType,
         unknownType,
@@ -69,8 +186,10 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     get document() {
       return parsedDocument
     },
-    get inputNode() {
-      return inputNode
+    async validate(input, options) {
+      await assertInputExists(input)
+      const document = await parseDocument(input)
+      await validateDocument(document, options)
     },
     getImports(node, resolve) {
       return ast.collectImports({
@@ -78,49 +197,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/constants.ts

@@ -79,6 +79,14 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  * formatMap['float']  // 'number'
  * ```
  */
+/**
+ * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+ * `int64` and the date/time family. Keep this in sync with the `convertFormat`
+ * special-cases in `parser.ts`. `isHandledFormat` reads it so the
+ * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+ */
+export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
+
 export const formatMap = {
   uuid: 'uuid',
   email: 'email',

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,22 @@
 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.
+ * 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`.
  *
- * 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)
- * ```
+ * The streaming path calls this 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 +43,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,48 +54,39 @@ 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)
     }
   }
 
-  if (childMap.size === 0) return root
-
-  return ast.transform(root, {
-    schema(node, { parent }) {
-      if (parent?.kind !== 'Input' || !node.name) return
-
-      const entry = childMap.get(node.name)
-      if (!entry) return
+  return childMap
+}
 
-      const objectNode = ast.narrowSchema(node, 'object')
-      if (!objectNode) return
+/**
+ * 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 { 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]
+  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 { ...objectNode, properties: newProperties }
 }

package/src/factory.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
-import { mergeDeep, URLPath } from '@internals/utils'
+import { exists, mergeDeep, URLPath } from '@internals/utils'
+import { Diagnostics } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
 import { bundle, loadConfig } from '@redocly/openapi-core'
 import OASNormalize from 'oas-normalize'
@@ -74,13 +75,16 @@ 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.')
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputRequired,
+      severity: 'error',
+      message: 'No OAS documents were provided for merging.',
+      help: 'Pass at least one path or document to `input.path`.',
+      location: { kind: 'config' },
+    })
   }
 
   const seed: Document = {
@@ -102,9 +106,9 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
  * Creates a `Document` from an `AdapterSource`.
  *
  * Handles all three source types:
- * - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
- * - `{ type: 'paths' }` — merges multiple file paths into a single document.
- * - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+ * - `{ type: 'path' }` resolves and bundles a local file path or remote URL.
+ * - `{ type: 'paths' }` merges multiple file paths into a single document.
+ * - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
  *
  * @example
  * ```ts
@@ -112,7 +116,7 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
  * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
  * ```
  */
-export function parseFromConfig(source: AdapterSource): Promise<Document> {
+export async function parseFromConfig(source: AdapterSource): Promise<Document> {
   if (source.type === 'data') {
     if (typeof source.data === 'object') {
       return parseDocument(structuredClone(source.data) as Document)
@@ -130,7 +134,29 @@ export function parseFromConfig(source: AdapterSource): Promise<Document> {
     return parseDocument(source.path)
   }
 
-  return parseDocument(path.resolve(path.dirname(source.path), source.path))
+  const resolved = path.resolve(path.dirname(source.path), source.path)
+  await assertInputExists(resolved)
+  return parseDocument(resolved)
+}
+
+/**
+ * Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+ * URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+ * its parse error instead.
+ */
+export async function assertInputExists(input: string): Promise<void> {
+  if (new URLPath(input).isURL) {
+    return
+  }
+  if (!(await exists(input))) {
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputNotFound,
+      severity: 'error',
+      message: `Cannot read the file set in \`input.path\` (or via \`kubb generate PATH\`): ${input}`,
+      help: 'Check that the path exists and is readable, then set it in `input.path` or pass it as `kubb generate PATH`.',
+      location: { kind: 'config' },
+    })
+  }
 }
 
 /**
@@ -160,6 +186,6 @@ export async function validateDocument(document: Document, { throwOnError = fals
       throw error
     }
 
-    // Validation failures are non-fatal — mirror plugin-oas behavior
+    // Validation failures are non-fatal, mirror plugin-oas behavior
   }
 }

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,