@kubb/plugin-ts 5.0.0-alpha.23 → 5.0.0-alpha.25

package/src/printers/printerTs.ts

@@ -1,6 +1,4 @@
-import { jsStringEscape, stringify } from '@internals/utils'
-import { isStringType, narrowSchema, schemaTypes } from '@kubb/ast'
-import type { ArraySchemaNode, SchemaNode } from '@kubb/ast/types'
+import { extractRefName, isStringType, narrowSchema, schemaTypes, syncSchemaRef } from '@kubb/ast'
 import type { PrinterFactoryOptions } from '@kubb/core'
 import { definePrinter } from '@kubb/core'
 import { safePrint } from '@kubb/fabric-core/parsers/typescript'
@@ -8,6 +6,7 @@ import type ts from 'typescript'
 import { ENUM_TYPES_WITH_KEY_SUFFIX, OPTIONAL_ADDS_QUESTION_TOKEN, OPTIONAL_ADDS_UNDEFINED } from '../constants.ts'
 import * as factory from '../factory.ts'
 import type { PluginTs, ResolverTs } from '../types.ts'
+import { buildPropertyJSDocComments } from '../utils.ts'
 
 type TsOptions = {
   /**
@@ -52,6 +51,12 @@ type TsOptions = {
    * Resolver used to transform raw schema names into valid TypeScript identifiers.
    */
   resolver: ResolverTs
+  /**
+   * Names of top-level schemas that are enums.
+   * When set, the `ref` handler uses the suffixed type name (e.g. `StatusKey`) for enum refs
+   * instead of the plain PascalCase name, so imports align with what the enum file actually exports.
+   */
+  enumSchemaNames?: Set<string>
 }
 
 /**
@@ -59,140 +64,6 @@ type TsOptions = {
  */
 type TsPrinter = PrinterFactoryOptions<'typescript', TsOptions, ts.TypeNode, string>
 
-/**
- * Converts a primitive const value to a TypeScript literal type node.
- * Handles negative numbers via a prefix unary expression.
- */
-function constToTypeNode(value: string | number | boolean, format: 'string' | 'number' | 'boolean'): ts.TypeNode | undefined {
-  if (format === 'boolean') {
-    return factory.createLiteralTypeNode(value === true ? factory.createTrue() : factory.createFalse())
-  }
-  if (format === 'number' && typeof value === 'number') {
-    if (value < 0) {
-      return factory.createLiteralTypeNode(factory.createPrefixUnaryExpression(factory.SyntaxKind.MinusToken, factory.createNumericLiteral(Math.abs(value))))
-    }
-    return factory.createLiteralTypeNode(factory.createNumericLiteral(value))
-  }
-  return factory.createLiteralTypeNode(factory.createStringLiteral(String(value)))
-}
-
-/**
- * Returns a `Date` reference type node when `representation` is `'date'`, otherwise falls back to `string`.
- */
-function dateOrStringNode(node: { representation?: string }): ts.TypeNode {
-  return node.representation === 'date' ? factory.createTypeReferenceNode(factory.createIdentifier('Date')) : factory.keywordTypeNodes.string
-}
-
-/**
- * Maps an array of `SchemaNode`s through the printer, filtering out `null` and `undefined` results.
- */
-function buildMemberNodes(members: Array<SchemaNode> | undefined, print: (node: SchemaNode) => ts.TypeNode | null | undefined): Array<ts.TypeNode> {
-  return (members ?? []).map(print).filter(Boolean)
-}
-
-/**
- * Builds a TypeScript tuple type node from an array schema's `items`,
- * applying min/max slice and optional/rest element rules.
- */
-function buildTupleNode(node: ArraySchemaNode, print: (node: SchemaNode) => ts.TypeNode | null | undefined): ts.TypeNode | undefined {
-  let items = (node.items ?? []).map(print).filter(Boolean)
-
-  const restNode = node.rest ? (print(node.rest) ?? undefined) : undefined
-  const { min, max } = node
-
-  if (max !== undefined) {
-    items = items.slice(0, max)
-    if (items.length < max && restNode) {
-      items = [...items, ...Array(max - items.length).fill(restNode)]
-    }
-  }
-
-  if (min !== undefined) {
-    items = items.map((item, i) => (i >= min ? factory.createOptionalTypeNode(item) : item))
-  }
-
-  if (max === undefined && restNode) {
-    items.push(factory.createRestTypeNode(factory.createArrayTypeNode(restNode)))
-  }
-
-  return factory.createTupleTypeNode(items)
-}
-
-/**
- * Applies `nullable` and optional/nullish `| undefined` union modifiers to a property's resolved base type.
- */
-function buildPropertyType(schema: SchemaNode, baseType: ts.TypeNode, optionalType: TsOptions['optionalType']): ts.TypeNode {
-  const addsUndefined = OPTIONAL_ADDS_UNDEFINED.has(optionalType)
-
-  let type = baseType
-
-  if (schema.nullable) {
-    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
-  }
-
-  if ((schema.nullish || schema.optional) && addsUndefined) {
-    type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
-  }
-
-  return type
-}
-
-/**
- * Collects JSDoc annotation strings (description, deprecated, min/max, pattern, default, example, type) for a schema node.
- */
-function buildPropertyJSDocComments(schema: SchemaNode): Array<string | undefined> {
-  const isArray = schema.type === 'array'
-
-  return [
-    'description' in schema && schema.description ? `@description ${jsStringEscape(schema.description)}` : undefined,
-    'deprecated' in schema && schema.deprecated ? '@deprecated' : undefined,
-    // minItems/maxItems on arrays should not be emitted as @minLength/@maxLength
-    !isArray && 'min' in schema && schema.min !== undefined ? `@minLength ${schema.min}` : undefined,
-    !isArray && 'max' in schema && schema.max !== undefined ? `@maxLength ${schema.max}` : undefined,
-    'pattern' in schema && schema.pattern ? `@pattern ${schema.pattern}` : undefined,
-    'default' in schema && schema.default !== undefined
-      ? `@default ${'primitive' in schema && schema.primitive === 'string' ? stringify(schema.default as string) : schema.default}`
-      : undefined,
-    'example' in schema && schema.example !== undefined ? `@example ${schema.example}` : undefined,
-    'primitive' in schema && schema.primitive
-      ? [`@type ${schema.primitive || 'unknown'}`, 'optional' in schema && schema.optional ? ' | undefined' : undefined].filter(Boolean).join('')
-      : undefined,
-  ]
-}
-
-/**
- * Creates TypeScript index signatures for `additionalProperties` and `patternProperties` on an object schema node.
- */
-function buildIndexSignatures(
-  node: { additionalProperties?: SchemaNode | boolean; patternProperties?: Record<string, SchemaNode> },
-  propertyCount: number,
-  print: (node: SchemaNode) => ts.TypeNode | null | undefined,
-): Array<ts.TypeElement> {
-  const elements: Array<ts.TypeElement> = []
-
-  if (node.additionalProperties && node.additionalProperties !== true) {
-    const additionalType = print(node.additionalProperties) ?? factory.keywordTypeNodes.unknown
-
-    elements.push(factory.createIndexSignature(propertyCount > 0 ? factory.keywordTypeNodes.unknown : additionalType))
-  } else if (node.additionalProperties === true) {
-    elements.push(factory.createIndexSignature(factory.keywordTypeNodes.unknown))
-  }
-
-  if (node.patternProperties) {
-    const first = Object.values(node.patternProperties)[0]
-    if (first) {
-      let patternType = print(first) ?? factory.keywordTypeNodes.unknown
-
-      if (first.nullable) {
-        patternType = factory.createUnionDeclaration({ nodes: [patternType, factory.keywordTypeNodes.null] })
-      }
-      elements.push(factory.createIndexSignature(patternType))
-    }
-  }
-
-  return elements
-}
-
 /**
  * TypeScript type printer built with `definePrinter`.
  *
@@ -239,12 +110,14 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         }
         return factory.keywordTypeNodes.string
       },
+      ipv4: () => factory.keywordTypeNodes.string,
+      ipv6: () => factory.keywordTypeNodes.string,
       datetime: () => factory.keywordTypeNodes.string,
       number: () => factory.keywordTypeNodes.number,
       integer: () => factory.keywordTypeNodes.number,
       bigint: () => factory.keywordTypeNodes.bigint,
-      date: dateOrStringNode,
-      time: dateOrStringNode,
+      date: factory.dateOrStringNode,
+      time: factory.dateOrStringNode,
       ref(node) {
         if (!node.name) {
           return undefined
@@ -253,8 +126,18 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         // Use the canonical name from the $ref path — node.name may have been overridden
         // (e.g. by single-member allOf flatten using the property-derived child name).
         // Inline refs (without $ref) from utils already carry resolved type names.
-        const refName = node.ref ? (node.ref.split('/').at(-1) ?? node.name) : node.name
-        const name = node.ref ? this.options.resolver.default(refName, 'type') : refName
+        const refName = node.ref ? (extractRefName(node.ref) ?? node.name) : node.name
+
+        // When a Key suffix is configured, enum refs must use the suffixed name (e.g. `StatusKey`)
+        // so the reference matches what the enum file actually exports.
+        const isEnumRef =
+          node.ref && ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix && this.options.enumSchemaNames?.has(refName)
+
+        const name = isEnumRef
+          ? this.options.resolver.resolveEnumKeyName({ name: refName }, this.options.enumTypeSuffix!)
+          : node.ref
+            ? this.options.resolver.default(refName, 'type')
+            : refName
 
         return factory.createTypeReferenceNode(name, undefined)
       },
@@ -263,8 +146,8 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
 
         if (this.options.enumType === 'inlineLiteral' || !node.name) {
           const literalNodes = values
-            .filter((v): v is string | number | boolean => v !== null)
-            .map((value) => constToTypeNode(value, typeof value as 'string' | 'number' | 'boolean'))
+            .filter((v): v is string | number | boolean => v !== null && v !== undefined)
+            .map((value) => factory.constToTypeNode(value, typeof value as 'string' | 'number' | 'boolean'))
             .filter(Boolean)
 
           return factory.createUnionDeclaration({ withParentheses: true, nodes: literalNodes }) ?? undefined
@@ -272,7 +155,7 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
 
         const resolvedName =
           ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix
-            ? this.options.resolver.resolveEnumKeyName(node as unknown as SchemaNode, this.options.enumTypeSuffix)
+            ? this.options.resolver.resolveEnumKeyName(node, this.options.enumTypeSuffix)
             : this.options.resolver.default(node.name, 'type')
 
         return factory.createTypeReferenceNode(resolvedName, undefined)
@@ -303,10 +186,10 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
           return factory.createUnionDeclaration({ withParentheses: true, nodes: memberNodes }) ?? undefined
         }
 
-        return factory.createUnionDeclaration({ withParentheses: true, nodes: buildMemberNodes(members, this.transform) }) ?? undefined
+        return factory.createUnionDeclaration({ withParentheses: true, nodes: factory.buildMemberNodes(members, this.transform) }) ?? undefined
       },
       intersection(node) {
-        return factory.createIntersectionDeclaration({ withParentheses: true, nodes: buildMemberNodes(node.members, this.transform) }) ?? undefined
+        return factory.createIntersectionDeclaration({ withParentheses: true, nodes: factory.buildMemberNodes(node.members, this.transform) }) ?? undefined
       },
       array(node) {
         const itemNodes = (node.items ?? []).map((item) => this.transform(item)).filter(Boolean)
@@ -314,7 +197,7 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         return factory.createArrayDeclaration({ nodes: itemNodes, arrayType: this.options.arrayType }) ?? undefined
       },
       tuple(node) {
-        return buildTupleNode(node, this.transform)
+        return factory.buildTupleNode(node, this.transform)
       },
       object(node) {
         const { transform, options } = this
@@ -323,19 +206,20 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
 
         const propertyNodes: Array<ts.TypeElement> = node.properties.map((prop) => {
           const baseType = transform(prop.schema) ?? factory.keywordTypeNodes.unknown
-          const type = buildPropertyType(prop.schema, baseType, options.optionalType)
+          const type = factory.buildPropertyType(prop.schema, baseType, options.optionalType)
+          const propMeta = syncSchemaRef(prop.schema)
 
           const propertyNode = factory.createPropertySignature({
             questionToken: prop.schema.optional || prop.schema.nullish ? addsQuestionToken : false,
             name: prop.name,
             type,
-            readOnly: prop.schema.readOnly,
+            readOnly: propMeta?.readOnly,
           })
 
           return factory.appendJSDocToNode({ node: propertyNode, comments: buildPropertyJSDocComments(prop.schema) })
         })
 
-        const allElements = [...propertyNodes, ...buildIndexSignatures(node, propertyNodes.length, transform)]
+        const allElements = [...propertyNodes, ...factory.buildIndexSignatures(node, propertyNodes.length, transform)]
 
         if (!allElements.length) {
           return factory.keywordTypeNodes.object
@@ -345,50 +229,50 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
       },
     },
     print(node) {
-      let type = this.transform(node)
+      const { name, syntaxType = 'type', description, keysToOmit } = this.options
 
-      if (!type) {
-        return null
-      }
+      let base = this.transform(node)
+      if (!base) return null
 
-      // Apply top-level nullable / optional union modifiers.
-      if (node.nullable) {
-        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.null] })
+      // For ref nodes, structural metadata lives on node.schema rather than the ref node itself.
+      const meta = syncSchemaRef(node)
+
+      // Without name, apply modifiers inline and return.
+      if (!name) {
+        if (meta.nullable) {
+          base = factory.createUnionDeclaration({ nodes: [base, factory.keywordTypeNodes.null] })
+        }
+        if ((meta.nullish || meta.optional) && addsUndefined) {
+          base = factory.createUnionDeclaration({ nodes: [base, factory.keywordTypeNodes.undefined] })
+        }
+        return safePrint(base)
       }
 
-      if ((node.nullish || node.optional) && addsUndefined) {
-        type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
+      // When keysToOmit is present, wrap with Omit first, then apply nullable/optional
+      // modifiers so they are not swallowed by NonNullable inside createOmitDeclaration.
+      let inner: ts.TypeNode = keysToOmit?.length ? factory.createOmitDeclaration({ keys: keysToOmit, type: base, nonNullable: true }) : base
+
+      if (meta.nullable) {
+        inner = factory.createUnionDeclaration({ nodes: [inner, factory.keywordTypeNodes.null] })
       }
 
-      // Without name, return the type node as-is (no declaration wrapping).
-      const { name, syntaxType = 'type', description, keysToOmit } = this.options
-      if (!name) {
-        return safePrint(type)
+      // For named type declarations (type aliases), optional/nullish always produces | undefined
+      // regardless of optionalType — the questionToken ? modifier only applies to object properties.
+      if (meta.nullish || meta.optional) {
+        inner = factory.createUnionDeclaration({ nodes: [inner, factory.keywordTypeNodes.undefined] })
       }
 
-      const useTypeGeneration = syntaxType === 'type' || type.kind === factory.syntaxKind.union || !!keysToOmit?.length
+      const useTypeGeneration = syntaxType === 'type' || inner.kind === factory.syntaxKind.union || !!keysToOmit?.length
 
       const typeNode = factory.createTypeDeclaration({
         name,
         isExportable: true,
-        type: keysToOmit?.length
-          ? factory.createOmitDeclaration({
-              keys: keysToOmit,
-              type,
-              nonNullable: true,
-            })
-          : type,
+        type: inner,
         syntax: useTypeGeneration ? 'type' : 'interface',
-        comments: [
-          node?.title ? jsStringEscape(node.title) : undefined,
-          description ? `@description ${jsStringEscape(description)}` : undefined,
-          node?.deprecated ? '@deprecated' : undefined,
-          node && 'min' in node && node.min !== undefined ? `@minLength ${node.min}` : undefined,
-          node && 'max' in node && node.max !== undefined ? `@maxLength ${node.max}` : undefined,
-          node && 'pattern' in node && node.pattern ? `@pattern ${node.pattern}` : undefined,
-          node?.default ? `@default ${node.default}` : undefined,
-          node?.example ? `@example ${node.example}` : undefined,
-        ],
+        comments: buildPropertyJSDocComments({
+          ...meta,
+          description,
+        }),
       })
 
       return safePrint(typeNode)

package/src/resolvers/resolverTs.ts

@@ -2,7 +2,7 @@ import { pascalCase } from '@internals/utils'
 import { defineResolver } from '@kubb/core'
 import type { PluginTs } from '../types.ts'
 
-function resolveName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string {
+function toTypeName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string {
   return pascalCase(name, { isFile: type === 'file' })
 }
 
@@ -28,7 +28,7 @@ export const resolverTs = defineResolver<PluginTs>(() => {
     name: 'default',
     pluginName: 'plugin-ts',
     default(name, type) {
-      return resolveName(name, type)
+      return toTypeName(name, type)
     },
     resolveName(name) {
       return this.default(name, 'function')

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { OperationParamsResolver } from '@kubb/ast'
-import type { OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from '@kubb/ast/types'
+import type { OperationNode, ParameterNode, StatusCode, Visitor } from '@kubb/ast/types'
 import type {
   CompatibilityPreset,
   Exclude,
@@ -35,7 +35,9 @@ export type ResolverTs = Resolver &
      * resolver.resolvePathName('list pets', 'file') // → 'ListPets'
      */
     resolvePathName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string
-    /** Resolves the request body type name (required on ResolverTs). */
+    /**
+     * Resolves the request body type name for an operation (required on ResolverTs).
+     */
     resolveDataName(node: OperationNode): string
 
     /**
@@ -76,7 +78,7 @@ export type ResolverTs = Resolver &
      * resolver.resolveEnumKeyName(node, 'Value') // → 'PetStatusValue'
      * resolver.resolveEnumKeyName(node, '')      // → 'PetStatus'
      */
-    resolveEnumKeyName(node: SchemaNode, enumTypeSuffix: string): string
+    resolveEnumKeyName(node: { name?: string | null }, enumTypeSuffix: string): string
     /**
      * Resolves the name for an operation's grouped path parameters type.
      *
@@ -100,6 +102,92 @@ export type ResolverTs = Resolver &
     resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string
   }
 
+type EnumKeyCasing = 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none'
+
+/**
+ * Discriminated union that ties `enumTypeSuffix` and `enumKeyCasing` to the enum types that actually use them.
+ *
+ * - `'asConst'` / `'asPascalConst'` — emit a `const` object; both `enumTypeSuffix` (type-alias suffix) and
+ *    `enumKeyCasing` (key formatting) are meaningful.
+ * - `'enum'` / `'constEnum'` — emit a TypeScript enum; `enumKeyCasing` applies to member names,
+ *    but there is no separate type alias so `enumTypeSuffix` is not used.
+ * - `'literal'` / `'inlineLiteral'` — emit only union literals; keys are discarded entirely,
+ *    so neither `enumTypeSuffix` nor `enumKeyCasing` have any effect.
+ */
+type EnumTypeOptions =
+  | {
+      /**
+       * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+       * - 'asConst' generates const objects with camelCase names and as const assertion.
+       * - 'asPascalConst' generates const objects with PascalCase names and as const assertion.
+       * @default 'asConst'
+       */
+      enumType?: 'asConst' | 'asPascalConst'
+      /**
+       * Suffix appended to the generated type alias name.
+       *
+       * Only affects the type alias — the const object name is unchanged.
+       *
+       * @default 'Key'
+       * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
+       */
+      enumTypeSuffix?: string
+      /**
+       * Choose the casing for enum key names.
+       * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
+       * - 'snakeCase' generates keys in snake_case format.
+       * - 'pascalCase' generates keys in PascalCase format.
+       * - 'camelCase' generates keys in camelCase format.
+       * - 'none' uses the enum value as-is without transformation.
+       * @default 'none'
+       */
+      enumKeyCasing?: EnumKeyCasing
+    }
+  | {
+      /**
+       * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+       * - 'enum' generates TypeScript enum declarations.
+       * - 'constEnum' generates TypeScript const enum declarations.
+       * @default 'asConst'
+       */
+      enumType?: 'enum' | 'constEnum'
+      /**
+       * `enumTypeSuffix` has no effect for this `enumType`.
+       * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+       */
+      enumTypeSuffix?: never
+      /**
+       * Choose the casing for enum key names.
+       * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
+       * - 'snakeCase' generates keys in snake_case format.
+       * - 'pascalCase' generates keys in PascalCase format.
+       * - 'camelCase' generates keys in camelCase format.
+       * - 'none' uses the enum value as-is without transformation.
+       * @default 'none'
+       */
+      enumKeyCasing?: EnumKeyCasing
+    }
+  | {
+      /**
+       * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
+       * - 'literal' generates literal union types.
+       * - 'inlineLiteral' will inline enum values directly into the type (default in v5).
+       * @default 'asConst'
+       * @note In Kubb v5, 'inlineLiteral' becomes the default.
+       */
+      enumType?: 'literal' | 'inlineLiteral'
+      /**
+       * `enumTypeSuffix` has no effect for this `enumType`.
+       * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+       */
+      enumTypeSuffix?: never
+      /**
+       * `enumKeyCasing` has no effect for this `enumType`.
+       * Literal and inlineLiteral modes emit only values — keys are discarded entirely.
+       */
+      enumKeyCasing?: never
+    }
+
 export type Options = {
   /**
    * Specify the export location for the files and define the behavior of the output
@@ -127,37 +215,6 @@ export type Options = {
    * Array containing override parameters to override `options` based on tags/operations/methods/paths.
    */
   override?: Array<Override<ResolvedOptions>>
-  /**
-   * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
-   * - 'enum' generates TypeScript enum declarations.
-   * - 'asConst' generates const objects with camelCase names and as const assertion.
-   * - 'asPascalConst' generates const objects with PascalCase names and as const assertion.
-   * - 'constEnum' generates TypeScript const enum declarations.
-   * - 'literal' generates literal union types.
-   * - 'inlineLiteral' inline enum values directly into the type (default in v5).
-   * @default 'asConst'
-   * @note In Kubb v5, 'inlineLiteral' becomes the default.
-   */
-  enumType?: 'enum' | 'asConst' | 'asPascalConst' | 'constEnum' | 'literal' | 'inlineLiteral'
-  /**
-   * Suffix appended to the generated type alias name when `enumType` is `asConst` or `asPascalConst`.
-   *
-   * Only affects the type alias — the const object name is unchanged.
-   *
-   * @default 'Key'
-   * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
-   */
-  enumTypeSuffix?: string
-  /**
-   * Choose the casing for enum key names.
-   * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
-   * - 'snakeCase' generates keys in snake_case format.
-   * - 'pascalCase' generates keys in PascalCase format.
-   * - 'camelCase' generates keys in camelCase format.
-   * - 'none' uses the enum value as-is without transformation.
-   * @default 'none'
-   */
-  enumKeyCasing?: 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none'
   /**
    * Switch between type or interface for creating TypeScript types.
    * - 'type' generates type alias declarations.
@@ -228,14 +285,14 @@ export type Options = {
    * ```
    */
   transformers?: Array<Visitor>
-}
+} & EnumTypeOptions
 
 type ResolvedOptions = {
   output: Output
   group: Group | undefined
   enumType: NonNullable<Options['enumType']>
   enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
-  enumKeyCasing: NonNullable<Options['enumKeyCasing']>
+  enumKeyCasing: EnumKeyCasing
   optionalType: NonNullable<Options['optionalType']>
   arrayType: NonNullable<Options['arrayType']>
   syntaxType: NonNullable<Options['syntaxType']>

package/src/utils.ts

@@ -1,19 +1,47 @@
-import { createProperty, createSchema } from '@kubb/ast'
+import { jsStringEscape, stringify } from '@internals/utils'
+import { createProperty, createSchema, syncSchemaRef } from '@kubb/ast'
 import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
 import type { ResolverTs } from './types.ts'
 
+/**
+ * Collects JSDoc annotation strings for a schema node.
+ *
+ * Only uses official JSDoc tags from https://jsdoc.app/: `@description`, `@deprecated`, `@default`, `@example`, `@type`.
+ * Constraint metadata (min/max length, pattern, multipleOf, min/maxProperties) is emitted as plain-text lines.
+
+ */
+export function buildPropertyJSDocComments(schema: SchemaNode): Array<string | undefined> {
+  const meta = syncSchemaRef(schema)
+
+  const isArray = meta?.primitive === 'array'
+
+  return [
+    meta && 'description' in meta && meta.description ? `@description ${jsStringEscape(meta.description)}` : undefined,
+    meta && 'deprecated' in meta && meta.deprecated ? '@deprecated' : undefined,
+    // minItems/maxItems on arrays should not be emitted as @minLength/@maxLength
+    !isArray && meta && 'min' in meta && meta.min !== undefined ? `@minLength ${meta.min}` : undefined,
+    !isArray && meta && 'max' in meta && meta.max !== undefined ? `@maxLength ${meta.max}` : undefined,
+    meta && 'pattern' in meta && meta.pattern ? `@pattern ${meta.pattern}` : undefined,
+    meta && 'default' in meta && meta.default !== undefined
+      ? `@default ${'primitive' in meta && meta.primitive === 'string' ? stringify(meta.default as string) : meta.default}`
+      : undefined,
+    meta && 'example' in meta && meta.example !== undefined ? `@example ${meta.example}` : undefined,
+    meta && 'primitive' in meta && meta.primitive
+      ? [`@type ${meta.primitive}`, 'optional' in schema && schema.optional ? ' | undefined' : undefined].filter(Boolean).join('')
+      : undefined,
+  ].filter(Boolean)
+}
+
 type BuildParamsSchemaOptions = {
   params: Array<ParameterNode>
-  node: OperationNode
   resolver: ResolverTs
 }
 
 type BuildOperationSchemaOptions = {
-  node: OperationNode
   resolver: ResolverTs
 }
 
-export function buildParams({ params, node, resolver }: BuildParamsSchemaOptions): SchemaNode {
+export function buildParams(node: OperationNode, { params, resolver }: BuildParamsSchemaOptions): SchemaNode {
   return createSchema({
     type: 'object',
     properties: params.map((param) =>
@@ -29,7 +57,7 @@ export function buildParams({ params, node, resolver }: BuildParamsSchemaOptions
   })
 }
 
-export function buildData({ node, resolver }: BuildOperationSchemaOptions): SchemaNode {
+export function buildData(node: OperationNode, { resolver }: BuildOperationSchemaOptions): SchemaNode {
   const pathParams = node.parameters.filter((p) => p.in === 'path')
   const queryParams = node.parameters.filter((p) => p.in === 'query')
   const headerParams = node.parameters.filter((p) => p.in === 'header')
@@ -42,26 +70,26 @@ export function buildData({ node, resolver }: BuildOperationSchemaOptions): Sche
         name: 'data',
         schema: node.requestBody?.schema
           ? createSchema({ type: 'ref', name: resolver.resolveDataName(node), optional: true })
-          : createSchema({ type: 'never', optional: true }),
+          : createSchema({ type: 'never', primitive: undefined, optional: true }),
       }),
       createProperty({
         name: 'pathParams',
         required: pathParams.length > 0,
-        schema: pathParams.length > 0 ? buildParams({ params: pathParams, node, resolver }) : createSchema({ type: 'never' }),
+        schema: pathParams.length > 0 ? buildParams(node, { params: pathParams, resolver }) : createSchema({ type: 'never', primitive: undefined }),
       }),
       createProperty({
         name: 'queryParams',
         schema:
           queryParams.length > 0
-            ? createSchema({ ...buildParams({ params: queryParams, node, resolver }), optional: true })
-            : createSchema({ type: 'never', optional: true }),
+            ? createSchema({ ...buildParams(node, { params: queryParams, resolver }), optional: true })
+            : createSchema({ type: 'never', primitive: undefined, optional: true }),
       }),
       createProperty({
         name: 'headerParams',
         schema:
           headerParams.length > 0
-            ? createSchema({ ...buildParams({ params: headerParams, node, resolver }), optional: true })
-            : createSchema({ type: 'never', optional: true }),
+            ? createSchema({ ...buildParams(node, { params: headerParams, resolver }), optional: true })
+            : createSchema({ type: 'never', primitive: undefined, optional: true }),
       }),
       createProperty({
         name: 'url',
@@ -72,7 +100,7 @@ export function buildData({ node, resolver }: BuildOperationSchemaOptions): Sche
   })
 }
 
-export function buildResponses({ node, resolver }: BuildOperationSchemaOptions): SchemaNode | null {
+export function buildResponses(node: OperationNode, { resolver }: BuildOperationSchemaOptions): SchemaNode | null {
   if (node.responses.length === 0) {
     return null
   }
@@ -89,7 +117,7 @@ export function buildResponses({ node, resolver }: BuildOperationSchemaOptions):
   })
 }
 
-export function buildResponseUnion({ node, resolver }: BuildOperationSchemaOptions): SchemaNode | null {
+export function buildResponseUnion(node: OperationNode, { resolver }: BuildOperationSchemaOptions): SchemaNode | null {
   const responsesWithSchema = node.responses.filter((res) => res.schema)
 
   if (responsesWithSchema.length === 0) {