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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.61",
+  "version": "5.0.0-beta.62",
   "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",
@@ -46,8 +46,8 @@
     "api-ref-bundler": "0.5.1",
     "swagger2openapi": "^7.0.8",
     "yaml": "^2.9.0",
-    "@kubb/ast": "5.0.0-beta.61",
-    "@kubb/core": "5.0.0-beta.61"
+    "@kubb/ast": "5.0.0-beta.62",
+    "@kubb/core": "5.0.0-beta.62"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",

package/src/dialect.ts

@@ -3,6 +3,25 @@ import { isDiscriminator, isNullable, isReference } from './guards.ts'
 import { resolveRef } from './refs.ts'
 import type { SchemaObject } from './types.ts'
 
+/**
+ * Derives a schema's `optional`/`nullish` flags from a parent's `required` value and the
+ * schema's own `nullable`. How "required" and "nullable" combine is OpenAPI-specific, so it
+ * lives in the dialect.
+ *
+ * - Non-required + non-nullable → `optional: true`.
+ * - Non-required + nullable → `nullish: true`.
+ * - Required → both flags cleared.
+ */
+function optionality(schema: ast.SchemaNode, required: boolean): ast.SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}
+
 /**
  * The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
  *
@@ -22,13 +41,16 @@ import type { SchemaObject } from './types.ts'
  * const parser = createSchemaParser(context, oasDialect) // explicit
  * ```
  */
-export const oasDialect = ast.defineSchemaDialect({
+export const oasDialect = ast.defineDialect({
   name: 'oas',
-  isNullable,
-  isReference,
-  isDiscriminator,
-  isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
-  resolveRef,
+  schema: {
+    isNullable,
+    isReference,
+    isDiscriminator,
+    isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+    resolveRef,
+    optionality,
+  },
 })
 
 /**

package/src/parser.ts

@@ -20,6 +20,7 @@ import {
   getSchemaType,
 } from './resolvers.ts'
 import type { ContentType, Document, Operation, ReferenceObject, SchemaObject } from './types.ts'
+import type { StatusCode } from '@kubb/ast'
 
 /**
  * Parser context holding the raw OpenAPI document and optional content-type override.
@@ -101,6 +102,22 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   return { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject
 }
 
+/**
+ * Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+ * and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+ */
+function createNullSchema(schema: SchemaObject, name: string | null | undefined): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'null',
+    primitive: 'null',
+    name,
+    title: schema.title,
+    description: schema.description,
+    deprecated: schema.deprecated,
+    format: schema.format,
+  })
+}
+
 /**
  * Names the inline enums on a property's schema, and on each item when the property is a tuple, from
  * the parent and property name. Wraps `macroEnumName` at the property construction site.
@@ -162,7 +179,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     if (refPath && !resolvingRefs.has(refPath)) {
       if (!resolvedRefCache.has(refPath)) {
         try {
-          const referenced = dialect.resolveRef<SchemaObject>(document, refPath)
+          const referenced = dialect.schema.resolveRef<SchemaObject>(document, refPath)
           if (referenced) {
             resolvingRefs.add(refPath)
             resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
@@ -223,13 +240,13 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     }> = []
     const allOfMembers: Array<ast.SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
-        if (!dialect.isReference(item) || !name) return true
-        const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
-        if (!deref || !dialect.isDiscriminator(deref)) return true
+        if (!dialect.schema.isReference(item) || !name) return true
+        const deref = dialect.schema.resolveRef<SchemaObject>(document, item.$ref)
+        if (!deref || !dialect.schema.isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `${SCHEMA_REF_PREFIX}${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inOneOf = parentUnion.some((oneOfItem) => dialect.schema.isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
           const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef)
@@ -253,9 +270,9 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
       if (missingRequired.length) {
         const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
-          if (!dialect.isReference(item)) return [item as SchemaObject]
-          const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
-          return deref && !dialect.isReference(deref) ? [deref] : []
+          if (!dialect.schema.isReference(item)) return [item as SchemaObject]
+          const deref = dialect.schema.resolveRef<SchemaObject>(document, item.$ref)
+          return deref && !dialect.schema.isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -322,10 +339,10 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const strategy: 'one' | 'any' = schema.oneOf ? 'one' : 'any'
     const unionBase = {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
-      discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
+      discriminatorPropertyName: dialect.schema.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
       strategy,
     }
-    const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : undefined
+    const discriminator = dialect.schema.isDiscriminator(schema) ? schema.discriminator : undefined
     const sharedPropertiesNode = schema.properties
       ? (() => {
           const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
@@ -338,7 +355,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
     if (sharedPropertiesNode || discriminator?.mapping) {
       const members = unionMembers.map((s) => {
-        const ref = dialect.isReference(s) ? s.$ref : undefined
+        const ref = dialect.schema.isReference(s) ? s.$ref : undefined
         const discriminatorValue = findDiscriminator(discriminator?.mapping, ref)
         const memberNode = parseSchema({ schema: s as SchemaObject, name }, rawOptions)
 
@@ -401,15 +418,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const constValue = schema.const
 
     if (constValue === null) {
-      return ast.factory.createSchema({
-        type: 'null',
-        primitive: 'null',
-        name,
-        title: schema.title,
-        description: schema.description,
-        deprecated: schema.deprecated,
-        format: schema.format,
-      })
+      return createNullSchema(schema, name)
     }
 
     const constPrimitive = getPrimitiveType(typeof constValue === 'number' ? 'number' : typeof constValue === 'boolean' ? 'boolean' : 'string')
@@ -528,15 +537,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     // render as `never` (plugin-ts) / invalid `z.enum([])` (plugin-zod). Mirror the `const: null`
     // branch so it renders as a clean `null` (not `z.null().nullable()`).
     if (nullInEnum && filteredValues.length === 0) {
-      return ast.factory.createSchema({
-        type: 'null',
-        primitive: 'null',
-        name,
-        title: schema.title,
-        description: schema.description,
-        deprecated: schema.deprecated,
-        format: schema.format,
-      })
+      return createNullSchema(schema, name)
     }
 
     const enumNullable = nullable || nullInEnum || undefined
@@ -599,20 +600,23 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ? Object.entries(schema.properties).map(([propName, propSchema]) => {
           const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required
           const resolvedPropSchema = propSchema as SchemaObject
-          const propNullable = dialect.isNullable(resolvedPropSchema)
+          const propNullable = dialect.schema.isNullable(resolvedPropSchema)
 
           const resolvedChildName = childName(name, propName)
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
           const schemaNode = nameEnums(propNode, { parentName: name, propName, enumSuffix: options.enumSuffix })
 
-          return ast.factory.createProperty({
-            name: propName,
-            schema: {
-              ...schemaNode,
-              nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
+          return ast.factory.createProperty(
+            {
+              name: propName,
+              schema: {
+                ...schemaNode,
+                nullable: schemaNode.type === 'null' ? undefined : propNullable || undefined,
+              },
+              required,
             },
-            required,
-          })
+            dialect,
+          )
         })
       : []
 
@@ -653,7 +657,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
-    if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
+    if (dialect.schema.isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
       const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : undefined
@@ -795,14 +799,14 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
    * match/convert/fall-through contract.
    */
   const schemaRules: Array<SchemaRule> = [
-    { name: 'ref', match: ({ schema }) => dialect.isReference(schema), convert: convertRef },
+    { name: 'ref', match: ({ schema }) => dialect.schema.isReference(schema), convert: convertRef },
     { name: 'allOf', match: ({ schema }) => !!schema.allOf?.length, convert: convertAllOf },
     { name: 'union', match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length), convert: convertUnion },
     { name: 'const', match: ({ schema }) => 'const' in schema && schema.const !== undefined, convert: convertConst },
     { name: 'format', match: ({ schema }) => !!schema.format, convert: convertFormat },
     {
       name: 'blob',
-      match: ({ schema }) => dialect.isBinary(schema),
+      match: ({ schema }) => dialect.schema.isBinary(schema),
       convert: convertBlob,
     },
     { name: 'multi-type', match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1, convert: convertMultiType },
@@ -848,7 +852,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       return parseSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
-    const nullable = dialect.isNullable(schema) || undefined
+    const nullable = dialect.schema.isNullable(schema) || undefined
     const defaultValue = schema.default === null && nullable ? undefined : schema.default
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
@@ -890,15 +894,18 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ? parseSchema({ schema: param['schema'] as SchemaObject, name: schemaName }, options)
       : ast.factory.createSchema({ type: typeOptionMap.get(options.unknownType)! })
 
-    return ast.factory.createParameter({
-      name: paramName,
-      in: param['in'] as ast.ParameterLocation,
-      schema: {
-        ...schema,
-        description: (param['description'] as string | undefined) ?? schema.description,
+    return ast.factory.createParameter(
+      {
+        name: paramName,
+        in: param['in'] as ast.ParameterLocation,
+        schema: {
+          ...schema,
+          description: (param['description'] as string | undefined) ?? schema.description,
+        },
+        required,
       },
-      required,
-    })
+      dialect,
+    )
   }
 
   /**
@@ -946,7 +953,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const keys: Array<string> = []
     for (const key in schema.properties) {
       const prop = schema.properties[key]
-      if (prop && !dialect.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+      if (prop && !dialect.schema.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
         keys.push(key)
       }
     }
@@ -975,11 +982,11 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       const schema = getRequestSchema(document, operation, { contentType: ct })
       if (!schema) return []
       return [
-        {
+        ast.factory.createContent({
           contentType: ct,
-          schema: ast.syncOptionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
+          schema: dialect.schema.optionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
           keysToOmit: collectPropertyKeysByFlag(schema, 'readOnly'),
-        },
+        }),
       ]
     })
 
@@ -1013,23 +1020,28 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       // Build one entry per declared response content type so plugins can union the variants.
       // When a global contentType is configured, restrict to that single type (mirrors requestBody).
       const responseContentTypes = ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)
-      const content = responseContentTypes.map((contentType) => ({ contentType, ...parseEntrySchema(contentType) }))
+      const content = responseContentTypes.map((contentType) => ast.factory.createContent({ contentType, ...parseEntrySchema(contentType) }))
 
       // Body-less responses keep a single fallback entry so the response still resolves to a
       // (void/any) schema, matching how `requestBody` only carries schemas inside `content`.
       if (content.length === 0) {
-        content.push({ contentType: getRequestContentType({ document, operation }) || 'application/json', ...parseEntrySchema(ctx.contentType) })
+        content.push(
+          ast.factory.createContent({
+            contentType: getRequestContentType({ document, operation }) || 'application/json',
+            ...parseEntrySchema(ctx.contentType),
+          }),
+        )
       }
 
       return ast.factory.createResponse({
-        statusCode: statusCode as ast.StatusCode,
+        statusCode: statusCode as StatusCode,
         description,
         content,
       })
     })
 
     const pathItem = document.paths?.[operation.path]
-    const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
+    const pathItemDoc = pathItem && !dialect.schema.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
     const pickDoc = (key: 'summary' | 'description'): string | undefined => {
       const own = operation.schema[key]
       if (typeof own === 'string') return own

package/src/stream.ts

@@ -17,52 +17,6 @@ export type PreScanResult = {
   dedupePlan: ast.DedupePlan | null
 }
 
-/**
- * Builds the deduplication plan from the already-parsed top-level schema nodes plus a
- * single extra parse pass over operations (so duplicates in request/response bodies are seen).
- *
- * Only enums and objects are candidates, and object shapes that reference a circular schema are
- * rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
- * name (collision-resolved against existing component names). Shapes without a name stay inline.
- */
-function createDedupePlan({
-  schemaNodes,
-  operationNodes,
-  schemaNames,
-  circularNames,
-}: {
-  schemaNodes: Array<ast.SchemaNode>
-  operationNodes: Array<ast.OperationNode>
-  schemaNames: Array<string>
-  circularNames: Array<string>
-}): ast.DedupePlan {
-  const circularSchemas = new Set(circularNames)
-  const usedNames = new Set(schemaNames)
-
-  return ast.buildDedupePlan([...schemaNodes, ...operationNodes], {
-    isCandidate: (node) => {
-      if (node.type === 'enum') return true
-      if (node.type !== 'object') return false
-      // Skip object shapes that are part of a circular chain, hoisting them would break the cycle.
-      if (node.name && circularSchemas.has(node.name)) return false
-      return !containsCircularRef(node, { circularSchemas })
-    },
-    nameFor: (node) => {
-      const base = node.name
-      if (!base) return null
-
-      let name = base
-      let counter = 2
-      while (usedNames.has(name)) {
-        name = `${base}${counter++}`
-      }
-      usedNames.add(name)
-      return name
-    },
-    refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`,
-  })
-}
-
 /**
  * Reads the server URL from the document's `servers` array at `serverIndex`,
  * interpolating any `serverVariables` into the URL template.
@@ -163,7 +117,34 @@ export function preScan({
       if (operationNode) operationNodes.push(operationNode)
     }
 
-    dedupePlan = createDedupePlan({ schemaNodes: allNodes, operationNodes, schemaNames: Object.keys(schemas), circularNames })
+    // Only enums and objects are candidates, and object shapes that reference a circular schema are
+    // rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
+    // name (collision-resolved against existing component names). Shapes without a name stay inline.
+    const circularSchemas = new Set(circularNames)
+    const usedNames = new Set(Object.keys(schemas))
+
+    dedupePlan = ast.buildDedupePlan([...allNodes, ...operationNodes], {
+      isCandidate: (node) => {
+        if (node.type === 'enum') return true
+        if (node.type !== 'object') return false
+        // Skip object shapes that are part of a circular chain, hoisting them would break the cycle.
+        if (node.name && circularSchemas.has(node.name)) return false
+        return !containsCircularRef(node, { circularSchemas })
+      },
+      nameFor: (node) => {
+        const base = node.name
+        if (!base) return null
+
+        let name = base
+        let counter = 2
+        while (usedNames.has(name)) {
+          name = `${base}${counter++}`
+        }
+        usedNames.add(name)
+        return name
+      },
+      refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`,
+    })
 
     for (const definition of dedupePlan.hoisted) {
       if (definition.type === 'enum' && definition.name) enumNames.push(definition.name)