@kubb/adapter-oas 5.0.0-beta.6 → 5.0.0-beta.61

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.6",
-  "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.61",
+  "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",
     "codegen",
@@ -21,7 +21,6 @@
   "files": [
     "src",
     "dist",
-    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -43,13 +42,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.4",
-    "oas": "^32.1.18",
-    "oas-normalize": "^16.0.4",
+    "@readme/openapi-parser": "^6.1.3",
+    "api-ref-bundler": "0.5.1",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.6"
+    "yaml": "^2.9.0",
+    "@kubb/ast": "5.0.0-beta.61",
+    "@kubb/core": "5.0.0-beta.61"
   },
   "devDependencies": {
+    "@types/json-schema": "^7.0.15",
     "@types/swagger2openapi": "^7.0.4",
     "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
@@ -58,15 +59,18 @@
     "node": ">=22"
   },
   "inlinedDependencies": {
+    "@types/json-schema": "7.0.15",
     "openapi-types": "12.1.3"
   },
   "scripts": {
+    "bench": "vitest bench",
     "build": "tsdown",
-    "clean": "npx rimraf ./dist",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/adapter.bench.ts

@@ -0,0 +1,60 @@
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+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 petStorePath = path.resolve(import.meta.dirname, '../mocks/petStore.yaml')
+const stripeSpecPath = '/tmp/kubb-stripe-spec3.json'
+const hasStripe = existsSync(stripeSpecPath)
+
+let petStoreDoc: Document | undefined
+
+async function getPetStoreDocument(): Promise<Document> {
+  if (!petStoreDoc) {
+    petStoreDoc = await parseDocument(petStorePath)
+  }
+  return petStoreDoc
+}
+
+describe('parseOas() performance', () => {
+  bench(
+    'petStore spec',
+    async () => {
+      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.stream() drain',
+    async () => {
+      const adapter = adapterOas({ validate: false })
+      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,21 +1,27 @@
 import { ast, createAdapter } from '@kubb/core'
+import type { AdapterSource } from '@kubb/core'
 import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
-import { applyDiscriminatorInheritance } from './discriminator.ts'
-import { parseDocument, 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'
+import { collect, narrowSchema } from '@kubb/ast'
+import { extractRefName } from '@kubb/ast/utils'
 
 /**
- * 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()],
  * })
  * ```
@@ -37,6 +48,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 +56,103 @@ 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 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 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'],
+  ): ReturnType<typeof preScan> {
+    const cached = preScanCache.get(document)
+    if (cached) return cached
+
+    const result = preScan({ schemas, parseSchema, parseOperation, document, parserOptions, discriminator, dedupe })
+    preScanCache.set(document, result)
+    return result
+  }
+
+  async function createStream(source: AdapterSource): Promise<ast.InputNode<true>> {
+    const document = await ensureDocument(source)
+    const schemas = await ensureSchemas(document)
+    const { parseSchema, parseOperation } = ensureSchemaParser(document)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation)
+
+    return createInputStream({
+      schemas,
+      parseSchema,
+      parseOperation,
+      document,
+      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 +163,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
         serverIndex,
         serverVariables,
         discriminator,
+        dedupe,
         dateType,
         integerType,
         unknownType,
@@ -69,62 +175,33 @@ 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({
-        node,
-        nameMapping,
-        resolve: (schemaName) => {
+      return collect(node, {
+        schema(schemaNode) {
+          const schemaRef = narrowSchema(schemaNode, 'ref')
+          if (!schemaRef?.ref) return null
+
+          const rawName = extractRefName(schemaRef.ref)
+          const schemaName = nameMapping.get(rawName) ?? rawName
           const result = resolve(schemaName)
-          if (!result) return
+          if (!result) return null
 
-          return ast.createImport({ name: [result.name], path: result.path })
+          return ast.factory.createImport({ name: [result.name], path: result.path })
         },
       })
     },
     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 { root: parsedRoot, nameMapping: parsedNameMapping } = parseOas(document, {
-        contentType,
-        dateType,
-        integerType,
-        unknownType,
-        emptySchemaType,
-        enumSuffix,
-      })
+      const streamNode = await createStream(source)
 
-      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([Array.fromAsync(streamNode.schemas), Array.fromAsync(streamNode.operations)])
 
-      return inputNode
+      return ast.factory.createInput({ schemas, operations, meta: streamNode.meta })
     },
+    stream: createStream,
   }
 })

package/src/bundler.ts

@@ -0,0 +1,71 @@
+import { read } from '@internals/utils'
+import { bundle } from 'api-ref-bundler'
+import { parse } from 'yaml'
+import type { Document } from './types.ts'
+
+const urlRegExp = /^https?:\/+/i
+
+async function readSource(sourcePath: string): Promise<string> {
+  if (urlRegExp.test(sourcePath)) {
+    // api-ref-bundler joins relative refs with posix normalization, collapsing `https://` to
+    // `https:/`. The WHATWG URL parser restores the double slash.
+    const url = new URL(sourcePath)
+    const response = await fetch(url)
+
+    if (!response.ok) {
+      throw new Error(`Cannot fetch the OAS document at ${url.href} (HTTP ${response.status})`)
+    }
+
+    return response.text()
+  }
+
+  return read(sourcePath)
+}
+
+async function resolveSource(sourcePath: string): Promise<object | string> {
+  const data = await readSource(sourcePath)
+
+  if (sourcePath.toLowerCase().endsWith('.md')) {
+    return data
+  }
+
+  return parse(data) as object
+}
+
+/**
+ * Bundles a multi-file OpenAPI document into a single document via `api-ref-bundler`.
+ *
+ * External file schemas are hoisted into named `components.schemas` entries, so a property
+ * pointing at `./schemas/User.yaml` ends up referencing `#/components/schemas/User`. Generators
+ * can then emit a named type with an import instead of inlining the shape. Sources are read with
+ * the Bun-aware `read` util for local YAML and JSON files, and with `fetch` for HTTP(S) URLs.
+ *
+ * @example Local file
+ * `const document = await bundleDocument('./openapi.yaml')`
+ *
+ * @example Remote URL
+ * `const document = await bundleDocument('https://example.com/openapi.yaml')`
+ */
+export async function bundleDocument(pathOrUrl: string): Promise<Document> {
+  const cache = new Map<string, Promise<object | string>>()
+
+  const resolver = (sourcePath: string) => {
+    // api-ref-bundler refers to the same URL as both `https://` and the posix-normalized
+    // `https:/`, so cache on the canonical href to fetch each source once.
+    const key = urlRegExp.test(sourcePath) ? new URL(sourcePath).href : sourcePath
+    const cached = cache.get(key)
+    if (cached) {
+      return cached
+    }
+
+    const result = resolveSource(sourcePath)
+    cache.set(key, result)
+    return result
+  }
+
+  // api-ref-bundler swallows resolver errors and leaves refs unresolved, so surface an
+  // unreadable input document as a hard error before bundling.
+  await resolver(pathOrUrl)
+
+  return (await bundle(pathOrUrl, resolver)) as Document
+}

package/src/constants.ts

@@ -31,6 +31,12 @@ export const DEFAULT_PARSER_OPTIONS = {
  */
 export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
 
+/**
+ * HTTP methods that count as operations on an OpenAPI path item. Other keys
+ * (`parameters`, `summary`, `$ref`, vendor extensions) are skipped when iterating operations.
+ */
+export const SUPPORTED_METHODS: ReadonlySet<string> = new Set(['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'])
+
 /**
  * OpenAPI version string written into the stub document created during multi-spec merges.
  */
@@ -67,7 +73,7 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  *
  * Only formats whose AST type differs from the OAS `type` field appear here.
  * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
- * in the parser. `ipv4` and `ipv6` map to their own dedicated schema types; `hostname` and
+ * in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname` and
  * `idn-hostname` map to `'url'` as the closest generic string-format type.
  *
  * @example
@@ -79,6 +85,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',
@@ -112,8 +126,8 @@ export const formatMap = {
 export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
 
 /**
- * Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
- * Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+ * Maps the `unknownType`/`emptySchemaType` option string to its `ScalarSchemaType` constant.
+ * A `Map` (over a plain object) lets callers test key membership with `.has()`.
  */
 export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
   ['any', ast.schemaTypes.any],

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