@kubb/plugin-oas 4.18.5 → 4.19.1

package/src/SchemaGenerator.ts

@@ -3,7 +3,7 @@ import { BaseGenerator, type FileMetaBase } from '@kubb/core'
 import transformers, { pascalCase } from '@kubb/core/transformers'
 import { type AsyncEventEmitter, getUniqueName } from '@kubb/core/utils'
 import type { KubbFile } from '@kubb/fabric-core/types'
-import type { contentType, Oas, OpenAPIV3, SchemaObject } from '@kubb/oas'
+import type { contentType, Oas, OasTypes, OpenAPIV3, SchemaObject } from '@kubb/oas'
 import { isDiscriminator, isNullable, isReference } from '@kubb/oas'
 import type { Fabric } from '@kubb/react-fabric'
 import pLimit from 'p-limit'
@@ -12,7 +12,6 @@ import type { Generator } from './generators/types.ts'
 import { isKeyword, type Schema, type SchemaKeywordMapper, schemaKeywords } from './SchemaMapper.ts'
 import type { OperationSchema, Override, Refs } from './types.ts'
 import { getSchemaFactory } from './utils/getSchemaFactory.ts'
-import { getSchemas } from './utils/getSchemas.ts'
 import { buildSchema } from './utils.tsx'
 
 export type GetSchemaGeneratorOptions<T extends SchemaGenerator<any, any, any>> = T extends SchemaGenerator<infer Options, any, any> ? Options : never
@@ -41,6 +40,11 @@ export type SchemaGeneratorOptions = {
   emptySchemaType: 'any' | 'unknown' | 'void'
   enumType?: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral'
   enumSuffix?: string
+  /**
+   * @deprecated Will be removed in v5. Use `collisionDetection: true` instead to prevent enum name collisions.
+   * When `collisionDetection` is enabled, the rootName-based approach eliminates the need for numeric suffixes.
+   * @internal
+   */
   usedEnumNames?: Record<string, number>
   mapper?: Record<string, string>
   typed?: boolean
@@ -64,6 +68,7 @@ type SchemaProps = {
   schema: SchemaObject | null
   name: string | null
   parentName: string | null
+  rootName?: string | null
 }
 
 export class SchemaGenerator<
@@ -74,13 +79,31 @@ export class SchemaGenerator<
   // Collect the types of all referenced schemas, so we can export them later
   refs: Refs = {}
 
-  // Keep track of already used type aliases
-  #usedAliasNames: Record<string, number> = {}
+  // Map from original component paths to resolved schema names (after collision resolution)
+  // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
+  #schemaNameMapping: Map<string, string> = new Map()
+
+  // Flag to track if nameMapping has been initialized
+  #nameMappingInitialized = false
 
   // Cache for parsed schemas to avoid redundant parsing
   // Using WeakMap for automatic garbage collection when schemas are no longer referenced
   #parseCache: Map<string, Schema[]> = new Map()
 
+  /**
+   * Ensure the name mapping is initialized (lazy initialization)
+   */
+  #ensureNameMapping() {
+    if (this.#nameMappingInitialized) {
+      return
+    }
+
+    const { oas, contentType, include } = this.context
+    const { nameMapping } = oas.getSchemas({ contentType, includes: include })
+    this.#schemaNameMapping = nameMapping
+    this.#nameMappingInitialized = true
+  }
+
   /**
    * Creates a type node from a given schema.
    * Delegates to getBaseTypeFromSchema internally and
@@ -102,6 +125,7 @@ export class SchemaGenerator<
           schema: props.schema,
           name: props.name,
           parentName: props.parentName,
+          rootName: props.rootName,
         })
 
         const cached = this.#parseCache.get(cacheKey)
@@ -321,7 +345,7 @@ export class SchemaGenerator<
   /**
    * Recursively creates a type literal with the given props.
    */
-  #parseProperties(name: string | null, schemaObject: SchemaObject): Schema[] {
+  #parseProperties(name: string | null, schemaObject: SchemaObject, rootName?: string | null): Schema[] {
     const properties = schemaObject?.properties || {}
     const additionalProperties = schemaObject?.additionalProperties
     const required = schemaObject?.required
@@ -335,7 +359,7 @@ export class SchemaGenerator<
         const isRequired = Array.isArray(required) ? required?.includes(propertyName) : !!required
         const nullable = isNullable(propertySchema)
 
-        validationFunctions.push(...this.parse({ schema: propertySchema, name: propertyName, parentName: name }))
+        validationFunctions.push(...this.parse({ schema: propertySchema, name: propertyName, parentName: name, rootName: rootName || name }))
 
         validationFunctions.push({
           keyword: schemaKeywords.name,
@@ -359,7 +383,7 @@ export class SchemaGenerator<
       additionalPropertiesSchemas =
         additionalProperties === true || !Object.keys(additionalProperties).length
           ? [{ keyword: this.#getUnknownType(name) }]
-          : this.parse({ schema: additionalProperties as SchemaObject, name: null, parentName: name })
+          : this.parse({ schema: additionalProperties as SchemaObject, name: null, parentName: name, rootName: rootName || name })
     }
 
     let patternPropertiesSchemas: Record<string, Schema[]> = {}
@@ -369,7 +393,7 @@ export class SchemaGenerator<
         const schemas =
           patternSchema === true || !Object.keys(patternSchema as object).length
             ? [{ keyword: this.#getUnknownType(name) }]
-            : this.parse({ schema: patternSchema, name: null, parentName: name })
+            : this.parse({ schema: patternSchema, name: null, parentName: name, rootName: rootName || name })
 
         return {
           ...acc,
@@ -453,15 +477,21 @@ export class SchemaGenerator<
       ]
     }
 
-    const originalName = getUniqueName($ref.replace(/.+\//, ''), this.#usedAliasNames)
+    // Ensure name mapping is initialized before resolving names
+    this.#ensureNameMapping()
+
+    const originalName = $ref.replace(/.+\//, '')
+    // Use the full $ref path to look up the collision-resolved name
+    const resolvedName = this.#schemaNameMapping.get($ref) || originalName
+
     const propertyName = this.context.pluginManager.resolveName({
-      name: originalName,
+      name: resolvedName,
       pluginKey: this.context.plugin.key,
       type: 'function',
     })
 
     const fileName = this.context.pluginManager.resolveName({
-      name: originalName,
+      name: resolvedName,
       pluginKey: this.context.plugin.key,
       type: 'file',
     })
@@ -473,7 +503,7 @@ export class SchemaGenerator<
 
     this.refs[$ref] = {
       propertyName,
-      originalName,
+      originalName: resolvedName,
       path: file.path,
     }
 
@@ -504,7 +534,7 @@ export class SchemaGenerator<
       return schema
     }
 
-    const objectPropertySchema = SchemaGenerator.find(this.parse({ schema: schemaObject, name: null, parentName: null }), schemaKeywords.object)
+    const objectPropertySchema = SchemaGenerator.find(this.parse({ schema: schemaObject, name: null, parentName: null, rootName: null }), schemaKeywords.object)
 
     return {
       ...schema,
@@ -605,7 +635,7 @@ export class SchemaGenerator<
    * This is the very core of the OpenAPI to TS conversion - it takes a
    * schema and returns the appropriate type.
    */
-  #parseSchemaObject({ schema: _schemaObject, name, parentName }: SchemaProps): Schema[] {
+  #parseSchemaObject({ schema: _schemaObject, name, parentName, rootName }: SchemaProps): Schema[] {
     const normalizedSchema = this.context.oas.flattenSchema(_schemaObject)
 
     const { schemaObject, version } = this.#getParsedSchemaObject(normalizedSchema)
@@ -710,6 +740,7 @@ export class SchemaGenerator<
                     schema: { ...schemaObject, type: item },
                     name,
                     parentName,
+                    rootName,
                   })[0],
               )
               .filter(Boolean)
@@ -764,7 +795,7 @@ export class SchemaGenerator<
         args: (schemaObject.oneOf || schemaObject.anyOf)!
           .map((item) => {
             // first item, this is ref
-            return item && this.parse({ schema: item as SchemaObject, name, parentName })[0]
+            return item && this.parse({ schema: item as SchemaObject, name, parentName, rootName })[0]
           })
           .filter(Boolean),
       }
@@ -778,7 +809,7 @@ export class SchemaGenerator<
       }
 
       if (schemaWithoutOneOf.properties) {
-        const propertySchemas = this.parse({ schema: schemaWithoutOneOf, name, parentName })
+        const propertySchemas = this.parse({ schema: schemaWithoutOneOf, name, parentName, rootName })
 
         union.args = [
           ...union.args.map((arg) => {
@@ -808,7 +839,7 @@ export class SchemaGenerator<
               return []
             }
 
-            return item ? this.parse({ schema: item, name, parentName }) : []
+            return item ? this.parse({ schema: item, name, parentName, rootName }) : []
           })
           .filter(Boolean),
       }
@@ -848,7 +879,7 @@ export class SchemaGenerator<
         }
 
         for (const item of parsedItems) {
-          const parsed = this.parse({ schema: item, name, parentName })
+          const parsed = this.parse({ schema: item, name, parentName, rootName })
 
           if (Array.isArray(parsed)) {
             and.args = and.args ? and.args.concat(parsed) : parsed
@@ -857,7 +888,7 @@ export class SchemaGenerator<
       }
 
       if (schemaWithoutAllOf.properties) {
-        and.args = [...(and.args || []), ...this.parse({ schema: schemaWithoutAllOf, name, parentName })]
+        and.args = [...(and.args || []), ...this.parse({ schema: schemaWithoutAllOf, name, parentName, rootName })]
       }
 
       return SchemaGenerator.combineObjects([and, ...baseItems])
@@ -880,12 +911,22 @@ export class SchemaGenerator<
           items: normalizedItems,
         } as SchemaObject
 
-        return this.parse({ schema: normalizedSchema, name, parentName })
+        return this.parse({ schema: normalizedSchema, name, parentName, rootName })
       }
 
       // Removed verbose enum parsing debug log - too noisy for hundreds of enums
 
-      const enumName = getUniqueName(pascalCase([parentName, name, options.enumSuffix].join(' ')), this.options.usedEnumNames || {})
+      // Include rootName in enum naming to avoid collisions for nested enums with same path
+      // Only add rootName if it differs from parentName to avoid duplication
+      // This is controlled by the collisionDetection flag to maintain backward compatibility
+      const useCollisionDetection = this.context.oas.options.collisionDetection ?? false
+      const enumNameParts =
+        useCollisionDetection && rootName && rootName !== parentName ? [rootName, parentName, name, options.enumSuffix] : [parentName, name, options.enumSuffix]
+
+      // @deprecated usedEnumNames will be removed in v5 - collisionDetection with rootName-based naming eliminates the need for numeric suffixes
+      const enumName = useCollisionDetection
+        ? pascalCase(enumNameParts.join(' '))
+        : getUniqueName(pascalCase(enumNameParts.join(' ')), this.options.usedEnumNames || {})
       const typeName = this.context.pluginManager.resolveName({
         name: enumName,
         pluginKey: this.context.plugin.key,
@@ -1016,13 +1057,14 @@ export class SchemaGenerator<
             max,
             items: prefixItems
               .map((item) => {
-                return this.parse({ schema: item, name, parentName })[0]
+                return this.parse({ schema: item, name, parentName, rootName })[0]
               })
               .filter(Boolean),
             rest: this.parse({
               schema: items,
               name,
               parentName,
+              rootName,
             })[0],
           },
         },
@@ -1168,7 +1210,7 @@ export class SchemaGenerator<
     if ('items' in schemaObject || schemaObject.type === ('array' as 'string')) {
       const min = schemaObject.minimum ?? schemaObject.minLength ?? schemaObject.minItems ?? undefined
       const max = schemaObject.maximum ?? schemaObject.maxLength ?? schemaObject.maxItems ?? undefined
-      const items = this.parse({ schema: 'items' in schemaObject ? (schemaObject.items as SchemaObject) : [], name, parentName })
+      const items = this.parse({ schema: 'items' in schemaObject ? (schemaObject.items as SchemaObject) : [], name, parentName, rootName })
       const unique = !!schemaObject.uniqueItems
 
       return [
@@ -1205,10 +1247,10 @@ export class SchemaGenerator<
           return acc
         }, schemaObject || {}) as SchemaObject
 
-        return [...this.#parseProperties(name, schemaObjectOverridden), ...baseItems]
+        return [...this.#parseProperties(name, schemaObjectOverridden, rootName), ...baseItems]
       }
 
-      return [...this.#parseProperties(name, schemaObject), ...baseItems]
+      return [...this.#parseProperties(name, schemaObject, rootName), ...baseItems]
     }
 
     if (schemaObject.type) {
@@ -1244,13 +1286,29 @@ export class SchemaGenerator<
 
   async build(...generators: Array<Generator<TPluginOptions>>): Promise<Array<KubbFile.File<TFileMeta>>> {
     const { oas, contentType, include } = this.context
-    const schemas = getSchemas({ oas, contentType, includes: include })
-    const schemaEntries = Object.entries(schemas)
 
-    this.context.events?.emit('debug', {
-      date: new Date(),
-      logs: [`Building ${schemaEntries.length} schemas`, `  • Content Type: ${contentType || 'application/json'}`, `  • Generators: ${generators.length}`],
-    })
+    // Initialize the name mapping if not already done
+    if (!this.#nameMappingInitialized) {
+      const { schemas, nameMapping } = oas.getSchemas({ contentType, includes: include })
+      this.#schemaNameMapping = nameMapping
+      this.#nameMappingInitialized = true
+      const schemaEntries = Object.entries(schemas)
+
+      this.context.events?.emit('debug', {
+        date: new Date(),
+        logs: [`Building ${schemaEntries.length} schemas`, `  • Content Type: ${contentType || 'application/json'}`, `  • Generators: ${generators.length}`],
+      })
+
+      // Continue with build using the schemas
+      return this.#doBuild(schemas, generators)
+    }
+    // If already initialized, just get the schemas (without mapping)
+    const { schemas } = oas.getSchemas({ contentType, includes: include })
+    return this.#doBuild(schemas, generators)
+  }
+
+  async #doBuild(schemas: Record<string, OasTypes.SchemaObject>, generators: Array<Generator<TPluginOptions>>): Promise<Array<KubbFile.File<TFileMeta>>> {
+    const schemaEntries = Object.entries(schemas)
 
     // Increased parallelism for better performance
     // - generatorLimit increased from 1 to 3 to allow parallel generator processing
@@ -1263,7 +1321,7 @@ export class SchemaGenerator<
         const schemaTasks = schemaEntries.map(([name, schemaObject]) =>
           schemaLimit(async () => {
             const options = this.#getOptions(name)
-            const tree = this.parse({ schema: schemaObject, name, parentName: null })
+            const tree = this.parse({ schema: schemaObject, name, parentName: null, rootName: name })
 
             if (generator.type === 'react') {
               await buildSchema(

package/src/plugin.ts

@@ -23,6 +23,7 @@ export const pluginOas = definePlugin<PluginOas>((options) => {
     contentType,
     oasClass,
     discriminator = 'strict',
+    collisionDetection = false,
   } = options
 
   const getOas = async ({ validate, config, events }: { validate: boolean; config: Config; events: AsyncEventEmitter<KubbEvents> }): Promise<Oas> => {
@@ -32,6 +33,7 @@ export const pluginOas = definePlugin<PluginOas>((options) => {
     oas.setOptions({
       contentType,
       discriminator,
+      collisionDetection,
     })
 
     try {

package/src/types.ts

@@ -71,6 +71,36 @@ export type Options = {
    * Define some generators next to the JSON generation
    */
   generators?: Array<Generator<PluginOas>>
+  /**
+   * Resolve name collisions when schemas from different components share the same name (case-insensitive).
+   *
+   * When enabled, Kubb automatically detects and resolves collisions using intelligent suffixes:
+   * - Cross-component collisions: Adds semantic suffixes based on the component type (Schema/Response/Request)
+   * - Same-component collisions: Adds numeric suffixes (2, 3, ...) for case-insensitive duplicates
+   * - Nested enum collisions: Includes root schema name in enum names to prevent duplicates across schemas
+   *
+   * When disabled (legacy behavior), collisions may result in duplicate files or overwrite issues.
+   *
+   * **Cross-component collision example:**
+   * If you have "Order" in both schemas and requestBodies:
+   * - With `collisionDetection: true`: Generates `OrderSchema.ts`, `OrderRequest.ts`
+   * - With `collisionDetection: false`: May generate duplicate `Order.ts` files
+   *
+   * **Same-component collision example:**
+   * If you have "Variant" and "variant" in schemas:
+   * - With `collisionDetection: true`: Generates `Variant.ts`, `Variant2.ts`
+   * - With `collisionDetection: false`: May overwrite or create duplicates
+   *
+   * **Nested enum collision example:**
+   * If you have "params.channel" enum in both "NotificationTypeA" and "NotificationTypeB":
+   * - With `collisionDetection: true`: Generates `notificationTypeAParamsChannelEnum`, `notificationTypeBParamsChannelEnum`
+   * - With `collisionDetection: false`: Generates duplicate `paramsChannelEnum` in both files
+   *
+   * @default false (will be `true` in v5)
+   * @see https://github.com/kubb-labs/kubb/issues/1999
+   * @note In Kubb v5, this will be enabled by default and the deprecated `usedEnumNames` mechanism will be removed
+   */
+  collisionDetection?: boolean
 }
 
 /**

package/src/utils/getSchemas.ts

@@ -1,119 +1,41 @@
 import type { contentType, Oas, OasTypes } from '@kubb/oas'
 
+export type GetSchemasResult = {
+  schemas: Record<string, OasTypes.SchemaObject>
+  /**
+   * Mapping from original component name to resolved name after collision handling
+   * e.g., { 'Order': 'OrderSchema', 'variant': 'variant2' }
+   */
+  nameMapping: Map<string, string>
+}
+
 type Mode = 'schemas' | 'responses' | 'requestBodies'
 
 type GetSchemasProps = {
   oas: Oas
   contentType?: contentType
   includes?: Mode[]
-}
-
-/**
- * Collect all schema $ref dependencies recursively.
- */
-function collectRefs(schema: unknown, refs = new Set<string>()): Set<string> {
-  if (Array.isArray(schema)) {
-    for (const item of schema) {
-      collectRefs(item, refs)
-    }
-    return refs
-  }
-
-  if (schema && typeof schema === 'object') {
-    for (const [key, value] of Object.entries(schema)) {
-      if (key === '$ref' && typeof value === 'string') {
-        const match = value.match(/^#\/components\/schemas\/(.+)$/)
-        if (match) {
-          refs.add(match[1]!)
-        }
-      } else {
-        collectRefs(value, refs)
-      }
-    }
-  }
-
-  return refs
-}
-
-/**
- * Sort schemas topologically so referenced schemas appear first.
- */
-function sortSchemas(schemas: Record<string, OasTypes.SchemaObject>): Record<string, OasTypes.SchemaObject> {
-  const deps = new Map<string, string[]>()
-
-  for (const [name, schema] of Object.entries(schemas)) {
-    deps.set(name, Array.from(collectRefs(schema)))
-  }
-
-  const sorted: string[] = []
-  const visited = new Set<string>()
-
-  function visit(name: string, stack = new Set<string>()) {
-    if (visited.has(name)) {
-      return
-    }
-    if (stack.has(name)) {
-      return
-    } // circular refs, ignore
-    stack.add(name)
-    const children = deps.get(name) || []
-    for (const child of children) {
-      if (deps.has(child)) {
-        visit(child, stack)
-      }
-    }
-    stack.delete(name)
-    visited.add(name)
-    sorted.push(name)
-  }
-
-  for (const name of Object.keys(schemas)) {
-    visit(name)
-  }
-
-  const sortedSchemas: Record<string, OasTypes.SchemaObject> = {}
-  for (const name of sorted) {
-    sortedSchemas[name] = schemas[name]!
-  }
-  return sortedSchemas
+  /**
+   * Whether to resolve name collisions with suffixes.
+   * If not provided, uses oas.options.collisionDetection
+   * @default false (from oas.options or fallback)
+   */
+  collisionDetection?: boolean
 }
 
 /**
  * Collect schemas from OpenAPI components (schemas, responses, requestBodies)
- * and return them in dependency order.
+ * and return them in dependency order along with name mapping for collision resolution.
+ *
+ * This function is a wrapper around the oas.getSchemas() method for backward compatibility.
+ * New code should use oas.getSchemas() directly.
+ *
+ * @deprecated Use oas.getSchemas() instead
  */
-export function getSchemas({ oas, contentType, includes = ['schemas', 'requestBodies', 'responses'] }: GetSchemasProps): Record<string, OasTypes.SchemaObject> {
-  const components = oas.getDefinition().components
-  let schemas: Record<string, OasTypes.SchemaObject> = {}
-
-  if (includes.includes('schemas')) {
-    schemas = {
-      ...schemas,
-      ...((components?.schemas as Record<string, OasTypes.SchemaObject>) || {}),
-    }
-  }
-
-  if (includes.includes('responses')) {
-    const responses = components?.responses || {}
-    for (const [name, response] of Object.entries(responses)) {
-      const responseObject = response as OasTypes.ResponseObject
-      if (responseObject.content && !schemas[name]) {
-        const firstContentType = Object.keys(responseObject.content)[0] || 'application/json'
-        schemas[name] = responseObject.content?.[contentType || firstContentType]?.schema as OasTypes.SchemaObject
-      }
-    }
-  }
-
-  if (includes.includes('requestBodies')) {
-    const requestBodies = components?.requestBodies || {}
-    for (const [name, request] of Object.entries(requestBodies)) {
-      const requestObject = request as OasTypes.RequestBodyObject
-      if (requestObject.content && !schemas[name]) {
-        const firstContentType = Object.keys(requestObject.content)[0] || 'application/json'
-        schemas[name] = requestObject.content?.[contentType || firstContentType]?.schema as OasTypes.SchemaObject
-      }
-    }
-  }
-
-  return sortSchemas(schemas)
+export function getSchemas({ oas, contentType, includes = ['schemas', 'requestBodies', 'responses'], collisionDetection }: GetSchemasProps): GetSchemasResult {
+  return oas.getSchemas({
+    contentType,
+    includes,
+    collisionDetection,
+  })
 }