@kubb/plugin-ts 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/types.ts

@@ -1,24 +1,209 @@
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams } from '@kubb/core'
-import type { contentType, Oas } from '@kubb/oas'
-import type { Exclude, Include, Override, ResolvePathOptions } from '@kubb/plugin-oas'
-import type { Generator } from '@kubb/plugin-oas/generators'
-import type ts from 'typescript'
+import type { OperationParamsResolver } from '@kubb/ast'
+import type { OperationNode, ParameterNode, StatusCode, Visitor } from '@kubb/ast/types'
+import type {
+  CompatibilityPreset,
+  Exclude,
+  Generator,
+  Group,
+  Include,
+  Output,
+  Override,
+  PluginFactoryOptions,
+  ResolvePathOptions,
+  Resolver,
+  UserGroup,
+} from '@kubb/core'
+import type { PrinterTsNodes } from './printers/printerTs.ts'
+/**
+ * The concrete resolver type for `@kubb/plugin-ts`.
+ * Extends the base `Resolver` (which provides `default` and `resolveOptions`) with
+ * plugin-specific naming helpers for operations, parameters, responses, and schemas.
+ */
+export type ResolverTs = Resolver &
+  OperationParamsResolver & {
+    /**
+     * Resolves the name for a given raw name (equivalent to `default(name, 'function')`).
+     * Since TypeScript only emits types, this is the canonical naming method.
+     *
+     * @example
+     * resolver.resolveName('list pets status 200') // → 'ListPetsStatus200'
+     */
+    resolveTypeName(name: string): string
+    /**
+     * Resolves the file/path name for a given identifier using PascalCase.
+     *
+     * @example
+     * resolver.resolvePathName('list pets', 'file') // → 'ListPets'
+     */
+    resolvePathName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string
+    /**
+     * Resolves the request body type name for an operation (required on ResolverTs).
+     */
+    resolveDataName(node: OperationNode): string
+
+    /**
+     * Resolves the name for an operation response by status code.
+     * Encapsulates the `<operationId> Status <statusCode>` template with PascalCase applied to the result.
+     *
+     * @example
+     * resolver.resolveResponseStatusName(node, 200) // → 'ListPetsStatus200'
+     */
+    resolveResponseStatusName(node: OperationNode, statusCode: StatusCode): string
+    /**
+     * Resolves the name for an operation's request config (`RequestConfig`).
+     *
+     * @example
+     * resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'
+     */
+    resolveRequestConfigName(node: OperationNode): string
+    /**
+     * Resolves the name for the collection of all operation responses (`Responses`).
+     *
+     * @example
+     * resolver.resolveResponsesName(node) // → 'ListPetsResponses'
+     */
+    resolveResponsesName(node: OperationNode): string
+    /**
+     * Resolves the name for the union of all operation responses (`Response`).
+     *
+     * @example
+     * resolver.resolveResponseName(node) // → 'ListPetsResponse'
+     */
+    resolveResponseName(node: OperationNode): string
+    /**
+     * Resolves the TypeScript type alias name for an enum schema's key variant.
+     * Appends `enumTypeSuffix` (default `'Key'`) after applying the default naming convention.
+     *
+     * @example
+     * resolver.resolveEnumKeyName(node, 'Key')   // → 'PetStatusKey'
+     * resolver.resolveEnumKeyName(node, 'Value') // → 'PetStatusValue'
+     * resolver.resolveEnumKeyName(node, '')      // → 'PetStatus'
+     */
+    resolveEnumKeyName(node: { name?: string | null }, enumTypeSuffix: string): string
+    /**
+     * Resolves the name for an operation's grouped path parameters type.
+     *
+     * @example
+     * resolver.resolvePathParamsName(node, param) // → 'GetPetByIdPathParams'
+     */
+    resolvePathParamsName(node: OperationNode, param: ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped query parameters type.
+     *
+     * @example
+     * resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'
+     */
+    resolveQueryParamsName(node: OperationNode, param: ParameterNode): string
+    /**
+     * Resolves the name for an operation's grouped header parameters type.
+     *
+     * @example
+     * resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'
+     */
+    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
    * @default { path: 'types', barrelType: 'named' }
    */
-  output?: Output<Oas>
+  output?: Output
   /**
    * Define which contentType should be used.
    * By default, uses the first valid JSON media type.
    */
-  contentType?: contentType
+  contentType?: 'application/json' | (string & {})
   /**
    * Group the clients based on the provided name.
    */
-  group?: Group
+  group?: UserGroup
   /**
    * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
    */
@@ -31,28 +216,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'
-  /**
-   * 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.
@@ -60,42 +223,6 @@ export type Options = {
    * @default 'type'
    */
   syntaxType?: 'type' | 'interface'
-  /**
-   * Set a suffix for the generated enums.
-   * @default 'enum'
-   */
-  enumSuffix?: string
-  /**
-   * Choose to use date or datetime as JavaScript Date instead of string.
-   * - 'string' represents dates as string values.
-   * - 'date' represents dates as JavaScript Date objects.
-   * @default 'string'
-   */
-  dateType?: 'string' | 'date'
-  /**
-   * Choose to use `number` or `bigint` for integer fields with `int64` format.
-   * - 'number' uses the TypeScript `number` type (matches JSON.parse() runtime behavior).
-   * - 'bigint' uses the TypeScript `bigint` type (accurate for values exceeding Number.MAX_SAFE_INTEGER).
-   * @note in v5 of Kubb 'bigint' will become the default to better align with OpenAPI's int64 specification.
-   * @default 'number'
-   */
-  integerType?: 'number' | 'bigint'
-  /**
-   * Which type to use when the Swagger/OpenAPI file is not providing more information.
-   * - 'any' allows any value.
-   * - 'unknown' requires type narrowing before use.
-   * - 'void' represents no value.
-   * @default 'any'
-   */
-  unknownType?: 'any' | 'unknown' | 'void'
-  /**
-   * Which type to use for empty schema values.
-   * - 'any' allows any value.
-   * - 'unknown' requires type narrowing before use.
-   * - 'void' represents no value.
-   * @default `unknownType`
-   */
-  emptySchemaType?: 'any' | 'unknown' | 'void'
   /**
    * Choose what to use as mode for an optional value.
    * - 'questionToken' marks the property as optional with ? (e.g., type?: string).
@@ -111,23 +238,6 @@ export type Options = {
    * @default 'array'
    */
   arrayType?: 'generic' | 'array'
-  transformers?: {
-    /**
-     * Customize the names based on the type that is provided by the plugin.
-     */
-    name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
-  }
-  /**
-   * @example
-   * Use https://ts-ast-viewer.com to generate factory code(see createPropertySignature)
-   * category: factory.createPropertySignature(
-   *   undefined,
-   *   factory.createIdentifier("category"),
-   *   factory.createToken(ts.SyntaxKind.QuestionToken),
-   *   factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
-   * )
-   */
-  mapper?: Record<string, ts.PropertySignature>
   /**
    * How to style your params, by default no casing is applied
    * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
@@ -140,28 +250,78 @@ export type Options = {
    */
   generators?: Array<Generator<PluginTs>>
   /**
-   * Unstable naming for v5
+   * Apply a compatibility naming preset.
+   * Use `kubbV4` for strict v4 type-generation compatibility.
+   * You can further customize naming with `resolvers`.
+   * @default 'default'
    */
-  UNSTABLE_NAMING?: true
-}
+  compatibilityPreset?: CompatibilityPreset
+  /**
+   * Override naming conventions. When a method returns `null` or `undefined`, the preset
+   * resolver (`resolverTs` / `resolverTsLegacy`) is used as fallback.
+   */
+  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.
+   *
+   * @example Remove writeOnly properties from response types
+   * ```ts
+   * transformer: {
+   *   property(node) {
+   *     if (node.schema.writeOnly) return undefined
+   *   }
+   * }
+   * ```
+   */
+  transformer?: 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.
+   *
+   * @example Override the `date` node to use the `Date` object type
+   * ```ts
+   * import ts from 'typescript'
+   * pluginTs({
+   *   printer: {
+   *     nodes: {
+   *       date(node) {
+   *         return ts.factory.createTypeReferenceNode('Date', [])
+   *       },
+   *     },
+   *   },
+   * })
+   * ```
+   */
+  printer?: {
+    nodes?: PrinterTsNodes
+  }
+} & EnumTypeOptions
 
 type ResolvedOptions = {
-  output: Output<Oas>
-  group: Options['group']
-  override: NonNullable<Options['override']>
+  output: Output
+  exclude: Array<Exclude>
+  include: Array<Include> | undefined
+  override: Array<Override<ResolvedOptions>>
+  group: Group | undefined
   enumType: NonNullable<Options['enumType']>
-  enumKeyCasing: NonNullable<Options['enumKeyCasing']>
-  enumSuffix: NonNullable<Options['enumSuffix']>
-  dateType: NonNullable<Options['dateType']>
-  integerType: NonNullable<Options['integerType']>
-  unknownType: NonNullable<Options['unknownType']>
-  emptySchemaType: NonNullable<Options['emptySchemaType']>
+  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
+  enumKeyCasing: EnumKeyCasing
   optionalType: NonNullable<Options['optionalType']>
   arrayType: NonNullable<Options['arrayType']>
-  transformers: NonNullable<Options['transformers']>
   syntaxType: NonNullable<Options['syntaxType']>
-  mapper: Record<string, any>
   paramsCasing: Options['paramsCasing']
+  printer: Options['printer']
 }
 
-export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions>
+export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions, ResolverTs>
+
+declare global {
+  namespace Kubb {
+    interface PluginRegistry {
+      'plugin-ts': PluginTs
+    }
+  }
+}

package/src/utils.ts

@@ -0,0 +1,131 @@
+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>
+  resolver: ResolverTs
+}
+
+type BuildOperationSchemaOptions = {
+  resolver: ResolverTs
+}
+
+export function buildParams(node: OperationNode, { params, resolver }: BuildParamsSchemaOptions): SchemaNode {
+  return createSchema({
+    type: 'object',
+    properties: params.map((param) =>
+      createProperty({
+        name: param.name,
+        required: param.required,
+        schema: createSchema({
+          type: 'ref',
+          name: resolver.resolveParamName(node, param),
+        }),
+      }),
+    ),
+  })
+}
+
+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')
+
+  return createSchema({
+    type: 'object',
+    deprecated: node.deprecated,
+    properties: [
+      createProperty({
+        name: 'data',
+        schema: node.requestBody?.schema
+          ? createSchema({ type: 'ref', name: resolver.resolveDataName(node), optional: true })
+          : createSchema({ type: 'never', primitive: undefined, optional: true }),
+      }),
+      createProperty({
+        name: 'pathParams',
+        required: pathParams.length > 0,
+        schema: pathParams.length > 0 ? buildParams(node, { params: pathParams, resolver }) : createSchema({ type: 'never', primitive: undefined }),
+      }),
+      createProperty({
+        name: 'queryParams',
+        schema:
+          queryParams.length > 0
+            ? createSchema({ ...buildParams(node, { params: queryParams, resolver }), optional: true })
+            : createSchema({ type: 'never', primitive: undefined, optional: true }),
+      }),
+      createProperty({
+        name: 'headerParams',
+        schema:
+          headerParams.length > 0
+            ? createSchema({ ...buildParams(node, { params: headerParams, resolver }), optional: true })
+            : createSchema({ type: 'never', primitive: undefined, optional: true }),
+      }),
+      createProperty({
+        name: 'url',
+        required: true,
+        schema: createSchema({ type: 'url', path: node.path }),
+      }),
+    ],
+  })
+}
+
+export function buildResponses(node: OperationNode, { resolver }: BuildOperationSchemaOptions): SchemaNode | null {
+  if (node.responses.length === 0) {
+    return null
+  }
+
+  return createSchema({
+    type: 'object',
+    properties: node.responses.map((res) =>
+      createProperty({
+        name: String(res.statusCode),
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) }),
+      }),
+    ),
+  })
+}
+
+export function buildResponseUnion(node: OperationNode, { resolver }: BuildOperationSchemaOptions): SchemaNode | null {
+  const responsesWithSchema = node.responses.filter((res) => res.schema)
+
+  if (responsesWithSchema.length === 0) {
+    return null
+  }
+
+  return createSchema({
+    type: 'union',
+    members: responsesWithSchema.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) })),
+  })
+}