@kubb/adapter-oas 5.0.0-beta.30 → 5.0.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.30",
+  "version": "5.0.0-beta.31",
   "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",
@@ -43,11 +43,11 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@redocly/openapi-core": "^2.31.2",
+    "@redocly/openapi-core": "^2.31.4",
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.30"
+    "@kubb/core": "5.0.0-beta.31"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -48,6 +48,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
     serverIndex,
     serverVariables,
     discriminator = 'strict',
+    dedupe = true,
     dateType = DEFAULT_PARSER_OPTIONS.dateType,
     integerType = DEFAULT_PARSER_OPTIONS.integerType,
     unknownType = DEFAULT_PARSER_OPTIONS.unknownType,
@@ -85,24 +86,31 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
 
   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 }),
+  const ensurePreScan = once(
+    (
+      schemas: Awaited<ReturnType<typeof ensureSchemas>>,
+      parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
+      parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
+      baseOas: ReturnType<typeof ensureBaseOas>,
+    ) => preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe }),
   )
 
   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)
+    const baseOas = ensureBaseOas(document)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(schemas, parseSchema, parseOperation, baseOas)
 
     return createInputStream({
       schemas,
       parseSchema,
       parseOperation,
-      baseOas: ensureBaseOas(document),
+      baseOas,
       parserOptions,
       refAliasMap,
       discriminatorChildMap,
+      dedupePlan,
       meta: {
         title: document.info?.title,
         description: document.info?.description,
@@ -123,6 +131,7 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
         serverIndex,
         serverVariables,
         discriminator,
+        dedupe,
         dateType,
         integerType,
         unknownType,

package/src/parser.ts

@@ -494,6 +494,22 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
     const nullInEnum = schema.enum!.includes(null)
     const filteredValues = (nullInEnum ? schema.enum!.filter((v) => v !== null) : schema.enum!) as Array<string | number | boolean>
+
+    // drf-spectacular `NullEnum` ({ enum: [null] }) is just `null`; an empty enum node would
+    // 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.createSchema({
+        type: 'null',
+        primitive: 'null',
+        name,
+        title: schema.title,
+        description: schema.description,
+        deprecated: schema.deprecated,
+        format: schema.format,
+      })
+    }
+
     const enumNullable = nullable || nullInEnum || undefined
     const enumDefault = schema.default === null && enumNullable ? undefined : schema.default
     const enumPrimitive = getPrimitiveType(type)

package/src/stream.ts

@@ -1,5 +1,6 @@
 import { ast } from '@kubb/core'
 import type BaseOas from 'oas'
+import { SCHEMA_REF_PREFIX } from './constants.ts'
 import { buildDiscriminatorChildMap, patchDiscriminatorNode } from './discriminator.ts'
 import type { SchemaParser } from './parser.ts'
 import { resolveServerUrl } from './resolvers.ts'
@@ -11,6 +12,53 @@ export type PreScanResult = {
   enumNames: Array<string>
   circularNames: Array<string>
   discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+  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 !ast.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}`,
+  })
 }
 
 /**
@@ -66,13 +114,19 @@ export function resolveBaseUrl({
 export function preScan({
   schemas,
   parseSchema,
+  parseOperation,
+  baseOas,
   parserOptions,
   discriminator,
+  dedupe,
 }: {
   schemas: Record<string, SchemaObject>
   parseSchema: (entry: { schema: SchemaObject; name: string }, options: ast.ParserOptions) => ast.SchemaNode
+  parseOperation: SchemaParser['parseOperation']
+  baseOas: BaseOas
   parserOptions: ast.ParserOptions
   discriminator: AdapterOas['options']['discriminator']
+  dedupe: boolean
 }): PreScanResult {
   const allNodes: Array<ast.SchemaNode> = []
   const refAliasMap = new Map<string, ast.SchemaNode>()
@@ -96,7 +150,27 @@ export function preScan({
   const circularNames = [...ast.findCircularSchemas(allNodes)]
   const discriminatorChildMap = discriminatorParentNodes.length > 0 ? buildDiscriminatorChildMap(discriminatorParentNodes) : null
 
-  return { refAliasMap, enumNames, circularNames, discriminatorChildMap }
+  let dedupePlan: ast.DedupePlan | null = null
+  if (dedupe) {
+    // One extra parse pass over operations so duplicates in request/response bodies are seen.
+    // Reuses the already-parsed `allNodes` for schemas — no second schema parse.
+    const operationNodes: Array<ast.OperationNode> = []
+    for (const methods of Object.values(baseOas.getPaths())) {
+      for (const operation of Object.values(methods)) {
+        if (!operation) continue
+        const operationNode = parseOperation(parserOptions, operation)
+        if (operationNode) operationNodes.push(operationNode)
+      }
+    }
+
+    dedupePlan = createDedupePlan({ schemaNodes: allNodes, operationNodes, schemaNames: Object.keys(schemas), circularNames })
+
+    for (const definition of dedupePlan.hoisted) {
+      if (definition.type === 'enum' && definition.name) enumNames.push(definition.name)
+    }
+  }
+
+  return { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan }
 }
 
 /**
@@ -125,6 +199,7 @@ export function createInputStream({
   parserOptions,
   refAliasMap,
   discriminatorChildMap,
+  dedupePlan,
   meta,
 }: {
   schemas: Record<string, SchemaObject>
@@ -134,24 +209,50 @@ export function createInputStream({
   parserOptions: ast.ParserOptions
   refAliasMap: Map<string, ast.SchemaNode>
   discriminatorChildMap: Map<string, DiscriminatorTarget> | null
+  dedupePlan: ast.DedupePlan | null
   meta: ast.InputMeta
 }): ast.InputStreamNode {
+  // Rewrites a top-level schema against the dedupe plan: a structurally identical sibling
+  // becomes a `ref` alias to the canonical one (keeping its own name); otherwise nested
+  // duplicates are collapsed while the schema's own root is preserved.
+  const rewriteTopLevelSchema = (node: ast.SchemaNode): ast.SchemaNode => {
+    if (!dedupePlan) return node
+
+    const canonical = dedupePlan.canonicalBySignature.get(ast.schemaSignature(node))
+    if (canonical && canonical.name !== node.name) {
+      return ast.createSchema({
+        type: 'ref',
+        name: node.name ?? null,
+        ref: canonical.ref,
+        description: node.description,
+        deprecated: node.deprecated,
+      })
+    }
+
+    return ast.applyDedupe(node, dedupePlan.canonicalBySignature, true)
+  }
+
   const schemasIterable: AsyncIterable<ast.SchemaNode> = {
     [Symbol.asyncIterator]() {
       return (async function* () {
+        // Hoisted canonical definitions are emitted first so the schema list owns the shared shapes.
+        if (dedupePlan) {
+          for (const definition of dedupePlan.hoisted) yield definition
+        }
+
         for (const [name, schema] of Object.entries(schemas)) {
           // Inline ref aliases: replace the alias entry with its target's parsed node
           // (keeping the alias name). Skip the first parse entirely for alias entries
           // since that result is never used.
           const alias = refAliasMap.get(name)
           if (alias?.name && schemas[alias.name]) {
-            yield { ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name }
+            yield rewriteTopLevelSchema({ ...parseSchema({ schema: schemas[alias.name]!, name: alias.name }, parserOptions), name })
             continue
           }
 
           const parsed = parseSchema({ schema, name }, parserOptions)
           const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)!) : parsed
-          yield node
+          yield rewriteTopLevelSchema(node)
         }
       })()
     },
@@ -164,7 +265,7 @@ export function createInputStream({
           for (const operation of Object.values(methods)) {
             if (!operation) continue
             const node = parseOperation(parserOptions, operation)
-            if (node) yield node
+            if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan.canonicalBySignature) : node
           }
         }
       })()

package/src/types.ts

@@ -181,6 +181,18 @@ export type AdapterOasOptions = {
    * @default 'strict'
    */
   discriminator?: 'strict' | 'inherit'
+  /**
+   * Collapse structurally identical schemas and enums into a single shared definition.
+   *
+   * Duplicated inline shapes (especially enums repeated across many properties) are hoisted
+   * into one named schema; every other occurrence — and any structurally identical top-level
+   * component — becomes a `ref` to it. Equality is shape-only: documentation such as
+   * `description` and `example` is ignored. Enabled by default; set to `false` to keep every
+   * occurrence inline and produce byte-for-byte identical output to earlier versions.
+   *
+   * @default true
+   */
+  dedupe?: boolean
 } & Partial<ast.ParserOptions>
 
 /**
@@ -192,6 +204,7 @@ export type AdapterOasResolvedOptions = {
   serverIndex: AdapterOasOptions['serverIndex']
   serverVariables: AdapterOasOptions['serverVariables']
   discriminator: NonNullable<AdapterOasOptions['discriminator']>
+  dedupe: NonNullable<AdapterOasOptions['dedupe']>
   dateType: NonNullable<AdapterOasOptions['dateType']>
   integerType: NonNullable<AdapterOasOptions['integerType']>
   unknownType: NonNullable<AdapterOasOptions['unknownType']>