@kubb/adapter-oas 5.0.0-alpha.1 → 5.0.0-alpha.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.11",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -36,8 +36,8 @@
     "!/**/__snapshots__/**"
   ],
   "dependencies": {
-    "@kubb/fabric-core": "0.13.3",
-    "@redocly/openapi-core": "^2.22.1",
+    "@kubb/fabric-core": "0.14.0",
+    "@redocly/openapi-core": "^2.24.1",
     "@stoplight/yaml": "^4.3.0",
     "fflate": "^0.8.2",
     "jsonpointer": "^5.0.1",
@@ -46,8 +46,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.1",
-    "@kubb/core": "5.0.0-alpha.1"
+    "@kubb/ast": "5.0.0-alpha.11",
+    "@kubb/core": "5.0.0-alpha.11"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -1,11 +1,13 @@
 import path from 'node:path'
 import { createRoot } from '@kubb/ast'
 import type { AdapterSource } from '@kubb/core'
-import { defineAdapter } from '@kubb/core'
+import { createAdapter } from '@kubb/core'
+import { DEFAULT_PARSER_OPTIONS } from './constants.ts'
 import { resolveServerUrl } from './oas/resolveServerUrl.ts'
 import { parseFromConfig } from './oas/utils.ts'
 import { createOasParser } from './parser.ts'
 import type { OasAdapter } from './types.ts'
+import { getImports } from './utils.ts'
 
 export const adapterOasName = 'oas' satisfies OasAdapter['name']
 
@@ -27,7 +29,7 @@ export const adapterOasName = 'oas' satisfies OasAdapter['name']
  * })
  * ```
  */
-export const adapterOas = defineAdapter<OasAdapter>((options) => {
+export const adapterOas = createAdapter<OasAdapter>((options) => {
   const {
     validate = true,
     oasClass,
@@ -35,13 +37,18 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
     serverIndex,
     serverVariables,
     discriminator = 'strict',
-    collisionDetection = false,
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
-    emptySchemaType = unknownType,
+    collisionDetection = true,
+    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
 
+  // Mutable Map shared between `options` and each `parse()` call.
+  // Populated (and replaced) on every parse so consumers always see the latest state.
+  const nameMapping = new Map<string, string>()
+
   return {
     name: adapterOasName,
     options: {
@@ -56,6 +63,11 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
       integerType,
       unknownType,
       emptySchemaType,
+      enumSuffix,
+      nameMapping,
+    },
+    getImports(node, resolve) {
+      return getImports({ node, nameMapping, resolve })
     },
     async parse(source) {
       const fakeConfig = sourceToFakeConfig(source)
@@ -75,12 +87,20 @@ export const adapterOas = defineAdapter<OasAdapter>((options) => {
       const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
 
       const parser = createOasParser(oas, { contentType, collisionDetection })
-      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType })
+
+      // Sync the adapter's shared nameMapping with the one computed by the parser.
+      nameMapping.clear()
+      for (const [key, value] of parser.nameMapping) {
+        nameMapping.set(key, value)
+      }
+
+      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType, enumSuffix })
 
       return createRoot({
         ...root,
         meta: {
           title: oas.api.info?.title,
+          description: oas.api.info?.description,
           version: oas.api.info?.version,
           baseURL,
         },

package/src/constants.ts

@@ -1,7 +1,17 @@
-import type { MediaType, SchemaType } from '@kubb/ast/types'
+import type { SchemaType } from '@kubb/ast/types'
 import type { HttpMethods as OASHttpMethods } from 'oas/types'
+import type { ParserOptions } from './types.ts'
 
-// ─── Merge defaults ────────────────────────────────────────────────────────────
+/**
+ * Default values for all `Options` fields.
+ */
+export const DEFAULT_PARSER_OPTIONS = {
+  dateType: 'string',
+  integerType: 'number',
+  unknownType: 'any',
+  emptySchemaType: 'any',
+  enumSuffix: 'enum',
+} as const satisfies ParserOptions
 
 /**
  * OpenAPI version string written into merged document stubs.
@@ -18,14 +28,12 @@ export const MERGE_DEFAULT_TITLE = 'Merged API' as const
  */
 export const MERGE_DEFAULT_VERSION = '1.0.0' as const
 
-// ─── Schema analysis ───────────────────────────────────────────────────────────
-
 /**
  * JSON Schema keywords that indicate structural composition.
  * A schema fragment containing any of these keys must not be inlined into its
  * parent during `allOf` flattening — it carries semantic meaning of its own.
  */
-export const structuralKeys = new Set<string>(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'])
+export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
 
 /**
  * Maps OAS/JSON Schema `format` strings to their Kubb `SchemaType` equivalents.
@@ -59,9 +67,8 @@ export const formatMap = {
 
 /**
  * Exhaustive list of media types that Kubb recognizes.
- * Kept as a module-level constant to avoid re-allocating the array on every call.
  */
-export const knownMediaTypes = [
+export const knownMediaTypes = new Set([
   'application/json',
   'application/xml',
   'application/x-www-form-urlencoded',
@@ -81,7 +88,7 @@ export const knownMediaTypes = [
   'image/svg+xml',
   'audio/mpeg',
   'video/mp4',
-] as const satisfies ReadonlyArray<MediaType>
+] as const)
 
 /**
  * Vendor extension keys used to attach human-readable labels to enum values.
@@ -89,7 +96,10 @@ export const knownMediaTypes = [
  */
 export const enumExtensionKeys = ['x-enumNames', 'x-enum-varnames'] as const
 
-// ─── HTTP ──────────────────────────────────────────────────────────────────────
+/**
+ * Scalar primitive schema types used for union member simplification.
+ */
+export const SCALAR_PRIMITIVE_TYPES = new Set(['string', 'number', 'integer', 'bigint', 'boolean'] as const)
 
 /**
  * Canonical HTTP method names for the Kubb OAS layer.

package/src/oas/Oas.ts

@@ -431,14 +431,15 @@ export class Oas extends BaseOas {
     return this.dereferenceWithRef(schema)
   }
 
-  getParametersSchema(operation: Operation, inKey: 'path' | 'query' | 'header'): SchemaObject | null {
-    const { contentType = operation.getContentType() } = this.#options
-
-    // Collect parameters from both operation-level and path-level, resolving $ref pointers.
-    // oas v31+ filters out $ref parameters in getParameters(), so we access raw parameters
-    // directly and resolve refs ourselves to preserve backward compatibility.
-    // Note: dereferenceWithRef preserves the $ref property on resolved objects, so we check
-    // for 'in' and 'name' fields to validate successful resolution instead of !isReference().
+  /**
+   * Returns all resolved parameters for an operation, merging path-level and operation-level
+   * parameters and deduplicating by `in:name` (operation-level takes precedence).
+   *
+   * oas v31+ filters out `$ref` parameters in `getParameters()`, so this method accesses the
+   * raw `operation.schema.parameters` and path-item parameters directly and resolves `$ref`
+   * pointers via `dereferenceWithRef` to preserve backward compatibility.
+   */
+  getParameters(operation: Operation): Array<ParameterObject> {
     const resolveParams = (params: unknown[]): Array<ParameterObject> =>
       params.map((p) => this.dereferenceWithRef(p)).filter((p): p is ParameterObject => !!p && typeof p === 'object' && 'in' in p && 'name' in p)
 
@@ -459,7 +460,13 @@ export class Oas extends BaseOas {
       }
     }
 
-    const params = Array.from(paramMap.values()).filter((v) => v.in === inKey)
+    return Array.from(paramMap.values())
+  }
+
+  getParametersSchema(operation: Operation, inKey: 'path' | 'query' | 'header'): SchemaObject | null {
+    const { contentType = operation.getContentType() } = this.#options
+
+    const params = this.getParameters(operation).filter((v) => v.in === inKey)
 
     if (!params.length) {
       return null

package/src/oas/types.ts

@@ -30,6 +30,25 @@ export type SchemaObject = OASSchemaObject & {
    */
   contentMediaType?: string
   $ref?: string
+  /**
+   * OAS 3.1 / JSON Schema: positional items in a tuple schema.
+   * Replaces the OAS 3.0 multi-item `items` array syntax.
+   */
+  prefixItems?: Array<SchemaObject | ReferenceObject>
+  /**
+   * JSON Schema: maps regex patterns to sub-schemas for additional property validation.
+   */
+  patternProperties?: Record<string, SchemaObject | boolean>
+  /**
+   * OAS 3.0 / JSON Schema: single-schema form.
+   * The OAS base type already includes this, but we re-declare it here to ensure
+   * the single-schema overload takes precedence over the multi-schema tuple form.
+   */
+  items?: SchemaObject | ReferenceObject
+  /**
+   * Enum values for this schema (narrowed from `unknown[]` in the base type).
+   */
+  enum?: Array<string | number | boolean | null>
 }
 
 /**

package/src/oas/utils.ts

@@ -183,7 +183,7 @@ export function flattenSchema(schema: SchemaObject | null): SchemaObject | null
   if (!schema?.allOf || schema.allOf.length === 0) return schema ?? null
   if (schema.allOf.some((item) => isRef(item))) return schema
 
-  const isPlainFragment = (item: SchemaObject) => !Object.keys(item).some((key) => structuralKeys.has(key))
+  const isPlainFragment = (item: SchemaObject) => !Object.keys(item).some((key) => structuralKeys.has(key as 'properties'))
   if (!schema.allOf.every((item) => isPlainFragment(item as SchemaObject))) return schema
 
   const merged: SchemaObject = { ...schema }