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

package/extension.yaml

@@ -0,0 +1,344 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: adapter
+id: adapter-oas
+name: OpenAPI
+description: Parse and convert OpenAPI 2.0, 3.0, and 3.1 specifications into Kubb's universal AST with full support for discriminators, date types, and server configuration.
+category: openapi
+type: official
+npmPackage: '@kubb/adapter-oas'
+docsPath: /adapters/adapter-oas
+repo: https://github.com/kubb-labs/kubb
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: '>=5.0.0'
+  node: '>=22'
+tags:
+  - openapi
+  - swagger
+  - api-spec
+  - parser
+  - converter
+resources:
+  documentation: https://kubb.dev/adapters/adapter-oas
+  repository: https://github.com/kubb-labs/kubb
+  issues: https://github.com/kubb-labs/kubb/issues
+  changelog: https://github.com/kubb-labs/kubb/blob/main/packages/adapter-oas/CHANGELOG.md
+featured: true
+icon:
+  light: https://kubb.dev/feature/openapi.svg
+intro: |-
+  The OpenAPI adapter parses and converts your OpenAPI specification into Kubb's internal AST (Abstract Syntax Tree), which all downstream plugins consume.
+
+  The adapter is configured once in `defineConfig` and applies globally to all plugins.
+options:
+  - name: validate
+    type: boolean
+    required: false
+    default: 'true'
+    description: Validate the OpenAPI spec before parsing using `@readme/openapi-parser`.
+  - name: contentType
+    type: "'application/json' | string"
+    required: false
+    description: Preferred content-type used when extracting request/response schemas from the spec. Defaults to the first valid JSON media type found in the spec.
+    codeBlock:
+      lang: typescript
+      title: kubb.config.ts
+      twoslash: false
+      code: |-
+        import { adapterOas } from '@kubb/adapter-oas'
+
+        adapterOas({ contentType: 'application/vnd.api+json' })
+  - name: serverIndex
+    type: number
+    required: false
+    description: Index into the `servers` array from your OpenAPI spec for computing `baseURL`.
+    tip: Defining the server here will make it possible to use that endpoint as `baseURL` in other plugins.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            code: |-
+              openapi: 3.0.3
+              servers:
+                - url: http://petstore.swagger.io/api
+                - url: http://localhost:3000
+      - name: serverIndex 0
+        files:
+          - lang: typescript
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({ serverIndex: 0 })
+      - name: serverIndex 1
+        files:
+          - lang: typescript
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({ serverIndex: 1 })
+  - name: serverVariables
+    type: Record<string, string>
+    required: false
+    description: Override values for `{variable}` placeholders in the selected server URL. Only used when `serverIndex` is set. Variables not provided fall back to their `default` value from the spec.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            code: |-
+              openapi: 3.0.3
+              servers:
+                - url: https://api.{env}.example.com
+                  variables:
+                    env:
+                      default: dev
+                      enum: [dev, staging, prod]
+      - name: kubb.config.ts
+        files:
+          - lang: typescript
+            code: |-
+              import { adapterOas } from '@kubb/adapter-oas'
+
+              adapterOas({
+                serverIndex: 0,
+                serverVariables: { env: 'prod' },
+              })
+              // Results in baseURL: https://api.prod.example.com
+  - name: discriminator
+    type: "'strict' | 'inherit'"
+    required: false
+    default: "'strict'"
+    description: How the discriminator field is interpreted when processing `oneOf`/`anyOf` schemas.
+    details:
+      - title: strict
+        body: Uses `oneOf` schemas as written in the spec. The discriminator is used for type narrowing but child schemas are not modified.
+      - title: inherit
+        body: Propagates the discriminator property with appropriate enum values into each child schema, ensuring type safety and enabling better code generation.
+    examples:
+      - name: OpenAPI
+        files:
+          - lang: yaml
+            code: |-
+              openapi: 3.0.3
+              components:
+                schemas:
+                  Animal:
+                    required: [type]
+                    type: object
+                    oneOf:
+                      - $ref: '#/components/schemas/Cat'
+                      - $ref: '#/components/schemas/Dog'
+                    discriminator:
+                      propertyName: type
+                      mapping:
+                        cat: '#/components/schemas/Cat'
+                        dog: '#/components/schemas/Dog'
+                  Cat:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                      indoor:
+                        type: boolean
+                  Dog:
+                    type: object
+                    properties:
+                      type:
+                        type: string
+                      name:
+                        type: string
+      - name: strict
+        files:
+          - lang: typescript
+            code: |-
+              export type Cat = {
+                type: string
+                indoor?: boolean
+              }
+
+              export type Dog = {
+                type: string
+                name?: string
+              }
+
+              export type Animal = Cat | Dog
+      - name: inherit
+        files:
+          - lang: typescript
+            code: |-
+              export type Cat = {
+                type: 'cat'
+                indoor?: boolean
+              }
+
+              export type Dog = {
+                type: 'dog'
+                name?: string
+              }
+
+              export type Animal = Cat | Dog
+  - name: dateType
+    type: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
+    required: false
+    default: "'string'"
+    description: "How `format: 'date-time'` schemas are represented in the generated AST and downstream output."
+    details:
+      - title: 'false'
+        body: Falls through to a plain `string` type.
+      - title: "'string'"
+        body: Emits a datetime string node (e.g. `z.string().datetime()`).
+      - title: "'stringOffset'"
+        body: 'Emits a datetime node with timezone offset (`{ offset: true }`).'
+      - title: "'stringLocal'"
+        body: 'Emits a local datetime node (`{ local: true }`).'
+      - title: "'date'"
+        body: Emits a `date` node (JavaScript `Date` object).
+    examples:
+      - name: 'false'
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → plain string
+              type CreatedAt = string
+      - name: "'string' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → datetime string
+              type CreatedAt = string // validated as ISO 8601 datetime
+      - name: "'stringOffset'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → datetime string with offset
+              type CreatedAt = string // validated as ISO 8601 datetime with offset
+      - name: "'stringLocal'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → local datetime string
+              type CreatedAt = string // validated as local ISO 8601 datetime
+      - name: "'date'"
+        files:
+          - lang: typescript
+            code: |-
+              // format: date-time → JavaScript Date
+              type CreatedAt = Date
+  - name: integerType
+    type: "'number' | 'bigint'"
+    required: false
+    default: "'bigint'"
+    description: "Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes."
+    examples:
+      - name: "'number' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                id: number
+              }
+      - name: "'bigint'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                id: bigint
+              }
+  - name: unknownType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: "'any'"
+    description: AST type used when no schema type can be inferred from the OpenAPI spec.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: any
+              }
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: unknown
+              }
+      - name: "'void'"
+        files:
+          - lang: typescript
+            code: |-
+              type Pet = {
+                extra: void
+              }
+  - name: emptySchemaType
+    type: "'any' | 'unknown' | 'void'"
+    required: false
+    default: unknownType | 'any'
+    description: AST type used for completely empty schemas (`{}`).
+    tip: When not set, `emptySchemaType` falls back to the value of `unknownType`. Set it explicitly only when you want a different type for empty schemas than for unresolvable ones.
+    examples:
+      - name: "'any' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              // empty schema {} → any
+              type EmptyModel = any
+      - name: "'unknown'"
+        files:
+          - lang: typescript
+            code: |-
+              // empty schema {} → unknown
+              type EmptyModel = unknown
+  - name: enumSuffix
+    type: string
+    required: false
+    default: "'enum'"
+    description: Suffix appended to derived enum names when building nested property schema names.
+    examples:
+      - name: "'enum' (default)"
+        files:
+          - lang: typescript
+            code: |-
+              // property `status` with inline enum values
+              const statusEnum = { available: 'available', pending: 'pending' } as const
+              type StatusEnum = (typeof statusEnum)[keyof typeof statusEnum]
+      - name: "'type'"
+        files:
+          - lang: typescript
+            code: |-
+              // enumSuffix: 'type'
+              const statusType = { available: 'available', pending: 'pending' } as const
+              type StatusType = (typeof statusType)[keyof typeof statusType]
+examples:
+  - name: kubb.config.ts
+    files:
+      - lang: typescript
+        code: |-
+          import { defineConfig } from 'kubb'
+          import { adapterOas } from '@kubb/adapter-oas'
+          import { pluginTs } from '@kubb/plugin-ts'
+
+          export default defineConfig({
+            input: {
+              path: './petStore.yaml',
+            },
+            output: {
+              path: './src/gen',
+            },
+            adapter: adapterOas({
+              validate: true,
+              serverIndex: 0,
+              serverVariables: { env: 'prod' },
+              discriminator: 'inherit',
+              dateType: 'date',
+              integerType: 'number',
+              unknownType: 'unknown',
+              emptySchemaType: 'unknown',
+              enumSuffix: 'enum',
+            }),
+            plugins: [
+              pluginTs(),
+            ],
+          })

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.2",
-  "description": "OpenAPI / Swagger adapter for Kubb converts OAS input into a @kubb/ast RootNode.",
+  "version": "5.0.0-beta.21",
+  "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,6 +21,7 @@
   "files": [
     "src",
     "dist",
+    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -42,11 +43,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.3",
+    "@redocly/openapi-core": "^2.30.6",
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.2"
+    "@kubb/core": "5.0.0-beta.21"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",
@@ -67,6 +68,7 @@
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",
+    "bench": "vitest bench",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"
   }

package/src/adapter.bench.ts

@@ -0,0 +1,64 @@
+import path from 'node:path'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+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 __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const petStorePath = path.resolve(__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,9 +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 } 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'
 
 /**
@@ -44,10 +47,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 +126,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 +136,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<T[]> => {
+        const out: 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,
   }
 })