@kubb/adapter-oas 5.0.0-alpha.15 → 5.0.0-alpha.16

package/src/parser.ts

@@ -1,120 +1,44 @@
-import { pascalCase, URLPath } from '@internals/utils'
-import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
+import { URLPath } from '@internals/utils'
+import {
+  applyDiscriminatorEnum,
+  createOperation,
+  createParameter,
+  createProperty,
+  createResponse,
+  createRoot,
+  createSchema,
+  extractRefName,
+  mediaTypes,
+  mergeAdjacentAnonymousObjects,
+  narrowSchema,
+  schemaTypes,
+  simplifyUnionMembers,
+} from '@kubb/ast'
 import type {
-  ArraySchemaNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
+  DistributiveOmit,
   HttpMethod,
-  IntersectionSchemaNode,
   MediaType,
-  NumberSchemaNode,
-  ObjectSchemaNode,
   OperationNode,
   ParameterLocation,
   ParameterNode,
   PrimitiveSchemaType,
   PropertyNode,
-  RefSchemaNode,
   ResponseNode,
   RootNode,
-  ScalarSchemaNode,
   ScalarSchemaType,
   SchemaNode,
   SchemaType,
   StatusCode,
-  StringSchemaNode,
-  TimeSchemaNode,
-  UnionSchemaNode,
 } from '@kubb/ast/types'
-import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, formatMap, knownMediaTypes } from './constants.ts'
+import { DEFAULT_PARSER_OPTIONS, enumExtensionKeys, formatMap } from './constants.ts'
+import { createDiscriminantNode, resolveDiscriminatorValue } from './discriminator.ts'
+import type { InferSchemaNode } from './infer.ts'
+import { applyEnumName, resolveChildName, resolveEnumPropName } from './naming.ts'
 import type { Oas } from './oas/Oas.ts'
 import type { contentType, Operation, ReferenceObject, SchemaObject } from './oas/types.ts'
 import { flattenSchema, isDiscriminator, isNullable, isReference } from './oas/utils.ts'
+import { resolveRefs as resolveRefsNode } from './refResolver.ts'
 import type { ParserOptions } from './types.ts'
-import { applyDiscriminatorEnum, extractRefName, mergeAdjacentAnonymousObjects, simplifyUnionMembers } from './utils.ts'
-
-/**
- * Distributive `Omit` — correctly distributes over union types so that
- * `Omit<A | B, 'kind'>` produces `Omit<A, 'kind'> | Omit<B, 'kind'>`
- * rather than `Omit<A | B, 'kind'>`.
- */
-type DistributiveOmit<TValue, TKey extends PropertyKey> = TValue extends unknown ? Omit<TValue, TKey> : never
-
-/**
- * Maps each `dateType` option value to the AST node produced by `format: 'date-time'`.
- */
-type DateTimeNodeByDateType = {
-  date: DateSchemaNode
-  string: DatetimeSchemaNode
-  stringOffset: DatetimeSchemaNode
-  stringLocal: DatetimeSchemaNode
-  false: StringSchemaNode
-}
-
-/**
- * Resolves the AST node produced by `format: 'date-time'` based on the `dateType` option.
- */
-type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTimeNodeByDateType[TDateType extends keyof DateTimeNodeByDateType
-  ? TDateType
-  : 'string']
-
-/**
- * Single source of truth: ordered list of `[shape, SchemaNode]` pairs.
- * `InferSchemaNode` walks this tuple in order and returns the node type of the first matching entry.
- * Parameterized over `TDateType` so `format: 'date-time'` resolves to the correct node based on the option.
- */
-type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
-  [{ $ref: string }, RefSchemaNode],
-  // allOf with sibling `properties` always produces an intersection (shared props are appended as a member).
-  [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  // allOf with 2+ members always produces an intersection.
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
-  // Single-member allOf without sibling `properties` flattens to the member type.
-  [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
-  [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],
-  [{ const: null }, ScalarSchemaNode],
-  [{ const: string | number | boolean }, EnumSchemaNode],
-  // OAS 3.1 multi-type array: `{ type: ['string', 'integer'] }` → union node.
-  [{ type: ReadonlyArray<string> }, UnionSchemaNode],
-  // `{ type: 'array', enum }` is normalized at runtime: enum moves into items → array node.
-  [{ type: 'array'; enum: ReadonlyArray<unknown> }, ArraySchemaNode],
-  [{ enum: ReadonlyArray<unknown> }, EnumSchemaNode],
-  [{ type: 'object' }, ObjectSchemaNode],
-  [{ additionalProperties: boolean | {} }, ObjectSchemaNode],
-  [{ type: 'array' }, ArraySchemaNode],
-  [{ items: object }, ArraySchemaNode],
-  [{ prefixItems: ReadonlyArray<unknown> }, ArraySchemaNode],
-  // Format entries with explicit type — placed before generic type entries so format wins.
-  [{ type: string; format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ type: string; format: 'date' }, DateSchemaNode],
-  [{ type: string; format: 'time' }, TimeSchemaNode],
-  [{ format: 'date-time' }, ResolveDateTimeNode<TDateType>],
-  [{ format: 'date' }, DateSchemaNode],
-  [{ format: 'time' }, TimeSchemaNode],
-  [{ type: 'string' }, StringSchemaNode],
-  [{ type: 'number' }, NumberSchemaNode],
-  [{ type: 'integer' }, NumberSchemaNode],
-  [{ type: 'bigint' }, NumberSchemaNode],
-  [{ type: string }, ScalarSchemaNode],
-  // Inferred scalar types from constraints when no explicit type is present.
-  [{ minLength: number }, StringSchemaNode],
-  [{ maxLength: number }, StringSchemaNode],
-  [{ pattern: string }, StringSchemaNode],
-  [{ minimum: number }, NumberSchemaNode],
-  [{ maximum: number }, NumberSchemaNode],
-]
-
-export type InferSchemaNode<
-  TSchema extends SchemaObject,
-  TDateType extends ParserOptions['dateType'] = 'string',
-  TEntries extends ReadonlyArray<[object, SchemaNode]> = SchemaNodeMap<TDateType>,
-> = TEntries extends [infer TEntry extends [object, SchemaNode], ...infer TRest extends ReadonlyArray<[object, SchemaNode]>]
-  ? TSchema extends TEntry[0]
-    ? TEntry[1]
-    : InferSchemaNode<TSchema, TDateType, TRest>
-  : SchemaNode
 
 /**
  * Construction-time options for `createOasParser`.
@@ -148,7 +72,7 @@ function getPrimitiveType(type: string | undefined): PrimitiveSchemaType {
  * Returns `undefined` for content types not present in `KNOWN_MEDIA_TYPES`.
  */
 function toMediaType(contentType: string): MediaType | undefined {
-  return knownMediaTypes.has(contentType as MediaType) ? (contentType as MediaType) : undefined
+  return Object.values(mediaTypes).includes(contentType as MediaType) ? (contentType as MediaType) : undefined
 }
 
 /**
@@ -164,8 +88,8 @@ type SchemaContext = {
    * Normalized single type string (first element when OAS 3.1 multi-type array).
    */
   type: string | undefined
-  options: Partial<ParserOptions> | undefined
-  mergedOptions: ParserOptions
+  rawOptions: Partial<ParserOptions> | undefined
+  options: ParserOptions
 }
 
 /**
@@ -225,14 +149,25 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
   // e.g., { '#/components/schemas/Order': 'OrderSchema', '#/components/responses/Product': 'ProductResponse' }
   const { schemas: schemaObjects, nameMapping } = oas.getSchemas({ contentType })
 
+  const TYPE_OPTION_MAP: Record<'any' | 'unknown' | 'void', ScalarSchemaType> = {
+    any: schemaTypes.any,
+    unknown: schemaTypes.unknown,
+    void: schemaTypes.void,
+  }
+
   /**
    * Maps an `'any' | 'unknown' | 'void'` option string to the corresponding `SchemaType` constant.
    * Used for both `unknownType` (unannotated schemas) and `emptySchemaType` (empty `{}` schemas).
    */
   function resolveTypeOption(value: 'any' | 'unknown' | 'void'): ScalarSchemaType {
-    if (value === 'any') return schemaTypes.any
-    if (value === 'void') return schemaTypes.void
-    return schemaTypes.unknown
+    return TYPE_OPTION_MAP[value]
+  }
+
+  function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
+    const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
+    const normalizedItems: SchemaObject = { ...(isItemsObject ? (schema.items as SchemaObject) : {}), enum: schema.enum }
+    const { enum: _enum, ...schemaWithoutEnum } = schema
+    return { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject
   }
 
   /**
@@ -328,7 +263,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * Circular references through discriminator parents are detected and skipped to prevent
    * infinite recursion during code generation.
    */
-  function convertAllOf({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
+  function convertAllOf({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
     if (
       schema.allOf!.length === 1 &&
       !schema.properties &&
@@ -336,7 +271,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
       schema.additionalProperties === undefined
     ) {
       const [memberSchema] = schema.allOf as Array<SchemaObject | ReferenceObject>
-      const memberNode = convertSchema({ schema: memberSchema! as SchemaObject }, options)
+      const memberNode = convertSchema({ schema: memberSchema! as SchemaObject }, rawOptions)
       const { kind: _kind, ...memberNodeProps } = memberNode
       const mergedNullable = nullable || memberNode.nullable || undefined
       const mergedDefault = schema.default === null && mergedNullable ? undefined : (schema.default ?? memberNode.default)
@@ -371,7 +306,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
         const inOneOf = parentUnion.some((oneOfItem) => isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
-          const discriminatorValue = Object.entries(deref.discriminator.mapping ?? {}).find(([, v]) => v === childRef)?.[0]
+          const discriminatorValue = resolveDiscriminatorValue(deref.discriminator.mapping, childRef)
           if (discriminatorValue) {
             filteredDiscriminantValues.push({ propertyName: deref.discriminator.propertyName, value: discriminatorValue })
           }
@@ -379,7 +314,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
         }
         return true
       })
-      .map((s) => convertSchema({ schema: s as SchemaObject }, options))
+      .map((s) => convertSchema({ schema: s as SchemaObject }, rawOptions))
 
     // Track where allOf-derived members end so each portion can be merged independently.
     const syntheticStart = allOfMembers.length
@@ -400,7 +335,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
         for (const key of missingRequired) {
           for (const resolved of resolvedMembers) {
             if (resolved.properties?.[key]) {
-              allOfMembers.push(convertSchema({ schema: { properties: { [key]: resolved.properties[key] }, required: [key] } as SchemaObject }, options))
+              allOfMembers.push(convertSchema({ schema: { properties: { [key]: resolved.properties[key] }, required: [key] } as SchemaObject }, rawOptions))
               break
             }
           }
@@ -410,29 +345,13 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
 
     if (schema.properties) {
       const { allOf: _allOf, ...schemaWithoutAllOf } = schema
-      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, options))
+      allOfMembers.push(convertSchema({ schema: schemaWithoutAllOf }, rawOptions))
     }
 
     // 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,
-            }),
-          ],
-        }),
-      )
+      allOfMembers.push(createDiscriminantNode(propertyName, value))
     }
 
     // Merge consecutive anonymous object members within the synthetic portion — see `mergeAdjacentAnonymousObjects`.
@@ -451,81 +370,56 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * individually intersected with the shared properties node to match the OAS pattern of
    * adding common fields next to a discriminated union.
    */
-  function convertUnion({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode {
+  function convertUnion({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
     const unionMembers = [...(schema.oneOf ?? []), ...(schema.anyOf ?? [])]
     const unionBase = {
       ...renderSchemaBase(schema, name, nullable, defaultValue),
       discriminatorPropertyName: isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
     }
+    const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
+    const sharedPropertiesNode = schema.properties
+      ? (() => {
+          const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
+          // Strip discriminator so convertObject won't re-apply the full mapping enum.
+          const memberBaseSchema: SchemaObject = discriminator
+            ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
+            : schemaWithoutUnion
+          // Convert shared properties once to avoid duplicate enum naming
+          // (e.g. StatusEnum appearing twice and getting a numeric suffix).
+          return convertSchema({ schema: memberBaseSchema, name }, rawOptions)
+        })()
+      : undefined
 
-    if (schema.properties) {
-      const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
-      const discriminator = isDiscriminator(schema) ? schema.discriminator : undefined
-
-      // Strip discriminator so convertObject won't re-apply the full mapping enum.
-      const memberBaseSchema: SchemaObject = discriminator
-        ? (Object.fromEntries(Object.entries(schemaWithoutUnion).filter(([key]) => key !== 'discriminator')) as SchemaObject)
-        : schemaWithoutUnion
-
-      // Convert shared properties once to avoid duplicate enum naming
-      // (e.g. StatusEnum appearing twice and getting a numeric suffix).
-      const sharedPropertiesNode = convertSchema({ schema: memberBaseSchema, name }, options)
-
+    if (sharedPropertiesNode || discriminator?.mapping) {
       return createSchema({
         type: 'union',
         ...unionBase,
         members: unionMembers.map((s) => {
           const ref = isReference(s) ? s.$ref : undefined
-          const discriminatorValue = discriminator?.mapping && ref ? Object.entries(discriminator.mapping).find(([, v]) => v === ref)?.[0] : undefined
-
-          let propertiesNode = sharedPropertiesNode
-
-          if (discriminatorValue && discriminator) {
-            propertiesNode = applyDiscriminatorEnum({ node: propertiesNode, propertyName: discriminator.propertyName, values: [discriminatorValue] })
+          const discriminatorValue = resolveDiscriminatorValue(discriminator?.mapping, ref)
+          const memberNode = convertSchema({ schema: s as SchemaObject }, rawOptions)
+
+          if (sharedPropertiesNode) {
+            const narrowedProperties =
+              discriminatorValue && discriminator
+                ? applyDiscriminatorEnum({
+                    node: sharedPropertiesNode,
+                    propertyName: discriminator.propertyName,
+                    values: [discriminatorValue],
+                  })
+                : sharedPropertiesNode
+
+            return createSchema({
+              type: 'intersection',
+              members: [memberNode, narrowedProperties],
+            })
           }
 
-          return createSchema({
-            type: 'intersection',
-            members: [convertSchema({ schema: s as SchemaObject }, options), propertiesNode],
-          })
-        }),
-      })
-    }
-
-    // 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,
-              }),
-            ],
-          })
+          if (!discriminatorValue || !discriminator) return memberNode
 
           return createSchema({
             type: 'intersection',
-            members: [memberNode, discriminantNode],
+            members: [memberNode, createDiscriminantNode(discriminator.propertyName, discriminatorValue)],
           })
         }),
       })
@@ -534,7 +428,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     return createSchema({
       type: 'union',
       ...unionBase,
-      members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, options))),
+      members: simplifyUnionMembers(unionMembers.map((s) => convertSchema({ schema: s as SchemaObject }, rawOptions))),
     })
   }
 
@@ -573,13 +467,13 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * Returns `undefined` when the format should fall through to string handling
    * (i.e. `format: 'date-time'` with `dateType: false`).
    */
-  function convertFormat({ schema, name, nullable, defaultValue, mergedOptions }: SchemaContext): SchemaNode | undefined {
+  function convertFormat({ schema, name, nullable, defaultValue, options }: SchemaContext): SchemaNode | undefined {
     const base = renderSchemaBase(schema, name, nullable, defaultValue)
 
     // int64 is option-dependent so it can't live in the static formatMap.
     if (schema.format === 'int64') {
       return createSchema({
-        type: mergedOptions.integerType === 'bigint' ? 'bigint' : 'integer',
+        type: options.integerType === 'bigint' ? 'bigint' : 'integer',
         primitive: 'integer',
         ...base,
         min: schema.minimum,
@@ -591,7 +485,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
 
     // date-time / date / time are option-dependent and can't live in the static formatMap.
     if (schema.format === 'date-time' || schema.format === 'date' || schema.format === 'time') {
-      const dateType = getDateType(mergedOptions, schema.format)
+      const dateType = getDateType(options, schema.format)
       if (!dateType) return undefined // dateType: false → fall through to string
 
       if (dateType.type === 'datetime') {
@@ -625,13 +519,10 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * - Numeric and boolean enums require a const-map representation because most generators cannot
    *   use string-enum syntax for non-string values.
    */
-  function convertEnum({ schema, name, nullable, type, options }: SchemaContext): SchemaNode {
+  function convertEnum({ schema, name, nullable, type, rawOptions }: SchemaContext): SchemaNode {
     // Malformed schema: `{ type: 'array', enum: [...] }` — normalize by moving the enum into items.
     if (type === 'array') {
-      const isItemsObject = typeof schema.items === 'object' && !Array.isArray(schema.items)
-      const normalizedItems: SchemaObject = { ...(isItemsObject ? (schema.items as SchemaObject) : {}), enum: schema.enum }
-      const { enum: _enum, ...schemaWithoutEnum } = schema
-      return convertSchema({ schema: { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject, name }, options)
+      return convertSchema({ schema: normalizeArrayEnum(schema), name }, rawOptions)
     }
 
     // `null` in enum values is the OAS 3.0 convention for a nullable enum.
@@ -657,53 +548,26 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
 
     // x-enumNames / x-enum-varnames: named variants with explicit labels take priority.
     const extensionKey = enumExtensionKeys.find((key) => key in schema)
-    if (extensionKey) {
-      const rawNames = (schema as Record<string, unknown>)[extensionKey] as Array<string | number>
-      const uniqueNames = [...new Set(rawNames)]
-      const enumType =
-        getPrimitiveType(type) === 'number' || getPrimitiveType(type) === 'integer'
-          ? ('number' as const)
-          : getPrimitiveType(type) === 'boolean'
-            ? ('boolean' as const)
-            : ('string' as const)
+    if (extensionKey || enumPrimitive === 'number' || enumPrimitive === 'integer' || enumPrimitive === 'boolean') {
+      const enumType = (enumPrimitive === 'number' || enumPrimitive === 'integer' ? 'number' : enumPrimitive === 'boolean' ? 'boolean' : 'string') as
+        | 'number'
+        | 'boolean'
+        | 'string'
+      const sourceValues = extensionKey
+        ? [...new Set((schema as Record<string, unknown>)[extensionKey] as Array<string | number>)]
+        : [...new Set(filteredValues)]
 
       return createSchema({
         ...enumBase,
         enumType,
-        namedEnumValues: uniqueNames.map((label, index) => ({
+        namedEnumValues: sourceValues.map((label, index) => ({
           name: String(label),
-          value: filteredValues[index] ?? label,
+          value: extensionKey ? (filteredValues[index] ?? label) : label,
           format: enumType,
         })),
       })
     }
 
-    // Number / integer enum — must use a const map since most generators can't use string-enum for numbers.
-    if (type === 'number' || type === 'integer') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'number' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as number,
-          format: 'number' as const,
-        })),
-      })
-    }
-
-    // Boolean enum — same const-map approach as numeric.
-    if (type === 'boolean') {
-      return createSchema({
-        ...enumBase,
-        enumType: 'boolean' as const,
-        namedEnumValues: [...new Set(filteredValues)].map((value) => ({
-          name: String(value),
-          value: value as boolean,
-          format: 'boolean' as const,
-        })),
-      })
-    }
-
     // Plain string enum (default path).
     return createSchema({
       ...enumBase,
@@ -723,48 +587,8 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * - not required + not nullable → `optional: true`
    * - not required + nullable → `nullish: true`
    */
-  /**
-   * Builds the propagation name for a child property during recursive schema conversion.
-   *
-   * The parent name is prepended so the full path is encoded
-   *   (e.g. `OrderParams` when parent is `Order`).
-   */
-  function resolveChildName(parentName: string | undefined, propName: string): string | undefined {
-    return parentName ? pascalCase([parentName, propName].join(' ')) : undefined
-  }
-
-  /**
-   * Derives the final name for an enum property schema node.
-   *
-   * The resulting name always includes the enum suffix and full parent path context
-   * (e.g. `OrderParamsStatusEnum`).
-   */
-  function resolveEnumPropName(parentName: string | undefined, propName: string, enumSuffix: string): string {
-    return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
-  }
 
-  /**
-   * Given a freshly-converted property schema, returns the node with a correct
-   * `name` attached — or stripped — depending on whether the node is a named
-   * enum, a boolean const-enum (always inlined), or a regular schema.
-   */
-  function applyEnumName(propNode: SchemaNode, parentName: string | undefined, propName: string, enumSuffix: string): SchemaNode {
-    const enumNode = narrowSchema(propNode, 'enum')
-
-    // Boolean-primitive enum nodes (e.g. `const: false`) are always inlined as
-    // literal types and must not receive a named identifier.
-    if (enumNode?.primitive === 'boolean') {
-      return { ...propNode, name: undefined }
-    }
-
-    if (enumNode) {
-      return { ...propNode, name: resolveEnumPropName(parentName, propName, enumSuffix) }
-    }
-
-    return propNode
-  }
-
-  function convertObject({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
+  function convertObject({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): SchemaNode {
     const properties: Array<PropertyNode> = schema.properties
       ? Object.entries(schema.properties).map(([propName, propSchema]) => {
           const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required
@@ -772,12 +596,12 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
           const propNullable = isNullable(resolvedPropSchema)
 
           const childName = resolveChildName(name, propName)
-          const propNode = convertSchema({ schema: resolvedPropSchema, name: childName }, options)
-          let schemaNode = applyEnumName(propNode, name, propName, mergedOptions.enumSuffix)
+          const propNode = convertSchema({ schema: resolvedPropSchema, name: childName }, rawOptions)
+          let schemaNode = applyEnumName(propNode, name, propName, options.enumSuffix)
 
           const tupleNode = narrowSchema(schemaNode, 'tuple')
           if (tupleNode?.items) {
-            const namedItems = tupleNode.items.map((item) => applyEnumName(item, name, propName, mergedOptions.enumSuffix))
+            const namedItems = tupleNode.items.map((item) => applyEnumName(item, name, propName, options.enumSuffix))
             if (namedItems.some((item, i) => item !== tupleNode.items![i])) {
               schemaNode = { ...tupleNode, items: namedItems }
             }
@@ -799,11 +623,11 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     if (additionalProperties === true) {
       additionalPropertiesNode = true
     } else if (additionalProperties && Object.keys(additionalProperties).length > 0) {
-      additionalPropertiesNode = convertSchema({ schema: additionalProperties as SchemaObject }, options)
+      additionalPropertiesNode = convertSchema({ schema: additionalProperties as SchemaObject }, rawOptions)
     } else if (additionalProperties === false) {
       additionalPropertiesNode = undefined
     } else if (additionalProperties) {
-      additionalPropertiesNode = createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
+      additionalPropertiesNode = createSchema({ type: resolveTypeOption(options.unknownType) })
     }
 
     const rawPatternProperties = 'patternProperties' in schema ? schema.patternProperties : undefined
@@ -813,8 +637,8 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
           Object.entries(rawPatternProperties).map(([pattern, patternSchema]) => [
             pattern,
             patternSchema === true || (typeof patternSchema === 'object' && Object.keys(patternSchema).length === 0)
-              ? createSchema({ type: resolveTypeOption(mergedOptions.unknownType) })
-              : convertSchema({ schema: patternSchema as SchemaObject }, options),
+              ? createSchema({ type: resolveTypeOption(options.unknownType) })
+              : convertSchema({ schema: patternSchema as SchemaObject }, rawOptions),
           ]),
         )
       : undefined
@@ -833,7 +657,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     if (isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
-      const enumName = name ? resolveEnumPropName(name, discPropName, mergedOptions.enumSuffix) : undefined
+      const enumName = name ? resolveEnumPropName(name, discPropName, options.enumSuffix) : undefined
       return applyDiscriminatorEnum({ node: objectNode, propertyName: discPropName, values, enumName })
     }
 
@@ -848,9 +672,9 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * 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) : createSchema({ type: 'any' })
+  function convertTuple({ schema, name, nullable, defaultValue, rawOptions }: SchemaContext): SchemaNode {
+    const tupleItems = (schema.prefixItems ?? []).map((item) => convertSchema({ schema: item as SchemaObject }, rawOptions))
+    const rest = schema.items ? convertSchema({ schema: schema.items as SchemaObject }, rawOptions) : createSchema({ type: 'any' })
 
     return createSchema({
       type: 'tuple',
@@ -869,12 +693,12 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * When the items schema is an inline enum, a name derived from the parent array's name and
    * `enumSuffix` is forwarded so generators can emit a named enum declaration.
    */
-  function convertArray({ schema, name, nullable, defaultValue, options, mergedOptions }: SchemaContext): SchemaNode {
+  function convertArray({ schema, name, nullable, defaultValue, rawOptions, options }: SchemaContext): SchemaNode {
     const rawItems = schema.items as SchemaObject | undefined
     // When the items schema contains an inline enum, derive a named identifier
     // so generators can emit a standalone enum declaration.
-    const itemName = rawItems?.enum?.length && name ? resolveEnumPropName(undefined, name, mergedOptions.enumSuffix) : undefined
-    const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, options)] : []
+    const itemName = rawItems?.enum?.length && name ? resolveEnumPropName(undefined, name, options.enumSuffix) : undefined
+    const items = rawItems ? [convertSchema({ schema: rawItems, name: itemName }, rawOptions)] : []
 
     return createSchema({
       type: 'array',
@@ -958,13 +782,13 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
    * 10. Object / array / tuple / scalar by `type`
    * 11. Empty schema fallback (`emptySchemaType` option)
    */
-  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, options?: Partial<ParserOptions>): SchemaNode {
-    const mergedOptions: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...options }
+  function convertSchema({ schema, name }: { schema: SchemaObject; name?: string }, rawOptions?: Partial<ParserOptions>): SchemaNode {
+    const options: ParserOptions = { ...DEFAULT_PARSER_OPTIONS, ...rawOptions }
     // Flatten keyword-only allOf fragments (no $ref, no structural keys) into the parent
     // schema before parsing, so simple annotation patterns don't produce needless intersections.
     const flattenedSchema = flattenSchema(schema)
     if (flattenedSchema && flattenedSchema !== schema) {
-      return convertSchema({ schema: flattenedSchema, name }, options)
+      return convertSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
     const nullable = isNullable(schema) || undefined
@@ -972,7 +796,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     // Normalize OAS 3.1 multi-type array to a single type string for the dispatch below.
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
-    const ctx: SchemaContext = { schema, name, nullable, defaultValue, type, options, mergedOptions }
+    const ctx: SchemaContext = { schema, name, nullable, defaultValue, type, rawOptions, options }
 
     // $ref — pointer to another definition.
     // In OAS 3.0 siblings of $ref are technically ignored, but Kubb intentionally preserves them
@@ -1011,7 +835,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
       if (nonNullTypes.length > 1) {
         return createSchema({
           type: 'union',
-          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, options)),
+          members: nonNullTypes.map((t) => convertSchema({ schema: { ...schema, type: t } as SchemaObject, name }, rawOptions)),
           ...renderSchemaBase(schema, name, arrayNullable, defaultValue),
         })
       }
@@ -1039,7 +863,7 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     if (type === 'boolean') return convertBoolean(ctx)
     if (type === 'null') return convertNull(ctx)
 
-    const emptyType = resolveTypeOption(mergedOptions.emptySchemaType)
+    const emptyType = resolveTypeOption(options.emptySchemaType)
     return createSchema({ type: emptyType as ScalarSchemaType, name, title: schema.title, description: schema.description })
   }
 
@@ -1163,36 +987,11 @@ export function createOasParser(oas: Oas, { contentType }: OasParserOptions = {}
     return createRoot({ schemas, operations })
   }
 
-  /**
-   * Walks a `SchemaNode` tree and resolves all `ref` node names through the provided callbacks.
-   *
-   * `resolveName` handles all schema types; `resolveEnumName` (when provided) takes precedence
-   * for `enum` nodes, enabling a separate naming strategy for enums (e.g. different suffix).
-   *
-   * Collision-resolved names (from `nameMapping`) are applied before user-supplied resolvers.
-   */
-  function resolveRefs(node: SchemaNode, resolveName: (ref: string) => string | undefined, resolveEnumName?: (name: string) => string | undefined): SchemaNode {
-    return transform(node, {
-      schema(schemaNode) {
-        const schemaRef = narrowSchema(schemaNode, schemaTypes.ref)
-
-        if (schemaRef && (schemaRef.ref || schemaRef.name)) {
-          const rawRef = schemaRef.ref ?? schemaRef.name!
-          const resolved = resolveName(nameMapping.get(rawRef) ?? rawRef)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
-
-        if (schemaNode.type === 'enum' && schemaNode.name) {
-          const resolved = (resolveEnumName ?? resolveName)(schemaNode.name)
-          if (resolved) {
-            return { ...schemaNode, name: resolved }
-          }
-        }
-      },
-    }) as SchemaNode
-  }
+  const resolveRefs = (
+    node: SchemaNode,
+    resolveName: (ref: string) => string | undefined,
+    resolveEnumName?: (name: string) => string | undefined,
+  ): SchemaNode => resolveRefsNode({ node, nameMapping, resolveName, resolveEnumName })
 
   return {
     parse,