@kubb/adapter-oas 5.0.0-alpha.12 → 5.0.0-alpha.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-alpha.12",
+  "version": "5.0.0-alpha.14",
   "description": "OpenAPI / Swagger adapter for Kubb — converts OAS input into a @kubb/ast RootNode.",
   "keywords": [
     "openapi",
@@ -46,8 +46,8 @@
     "openapi-types": "^12.1.3",
     "remeda": "^2.33.6",
     "swagger2openapi": "^7.0.8",
-    "@kubb/ast": "5.0.0-alpha.12",
-    "@kubb/core": "5.0.0-alpha.12"
+    "@kubb/ast": "5.0.0-alpha.14",
+    "@kubb/core": "5.0.0-alpha.14"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -87,15 +87,14 @@ export const adapterOas = createAdapter<OasAdapter>((options) => {
       const baseURL = server?.url ? resolveServerUrl(server, serverVariables) : undefined
 
       const parser = createOasParser(oas, { contentType, collisionDetection })
+      const root = parser.parse({ dateType, integerType, unknownType, emptySchemaType, enumSuffix })
 
-      // Sync the adapter's shared nameMapping with the one computed by the parser.
+      // This must happen after parse() because legacy enum remapping is finalized there.
       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: {

package/src/oas/utils.ts

@@ -323,15 +323,14 @@ export function extractSchemaFromContent(content: Record<string, unknown> | unde
  * Returns the PascalCase suffix appended to a component name when resolving
  * cross-source name collisions (schemas vs. responses vs. requestBodies).
  */
+const semanticSuffixes: Record<SchemaSourceMode, string> = {
+  schemas: 'Schema',
+  responses: 'Response',
+  requestBodies: 'Request',
+}
+
 function getSemanticSuffix(source: SchemaSourceMode): string {
-  switch (source) {
-    case 'schemas':
-      return 'Schema'
-    case 'responses':
-      return 'Response'
-    case 'requestBodies':
-      return 'Request'
-  }
+  return semanticSuffixes[source]
 }
 
 /**

package/src/parser.ts

@@ -367,6 +367,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
     // When a child schema extends a discriminator parent via allOf and the parent's oneOf/anyOf
     // references that child back, skip that allOf item to prevent a circular type reference.
+    // When an item is skipped, collect its discriminant value so it can be injected below.
+    const filteredDiscriminantValues: Array<{ propertyName: string; value: string }> = []
     const allOfMembers: Array<SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
         if (!isReference(item) || !name) return true
@@ -377,12 +379,18 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         const childRef = `#/components/schemas/${name}`
         const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
-        return !inOneOf && !inMapping
+        if (inOneOf || inMapping) {
+          const discriminatorValue = Object.entries(deref.discriminator.mapping ?? {}).find(([, v]) => v === childRef)?.[0]
+          if (discriminatorValue) {
+            filteredDiscriminantValues.push({ propertyName: deref.discriminator.propertyName, value: discriminatorValue })
+          }
+          return false
+        }
+        return true
       })
       .map((s) => convertSchema({ schema: s as SchemaObject }, options))
 
-    // Track where allOf-derived members end so only the synthetic members added below
-    // (injected required-key objects + outer-properties object) are candidates for merging.
+    // Track where allOf-derived members end so each portion can be merged independently.
     const syntheticStart = allOfMembers.length
 
     // When `required` lists keys not present in the outer `properties`, resolve them from
@@ -414,10 +422,32 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options))
     }
 
+    // Inject a synthetic single-property object for each discriminant value collected from
+    // filtered discriminator parents so that child schemas carry the narrowed literal type.
+    for (const { propertyName, value } of filteredDiscriminantValues) {
+      allOfMembers.push(
+        createSchema({
+          type: 'object',
+          primitive: 'object',
+          properties: [
+            createProperty({
+              name: propertyName,
+              schema: createSchema({
+                type: 'enum',
+                primitive: 'string',
+                enumValues: [value],
+              }),
+              required: true,
+            }),
+          ],
+        }),
+      )
+    }
+
     // Merge consecutive anonymous object members within the synthetic portion — see `mergeAdjacentAnonymousObjects`.
     return createSchema({
       type: 'intersection',
-      members: [...allOfMembers.slice(0, syntheticStart), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
+      members: [...mergeAdjacentAnonymousObjects(allOfMembers.slice(0, syntheticStart)), ...mergeAdjacentAnonymousObjects(allOfMembers.slice(syntheticStart))],
       ...renderSchemaBase(schema, name, nullable, defaultValue),
     })
   }
@@ -471,6 +501,45 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       })
     }
 
+    // When a discriminator with mapping is present but there are no sibling properties,
+    // embed the narrowed discriminant value into each member to produce precise literal
+    // intersection types (e.g. `Cat & { type: 'cat' }`) instead of plain `Cat | Dog`.
+    const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    if (discriminator?.mapping) {
+      return createSchema({
+        type: 'union',
+        ...unionBase,
+        members: unionMembers.map((s) => {
+          const ref = isReference(s) ? s.$ref : undefined
+          const discriminatorValue = ref ? Object.entries(discriminator.mapping!).find(([, v]) => v === ref)?.[0] : undefined
+          const memberNode = convertSchema({ schema: s as SchemaObject }, options)
+
+          if (!discriminatorValue) return memberNode
+
+          const discriminantNode = createSchema({
+            type: 'object',
+            primitive: 'object',
+            properties: [
+              createProperty({
+                name: discriminator.propertyName,
+                schema: createSchema({
+                  type: 'enum',
+                  primitive: 'string',
+                  enumValues: [discriminatorValue],
+                }),
+                required: true,
+              }),
+            ],
+          })
+
+          return createSchema({
+            type: 'intersection',
+            members: [memberNode, discriminantNode],
+          })
+        }),
+      })
+    }
+
     return createSchema({
       type: 'union',
       ...unionBase,
@@ -487,6 +556,8 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     const constValue = schema.const
 
     if (constValue === null) {
+      // Do not propagate `nullable` here: the type is already `null`, so marking it
+      // nullable too would cause the printer to emit `null | null`.
       return createSchema({
         type: 'null',
         primitive: 'null',
@@ -494,7 +565,6 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
         title: schema.title,
         description: schema.description,
         deprecated: schema.deprecated,
-        nullable,
       })
     }
 
@@ -719,15 +789,21 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
           const childName = resolveChildName(name, propName)
           const propNode = convertSchema({ schema: resolvedPropSchema, name: childName }, options)
-          const schemaNode = applyEnumName(propNode, name, propName, mergedOptions.enumSuffix)
+          let schemaNode = applyEnumName(propNode, name, propName, mergedOptions.enumSuffix)
+
+          const tupleNode = narrowSchema(schemaNode, 'tuple')
+          if (tupleNode?.items) {
+            const namedItems = tupleNode.items.map((item) => applyEnumName(item, name, propName, mergedOptions.enumSuffix))
+            if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
+              schemaNode = { ...tupleNode, items: namedItems }
+            }
+          }
 
           return createProperty({
             name: propName,
             schema: {
               ...schemaNode,
-              nullable: propNullable || undefined,
-              optional: !required && !propNullable ? true : undefined,
-              nullish: !required && propNullable ? true : undefined,
+              nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
             },
             required,
           })
@@ -783,12 +859,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
   /**
    * Converts an OAS 3.1 `prefixItems` tuple into a `TupleSchemaNode`.
    *
-   * Each `prefixItems` element maps to a positional tuple slot. An optional `items` schema
-   * after the prefix items is mapped to the rest parameter of the tuple.
+   * Each `prefixItems` element maps to a positional tuple slot. When an explicit `items` schema
+   * is present alongside `prefixItems`, it becomes the rest element. When `items` is absent,
+   * a rest element of type `any` is emitted to match JSON Schema semantics (absent `items`
+   * means additional items are allowed).
    */
   function convertTuple({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
     const tupleItems = (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item as SchemaObject }, options))
-    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, options) : undefined
+    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, options) : createSchema({ type: 'any' })
 
     return createSchema({
       type: 'tuple',
@@ -983,15 +1061,14 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
   /**
    * Converts a single dereferenced OAS parameter object into a `ParameterNode`.
-   * When the parameter has no `schema` or its schema is a `$ref`, falls back to `unknownType`.
+   * When the parameter has no `schema`, falls back to `unknownType`; `$ref` schemas are resolved through `convertSchema` to produce a proper named type reference.
    */
   function parseParameter(options: ParserOptions, param: Record<string, unknown>): ParameterNode {
     const required = (param['required'] as boolean | undefined) ?? false
 
-    const schema: SchemaNode =
-      param['schema'] && !isReference(param['schema'])
-        ? convertSchema({ schema: param['schema'] as SchemaObject }, options)
-        : createSchema({ type: resolveTypeOption(options.unknownType) })
+    const schema: SchemaNode = param['schema']
+      ? convertSchema({ schema: param['schema'] as SchemaObject }, options)
+      : createSchema({ type: resolveTypeOption(options.unknownType) })
 
     return createParameter({
       name: param['name'] as string,
@@ -999,7 +1076,6 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
       schema: {
         ...schema,
         description: (param['description'] as string | undefined) ?? schema.description,
-        optional: !required || !!schema.optional ? true : undefined,
       },
       required,
     })
@@ -1015,6 +1091,11 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
     const requestBodySchema = oas.getRequestSchema(operation)
     const requestBodySchemaNode = requestBodySchema ? convertSchema({ schema: requestBodySchema }, options) : undefined
 
+    const requestBodyDescription =
+      operation.schema.requestBody && !isReference(operation.schema.requestBody)
+        ? (operation.schema.requestBody as { description?: string }).description
+        : undefined
+
     const requestBodyKeysToOmit = requestBodySchema?.properties
       ? Object.entries(requestBodySchema.properties)
           .filter(([, prop]) => !isReference(prop) && (prop as { readOnly?: boolean }).readOnly)
@@ -1023,6 +1104,7 @@ export function createOasParser(oas: Oas, { contentType, collisionDetection }: O
 
     const requestBody = requestBodySchemaNode
       ? {
+          description: requestBodyDescription,
           schema: requestBodySchemaNode,
           keysToOmit: requestBodyKeysToOmit?.length ? requestBodyKeysToOmit : undefined,
         }