@kubb/plugin-ts 5.0.0-beta.4 → 5.0.0-beta.56

package/src/resolvers/resolverTs.ts

@@ -1,66 +1,69 @@
-import { pascalCase } from '@internals/utils'
+import { ensureValidVarName, pascalCase, toFilePath } from '@internals/utils'
 import { defineResolver } from '@kubb/core'
 import type { PluginTs } from '../types.ts'
 
 /**
- * Resolver for `@kubb/plugin-ts` that provides the default naming and path-resolution
- * helpers used by the plugin. Import this in other plugins to resolve the exact names and
- * paths that `plugin-ts` generates without hardcoding the conventions.
+ * Default resolver used by `@kubb/plugin-ts`. Decides the names and file paths
+ * for every generated TypeScript type. Import this in other plugins that need
+ * to reference the exact names `plugin-ts` produces without duplicating the
+ * casing/file-layout rules.
  *
- * The `default` method is automatically injected by `defineResolver` — it uses `camelCase`
- * for identifiers/files and `pascalCase` for type names.
+ * The `default` method is supplied by `defineResolver`. It uses PascalCase for
+ * type names and PascalCase file paths (dotted names become `/`-joined) for files.
  *
- * @example
+ * @example Resolve a type and file name
  * ```ts
- * import { resolver } from '@kubb/plugin-ts'
+ * import { resolverTs } from '@kubb/plugin-ts'
  *
- * resolver.default('list pets', 'type')              // → 'ListPets'
- * resolver.resolveName('list pets status 200')        // → 'ListPetsStatus200'
- * resolver.resolvePathName('list pets', 'file')       // → 'listPets'
+ * resolverTs.default('list pets', 'type')        // 'ListPets'
+ * resolverTs.resolvePathName('list pets', 'file') // 'ListPets'
+ * resolverTs.resolveResponseStatusName(node, 200) // 'ListPetsStatus200'
  * ```
  */
-export const resolverTs = defineResolver<PluginTs>((ctx) => {
+export const resolverTs = defineResolver<PluginTs>(() => {
   return {
     name: 'default',
     pluginName: 'plugin-ts',
     default(name, type) {
-      return pascalCase(name, { isFile: type === 'file' })
+      if (type === 'file') return toFilePath(name, pascalCase)
+      return ensureValidVarName(pascalCase(name))
     },
     resolveTypeName(name) {
-      return pascalCase(name)
+      return ensureValidVarName(pascalCase(name))
     },
     resolvePathName(name, type) {
-      return pascalCase(name, { isFile: type === 'file' })
+      if (type === 'file') return toFilePath(name, pascalCase)
+      return ensureValidVarName(pascalCase(name))
     },
     resolveParamName(node, param) {
-      return ctx.resolveTypeName(`${node.operationId} ${param.in} ${param.name}`)
+      return this.resolveTypeName(`${node.operationId} ${param.in} ${param.name}`)
     },
     resolveResponseStatusName(node, statusCode) {
-      return ctx.resolveTypeName(`${node.operationId} Status ${statusCode}`)
+      return this.resolveTypeName(`${node.operationId} Status ${statusCode}`)
     },
     resolveDataName(node) {
-      return ctx.resolveTypeName(`${node.operationId} Data`)
+      return this.resolveTypeName(`${node.operationId} Data`)
     },
     resolveRequestConfigName(node) {
-      return ctx.resolveTypeName(`${node.operationId} RequestConfig`)
+      return this.resolveTypeName(`${node.operationId} RequestConfig`)
     },
     resolveResponsesName(node) {
-      return ctx.resolveTypeName(`${node.operationId} Responses`)
+      return this.resolveTypeName(`${node.operationId} Responses`)
     },
     resolveResponseName(node) {
-      return ctx.resolveTypeName(`${node.operationId} Response`)
+      return this.resolveTypeName(`${node.operationId} Response`)
     },
     resolveEnumKeyName(node, enumTypeSuffix = 'key') {
-      return `${ctx.resolveTypeName(node.name ?? '')}${enumTypeSuffix}`
+      return `${this.resolveTypeName(node.name ?? '')}${enumTypeSuffix}`
     },
     resolvePathParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
     resolveQueryParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
     resolveHeaderParamsName(node, param) {
-      return ctx.resolveParamName(node, param)
+      return this.resolveParamName(node, param)
     },
   }
 })

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
+import type { ast, Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver } from '@kubb/core'
 import type { PrinterTsNodes } from './printers/printerTs.ts'
 /**
  * The concrete resolver type for `@kubb/plugin-ts`.
@@ -93,34 +93,49 @@ export type ResolverTs = Resolver &
 
 type EnumKeyCasing = 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none'
 
+type EnumConstCasing = 'camelCase' | 'pascalCase'
+
 /**
- * Discriminated union that ties `enumTypeSuffix` and `enumKeyCasing` to the enum types that actually use them.
+ * Grouped enum settings. Each `type` uses only some of the other fields.
+ *
+ * - `'asConst'` emits a `const` object plus a `typeof` type alias, so `constCasing`, `typeSuffix`, and `keyCasing` all apply.
+ * - `'enum'` and `'constEnum'` emit a TypeScript enum, so only `keyCasing` (the member names) applies.
+ * - `'literal'` and `'inlineLiteral'` emit union literals and drop the keys, so none of the other fields apply.
  *
- * - `'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.
+ * @example Share one name between the const and the type
+ * ```ts
+ * enum: { type: 'asConst', constCasing: 'pascalCase', typeSuffix: '' }
+ * // export const VehicleType = { … } as const
+ * // export type VehicleType = (typeof VehicleType)[keyof typeof VehicleType]
+ * ```
  */
-type EnumTypeOptions =
+type EnumOptions =
   | {
       /**
-       * 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.
+       * Emit a `const` object asserted with `as const`, paired with a `typeof` type alias.
+       * This is tree-shakeable and adds no enum runtime.
+       *
        * @default 'asConst'
        */
-      enumType?: 'asConst' | 'asPascalConst'
+      type?: 'asConst'
       /**
-       * Suffix appended to the generated type alias name.
+       * Casing of the generated const variable.
+       * - 'camelCase' names the const `vehicleType`.
+       * - 'pascalCase' names the const `VehicleType`, matching the schema name.
        *
-       * Only affects the type alias — the const object name is unchanged.
+       * @default 'camelCase'
+       */
+      constCasing?: EnumConstCasing
+      /**
+       * Suffix appended to the generated type alias name. Only the type alias is renamed. The const
+       * object name stays the same. Set it to `''` together with `constCasing: 'pascalCase'` to merge
+       * the const and type under the schema's exact name.
        *
        * @default 'Key'
-       * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
+       * @example A custom suffix
+       * `typeSuffix: 'Value'` renames the alias to `PetStatusValue`
        */
-      enumTypeSuffix?: string
+      typeSuffix?: string
       /**
        * Choose the casing for enum key names.
        * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
@@ -130,23 +145,25 @@ type EnumTypeOptions =
        * - 'none' uses the enum value as-is without transformation.
        * @default 'none'
        */
-      enumKeyCasing?: EnumKeyCasing
+      keyCasing?: EnumKeyCasing
     }
   | {
       /**
-       * Choose to use enum, asConst, asPascalConst, constEnum, literal, or inlineLiteral for enums.
-       * - 'enum' generates TypeScript enum declarations.
-       * - 'constEnum' generates TypeScript const enum declarations.
+       * Emit a TypeScript `enum` (`'enum'`) or `const enum` (`'constEnum'`) declaration.
+       *
        * @default 'asConst'
        */
-      enumType?: 'enum' | 'constEnum'
+      type?: 'enum' | 'constEnum'
       /**
-       * `enumTypeSuffix` has no effect for this `enumType`.
-       * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+       * `constCasing` has no effect for this `type`. Only `'asConst'` emits a const object.
        */
-      enumTypeSuffix?: never
+      constCasing?: never
       /**
-       * Choose the casing for enum key names.
+       * `typeSuffix` has no effect for this `type`. Only `'asConst'` emits a separate type alias.
+       */
+      typeSuffix?: never
+      /**
+       * Choose the casing for enum member names.
        * - 'screamingSnakeCase' generates keys in SCREAMING_SNAKE_CASE format.
        * - 'snakeCase' generates keys in snake_case format.
        * - 'pascalCase' generates keys in PascalCase format.
@@ -154,99 +171,101 @@ type EnumTypeOptions =
        * - 'none' uses the enum value as-is without transformation.
        * @default 'none'
        */
-      enumKeyCasing?: EnumKeyCasing
+      keyCasing?: 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).
+       * Emit a union of literals as a named alias (`'literal'`) or inline the union at every usage
+       * site (`'inlineLiteral'`).
+       *
        * @default 'asConst'
        * @note In Kubb v5, 'inlineLiteral' becomes the default.
        */
-      enumType?: 'literal' | 'inlineLiteral'
+      type?: 'literal' | 'inlineLiteral'
+      /**
+       * `constCasing` has no effect for this `type`; literal modes emit no const object.
+       */
+      constCasing?: never
       /**
-       * `enumTypeSuffix` has no effect for this `enumType`.
-       * It is only used when `enumType` is `'asConst'` or `'asPascalConst'`.
+       * `typeSuffix` has no effect for this `type`; literal modes emit no separate type alias.
        */
-      enumTypeSuffix?: never
+      typeSuffix?: never
       /**
-       * `enumKeyCasing` has no effect for this `enumType`.
-       * Literal and inlineLiteral modes emit only values — keys are discarded entirely.
+       * `keyCasing` has no effect for this `type`. Literal and inlineLiteral modes emit only values,
+       * so the keys are discarded.
        */
-      enumKeyCasing?: never
+      keyCasing?: never
     }
 
-export type Options = {
-  /**
-   * Specify the export location for the files and define the behavior of the output
-   * @default { path: 'types', barrelType: 'named' }
-   */
-  output?: Output
-  /**
-   * Define which contentType should be used.
-   * By default, uses the first valid JSON media type.
-   */
-  contentType?: 'application/json' | (string & {})
-  /**
-   * Group the clients based on the provided name.
-   */
-  group?: Group
+/**
+ * Where the generated `.ts` files are written and how they are exported, plus the optional
+ * `group` strategy. The `group` option organizes `output.mode: 'directory'` output into per-tag or per-path subdirectories.
+ *
+ * @default { path: 'types', barrel: { type: 'named' } }
+ */
+export type Options = OutputOptions & {
   /**
-   * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
+   * Skip operations matching at least one entry in the list.
    */
   exclude?: Array<Exclude>
   /**
-   * Array containing include parameters to include tags/operations/methods/paths.
+   * Restrict generation to operations matching at least one entry in the list.
    */
   include?: Array<Include>
   /**
-   * Array containing override parameters to override `options` based on tags/operations/methods/paths.
+   * Apply a different options object to operations matching a pattern.
    */
   override?: Array<Override<ResolvedOptions>>
   /**
-   * Switch between type or interface for creating TypeScript types.
-   * - 'type' generates type alias declarations.
-   * - 'interface' generates interface declarations.
+   * Whether object schemas are emitted as `type` aliases or `interface` declarations.
+   * - `'type'` emits closed type aliases. Safer default for generated code.
+   * - `'interface'` emits interfaces. Useful when consumers rely on declaration merging.
+   *
    * @default 'type'
+   * @see https://www.totaltypescript.com/type-vs-interface-which-should-you-use
    */
   syntaxType?: 'type' | 'interface'
   /**
-   * Choose what to use as mode for an optional value.
-   * - 'questionToken' marks the property as optional with ? (e.g., type?: string).
-   * - 'undefined' adds undefined to the type union (e.g., type: string | undefined).
-   * - 'questionTokenAndUndefined' combines both approaches (e.g., type?: string | undefined).
+   * How optional properties are written in generated types.
+   * - `'questionToken'` — `type?: string`. The property may be missing.
+   * - `'undefined'` — `type: string | undefined`. Required to exist, may be `undefined`.
+   * - `'questionTokenAndUndefined'` — `type?: string | undefined`. Strictest.
+   *
    * @default 'questionToken'
+   * @note Pick `'questionTokenAndUndefined'` when `exactOptionalPropertyTypes` is on in `tsconfig.json`.
    */
   optionalType?: 'questionToken' | 'undefined' | 'questionTokenAndUndefined'
   /**
-   * Choose between Array<string> or string[] for array types.
-   * - 'generic' generates Array<Type> syntax.
-   * - 'array' generates Type[] syntax.
+   * Syntax used for array types.
+   * - `'array'` — `Type[]`. Shorter.
+   * - `'generic'` — `Array<Type>`. More readable for complex element types.
+   *
    * @default 'array'
    */
   arrayType?: 'generic' | 'array'
   /**
-   * How to style your params, by default no casing is applied
-   * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
-   * @default undefined
-   * @note response types (data/body) are NOT affected by this option
+   * Rename properties inside `PathParams`, `QueryParams`, and `HeaderParams` types.
+   * Response and request body types are not affected.
+   *
+   * @note Every plugin that touches operation parameters must use the same value.
    */
   paramsCasing?: 'camelcase'
   /**
-   * Define some generators next to the ts generators
+   * Custom generators that run alongside the built-in TypeScript generators.
    */
   generators?: Array<Generator<PluginTs>>
   /**
-   * Override naming conventions. When a method returns `null` or `undefined`, the preset
-   * resolver (`resolverTs`) is used as fallback.
+   * Override how names and file paths are built for generated symbols.
+   * Methods you omit fall back to the default `resolverTs`. `this` is bound to the
+   * full resolver, so `this.default(name, 'function')` delegates to the built-in
+   * implementation.
    */
   resolver?: Partial<ResolverTs> & ThisType<ResolverTs>
   /**
-   * AST visitor applied to each schema/operation node before printing.
-   * Returning `null` or `undefined` from a visitor method falls back to the preset transformer.
+   * AST visitor applied to each schema or operation node before printing.
+   * Methods you omit fall back to the preset transformer.
    *
-   * @example Remove writeOnly properties from response types
+   * @example Drop writeOnly properties from response types
    * ```ts
    * transformer: {
    *   property(node) {
@@ -257,18 +276,17 @@ export type Options = {
    */
   transformer?: ast.Visitor
   /**
-   * Override individual printer node handlers to customize rendering of specific schema types.
-   *
-   * Each key is a `SchemaType` (e.g. `'date'`, `'string'`). The function replaces the
-   * built-in handler for that type. Use `this.transform` to recurse into nested schema nodes.
+   * Replace the TypeScript handler for a specific schema type (`'integer'`, `'date'`, ...).
+   * Each handler returns a TypeScript AST node for that schema type. Use `this.transform`
+   * to recurse into nested schema nodes.
    *
-   * @example Override the `date` node to use the `Date` object type
+   * @example Use the JavaScript `Date` object for date schemas
    * ```ts
    * import ts from 'typescript'
    * pluginTs({
    *   printer: {
    *     nodes: {
-   *       date(node) {
+   *       date() {
    *         return ts.factory.createTypeReferenceNode('Date', [])
    *       },
    *     },
@@ -279,17 +297,26 @@ export type Options = {
   printer?: {
     nodes?: PrinterTsNodes
   }
-} & EnumTypeOptions
+  /**
+   * How OpenAPI enums are represented in the generated TypeScript, and how their names are cased.
+   */
+  enum?: EnumOptions
+}
+
+type ResolvedEnumOptions = {
+  type: NonNullable<EnumOptions['type']>
+  constCasing: EnumConstCasing
+  typeSuffix: string
+  keyCasing: EnumKeyCasing
+}
 
 type ResolvedOptions = {
   output: Output
   exclude: Array<Exclude>
   include: Array<Include> | undefined
   override: Array<Override<ResolvedOptions>>
-  group: Group | undefined
-  enumType: NonNullable<Options['enumType']>
-  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
-  enumKeyCasing: EnumKeyCasing
+  group: Group | null
+  enum: ResolvedEnumOptions
   optionalType: NonNullable<Options['optionalType']>
   arrayType: NonNullable<Options['arrayType']>
   syntaxType: NonNullable<Options['syntaxType']>

package/src/utils.ts

@@ -1,4 +1,5 @@
-import { jsStringEscape, stringify } from '@internals/utils'
+import { jsStringEscape, stringify } from '@kubb/ast/utils'
+import { getOperationParameters } from '@internals/shared'
 import { ast } from '@kubb/core'
 import type { ResolverTs } from './types.ts'
 
@@ -14,20 +15,31 @@ export function buildPropertyJSDocComments(schema: ast.SchemaNode): Array<string
 
   const isArray = meta?.primitive === 'array'
 
+  const hasDescription = meta && 'description' in meta && meta.description
+
+  const formatComment =
+    meta && 'format' in meta && meta.format
+      ? hasDescription
+        ? // Empty line between description and format
+          [' ', `Format: \`${meta.format}\``]
+        : ['@description', `Format: \`${meta.format}\``]
+      : []
+
   return [
-    meta && 'description' in meta && meta.description ? `@description ${jsStringEscape(meta.description)}` : undefined,
-    meta && 'deprecated' in meta && meta.deprecated ? '@deprecated' : undefined,
+    hasDescription ? `@description ${jsStringEscape(meta.description)}` : null,
+    ...formatComment,
+    meta && 'deprecated' in meta && meta.deprecated ? '@deprecated' : null,
     // 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,
+    !isArray && meta && 'min' in meta && meta.min !== undefined ? `@minLength ${meta.min}` : null,
+    !isArray && meta && 'max' in meta && meta.max !== undefined ? `@maxLength ${meta.max}` : null,
+    meta && 'pattern' in meta && meta.pattern ? `@pattern ${meta.pattern}` : null,
     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,
+      : null,
+    meta && 'example' in meta && meta.example !== undefined ? `@example ${meta.example}` : null,
     meta && 'primitive' in meta && meta.primitive
-      ? [`@type ${meta.primitive}`, 'optional' in schema && schema.optional ? ' | undefined' : undefined].filter(Boolean).join('')
-      : undefined,
+      ? [`@type ${meta.primitive}`, 'optional' in schema && schema.optional ? ' | undefined' : null].filter(Boolean).join('')
+      : null,
   ].filter(Boolean)
 }
 
@@ -57,9 +69,7 @@ export function buildParams(node: ast.OperationNode, { params, resolver }: Build
 }
 
 export function buildData(node: ast.OperationNode, { resolver }: BuildOperationSchemaOptions): ast.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')
+  const { path: pathParams, query: queryParams, header: headerParams } = getOperationParameters(node)
 
   return ast.createSchema({
     type: 'object',
@@ -117,7 +127,7 @@ export function buildResponses(node: ast.OperationNode, { resolver }: BuildOpera
 }
 
 export function buildResponseUnion(node: ast.OperationNode, { resolver }: BuildOperationSchemaOptions): ast.SchemaNode | null {
-  const responsesWithSchema = node.responses.filter((res) => res.schema)
+  const responsesWithSchema = node.responses.filter((res) => res.content?.some((entry) => entry.schema))
 
   if (responsesWithSchema.length === 0) {
     return null