@kubb/adapter-oas 5.0.0-beta.9 → 5.0.0-beta.91

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.9",
+  "version": "5.0.0-beta.91",
   "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",
     "kubb",
+    "meta-framework",
     "oas",
     "openapi",
     "swagger",
@@ -19,9 +20,7 @@
     "directory": "packages/adapter-oas"
   },
   "files": [
-    "src",
     "dist",
-    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -43,14 +42,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.30.4",
-    "oas": "^32.1.18",
-    "oas-normalize": "^16.0.4",
-    "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.9"
+    "@readme/openapi-parser": "^6.2.0",
+    "@scalar/openapi-upgrader": "^0.2.9",
+    "api-ref-bundler": "0.5.1",
+    "yaml": "^2.9.0",
+    "@kubb/core": "5.0.0-beta.91",
+    "@kubb/ast": "5.0.0-beta.91"
   },
   "devDependencies": {
-    "@types/swagger2openapi": "^7.0.4",
+    "@types/json-schema": "^7.0.15",
     "openapi-types": "^12.1.3",
     "@internals/utils": "0.0.0"
   },
@@ -58,15 +58,15 @@
     "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",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/extension.yaml

@@ -1,344 +0,0 @@
-$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/src/adapter.ts

@@ -1,130 +0,0 @@
-import { ast, createAdapter } 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 type { AdapterOas, Document } from './types.ts'
-
-/**
- * Stable string identifier for the OAS adapter used in Kubb's adapter registry.
- */
-export const adapterOasName = 'oas' satisfies AdapterOas['name']
-
-/**
- * Creates the default OpenAPI / Swagger adapter for Kubb.
- *
- * Parses the spec, optionally validates it, resolves the base URL, and converts
- * everything into an `InputNode` that downstream plugins consume.
- *
- * @example
- * ```ts
- * import { defineConfig } from 'kubb'
- * import { adapterOas } from '@kubb/adapter-oas'
- * import { pluginTs } from '@kubb/plugin-ts'
- *
- * export default defineConfig({
- *   adapter: adapterOas({ dateType: 'date', serverIndex: 0 }),
- *   input: { path: './openapi.yaml' },
- *   plugins: [pluginTs()],
- * })
- * ```
- */
-export const adapterOas = createAdapter<AdapterOas>((options) => {
-  const {
-    validate = true,
-    contentType,
-    serverIndex,
-    serverVariables,
-    discriminator = 'strict',
-    dateType = DEFAULT_PARSER_OPTIONS.dateType,
-    integerType = DEFAULT_PARSER_OPTIONS.integerType,
-    unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
-    enumSuffix = DEFAULT_PARSER_OPTIONS.enumSuffix,
-    emptySchemaType = unknownType || DEFAULT_PARSER_OPTIONS.emptySchemaType,
-  } = options
-
-  // Let-binding so parse() can replace it with a simple reassignment (no clear+loop).
-  let nameMapping = new Map<string, string>()
-  let parsedDocument: Document | null
-  let inputNode: ast.InputNode | null
-
-  return {
-    name: adapterOasName,
-    get options() {
-      return {
-        validate,
-        contentType,
-        serverIndex,
-        serverVariables,
-        discriminator,
-        dateType,
-        integerType,
-        unknownType,
-        emptySchemaType,
-        enumSuffix,
-        nameMapping,
-      }
-    },
-    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({
-        node,
-        nameMapping,
-        resolve: (schemaName) => {
-          const result = resolve(schemaName)
-          if (!result) return
-
-          return ast.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 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,
-        },
-      })
-
-      return inputNode
-    },
-  }
-})

package/src/constants.ts

@@ -1,122 +0,0 @@
-import { ast } from '@kubb/core'
-
-/**
- * Default parser options applied when no explicit options are provided.
- *
- * @example
- * ```ts
- * import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
- *
- * const parser = createOasParser(oas)
- * const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
- * ```
- */
-export const DEFAULT_PARSER_OPTIONS = {
-  dateType: 'string',
-  integerType: 'bigint',
-  unknownType: 'any',
-  emptySchemaType: 'any',
-  enumSuffix: 'enum',
-} as const satisfies ast.ParserOptions
-
-/**
- * JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
- *
- * Used when building or parsing `$ref` strings.
- *
- * @example
- * ```ts
- * `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
- * ```
- */
-export const SCHEMA_REF_PREFIX = '#/components/schemas/' as const
-
-/**
- * OpenAPI version string written into the stub document created during multi-spec merges.
- */
-export const MERGE_OPENAPI_VERSION = '3.0.0' as const
-
-/**
- * Fallback `info.title` placed in the stub document when merging multiple API files.
- */
-export const MERGE_DEFAULT_TITLE = 'Merged API' as const
-
-/**
- * Fallback `info.version` placed in the stub document when merging multiple API files.
- */
-export const MERGE_DEFAULT_VERSION = '1.0.0' as const
-
-/**
- * Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
- *
- * A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
- * intersection member rather than being merged into the parent.
- *
- * @example
- * ```ts
- * import { structuralKeys } from '@kubb/adapter-oas'
- *
- * const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
- * // true when fragment has e.g. 'properties' or 'oneOf'
- * ```
- */
-export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
-
-/**
- * Static map from OAS `format` strings to Kubb `SchemaType` values.
- *
- * 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
- * `idn-hostname` map to `'url'` as the closest generic string-format type.
- *
- * @example
- * ```ts
- * import { formatMap } from '@kubb/adapter-oas'
- *
- * formatMap['uuid']   // 'uuid'
- * formatMap['binary'] // 'blob'
- * formatMap['float']  // 'number'
- * ```
- */
-export const formatMap = {
-  uuid: 'uuid',
-  email: 'email',
-  'idn-email': 'email',
-  uri: 'url',
-  'uri-reference': 'url',
-  url: 'url',
-  ipv4: 'ipv4',
-  ipv6: 'ipv6',
-  hostname: 'url',
-  'idn-hostname': 'url',
-  binary: 'blob',
-  byte: 'blob',
-  // Numeric formats override the OAS `type` because format is more specific.
-  // See https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.7
-  int32: 'integer',
-  float: 'number',
-  double: 'number',
-} as const satisfies Record<string, ast.SchemaType>
-
-/**
- * Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
- *
- * @example
- * ```ts
- * import { enumExtensionKeys } from '@kubb/adapter-oas'
- *
- * const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
- * ```
- */
-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()`.
- */
-export const typeOptionMap = new Map<'any' | 'unknown' | 'void', ast.ScalarSchemaType>([
-  ['any', ast.schemaTypes.any],
-  ['unknown', ast.schemaTypes.unknown],
-  ['void', ast.schemaTypes.void],
-])