@kubb/plugin-ts 5.0.0-alpha.22 → 5.0.0-alpha.24

package/src/types.ts

@@ -1,6 +1,6 @@
+import type { OperationParamsResolver } from '@kubb/ast'
 import type { OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from '@kubb/ast/types'
 import type {
-  Builder,
   CompatibilityPreset,
   Exclude,
   Generator,
@@ -11,233 +11,180 @@ import type {
   PluginFactoryOptions,
   ResolvePathOptions,
   Resolver,
+  UserGroup,
 } from '@kubb/core'
 /**
  * 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 & {
-  /**
-   * Resolves the variable/function name for a given raw name (equivalent to `default(name, 'function')`).
-   * Use this shorthand when matching the `name` field produced by the v2 TypeGenerator,
-   * so call-sites don't need to repeat the `'function'` type literal.
-   *
-   * @example
-   * resolver.resolveName('list pets status 200') // → 'listPetsStatus200'
-   */
-  resolveName(name: string): string
-  /**
-   * Resolves the TypeScript type name for a given raw name (equivalent to `default(name, 'type')`).
-   * Use this shorthand when matching the `typedName` field produced by the v2 TypeGenerator,
-   * so call-sites don't need to repeat the `'type'` type literal.
-   *
-   * @example
-   * resolver.resolveTypedName('list pets status 200') // → 'ListPetsStatus200'
-   */
-  resolveTypedName(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 variable/function name for an operation parameter.
-   * Encapsulates the `<operationId> <PascalCase(paramIn)> <paramName>` naming convention.
-   *
-   * @example
-   * resolver.resolveParamName(node, param) // → 'ListPetsQueryLimit'
-   */
-  resolveParamName(node: OperationNode, param: ParameterNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation parameter
-   * (equivalent to `resolveParamName` with `type: 'type'`).
-   * In the default implementation both return the same PascalCase string;
-   * the distinction is preserved so overrides can diverge the two forms.
-   *
-   * @example
-   * resolver.resolveParamTypedName(node, param) // → 'ListPetsQueryLimit'
-   */
-  resolveParamTypedName(node: OperationNode, param: ParameterNode): string
-  /**
-   * Resolves the variable/function 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 TypeScript type alias name for an operation response by status code.
-   * Encapsulates the `<operationId> Status <statusCode>` template with PascalCase applied to the result.
-   *
-   * @example
-   * resolver.resolveResponseStatusTypedName(node, 200) // → 'ListPetsStatus200'
-   */
-  resolveResponseStatusTypedName(node: OperationNode, statusCode: StatusCode): string
-  /**
-   * Resolves the variable/function name for an operation's request body (`Data`).
-   *
-   * @example
-   * resolver.resolveDataName(node) // → 'ListPetsData'
-   */
-  resolveDataName(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation's request body (`Data`).
-   *
-   * @example
-   * resolver.resolveDataTypedName(node) // → 'ListPetsData'
-   */
-  resolveDataTypedName(node: OperationNode): string
-  /**
-   * Resolves the variable/function name for an operation's request config (`RequestConfig`).
-   *
-   * @example
-   * resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'
-   */
-  resolveRequestConfigName(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation's request config (`RequestConfig`).
-   *
-   * @example
-   * resolver.resolveRequestConfigTypedName(node) // → 'ListPetsRequestConfig'
-   */
-  resolveRequestConfigTypedName(node: OperationNode): string
-  /**
-   * Resolves the variable/function name for the collection of all operation responses (`Responses`).
-   *
-   * @example
-   * resolver.resolveResponsesName(node) // → 'ListPetsResponses'
-   */
-  resolveResponsesName(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for the collection of all operation responses.
-   *
-   * @example
-   * resolver.resolveResponsesTypedName(node) // → 'ListPetsResponses'
-   */
-  resolveResponsesTypedName(node: OperationNode): string
-  /**
-   * Resolves the variable/function 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 the union of all operation responses.
-   *
-   * @example
-   * resolver.resolveResponseTypedName(node) // → 'ListPetsResponse'
-   */
-  resolveResponseTypedName(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.resolveEnumKeyTypedName(node, 'Key')   // → 'PetStatusKey'
-   * resolver.resolveEnumKeyTypedName(node, 'Value') // → 'PetStatusValue'
-   * resolver.resolveEnumKeyTypedName(node, '')      // → 'PetStatus'
-   */
-  resolveEnumKeyTypedName(node: SchemaNode, enumTypeSuffix: string): string
-  /**
-   * Resolves the variable/function name for an operation's grouped path parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamName` per individual parameter instead.
-   * @example
-   * resolver.resolvePathParamsName(node) // → 'GetPetByIdPathParams'
-   */
-  resolvePathParamsName?(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation's grouped path parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamTypedName` per individual parameter instead.
-   * @example
-   * resolver.resolvePathParamsTypedName(node) // → 'GetPetByIdPathParams'
-   */
-  resolvePathParamsTypedName?(node: OperationNode): string
-  /**
-   * Resolves the variable/function name for an operation's grouped query parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamName` per individual parameter instead.
-   * @example
-   * resolver.resolveQueryParamsName(node) // → 'FindPetsByStatusQueryParams'
-   */
-  resolveQueryParamsName?(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation's grouped query parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamTypedName` per individual parameter instead.
-   * @example
-   * resolver.resolveQueryParamsTypedName(node) // → 'FindPetsByStatusQueryParams'
-   */
-  resolveQueryParamsTypedName?(node: OperationNode): string
-  /**
-   * Resolves the variable/function name for an operation's grouped header parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamName` per individual parameter instead.
-   * @example
-   * resolver.resolveHeaderParamsName(node) // → 'DeletePetHeaderParams'
-   */
-  resolveHeaderParamsName?(node: OperationNode): string
-  /**
-   * Resolves the TypeScript type alias name for an operation's grouped header parameters type.
-   * Only available with `compatibilityPreset: 'kubbV4'`.
-   *
-   * @deprecated Kubb v4 compatibility only — use `resolveParamTypedName` per individual parameter instead.
-   * @example
-   * resolver.resolveHeaderParamsTypedName(node) // → 'DeletePetHeaderParams'
-   */
-  resolveHeaderParamsTypedName?(node: OperationNode): string
-}
+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'
+     */
+    resolveName(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 (required on ResolverTs). */
+    resolveDataName(node: OperationNode): string
 
-/**
- * Options for building a grouped parameter schema (`pathParams`, `queryParams`, `headerParams`).
- */
-type BuildParamsSchemaOptions = {
-  params: Array<ParameterNode>
-  node: OperationNode
-  resolver: ResolverTs
-}
+    /**
+     * 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: SchemaNode, 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
+  }
 
-/**
- * Options for building an operation-level schema (`data`, `responses`, `responseUnion`).
- */
-type BuildOperationSchemaOptions = {
-  node: OperationNode
-  resolver: ResolverTs
-}
+type EnumKeyCasing = 'screamingSnakeCase' | 'snakeCase' | 'pascalCase' | 'camelCase' | 'none'
 
 /**
- * The concrete builder type for `@kubb/plugin-ts`.
- * Extends the base `Builder` with schema-building helpers used by the v5 type generator.
+ * 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.
  */
-export type BuilderTs = Builder & {
-  /**
-   * Builds an object schema that groups the given parameters by name.
-   */
-  buildParams(options: BuildParamsSchemaOptions): SchemaNode
-  /**
-   * Builds the combined data schema containing `pathParams`, `queryParams`, `headerParams`, `data`, and `url`.
-   */
-  buildData(options: BuildOperationSchemaOptions): SchemaNode
-  /**
-   * Builds an object schema that maps each response status code to its type reference, or `null` when there are no responses.
-   */
-  buildResponses(options: BuildOperationSchemaOptions): SchemaNode | null
-  /**
-   * Builds a union schema of all response status types, or `null` when no responses have a schema.
-   */
-  buildResponseUnion(options: BuildOperationSchemaOptions): SchemaNode | null
-}
+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' inlines 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 = {
   /**
@@ -253,7 +200,7 @@ export type Options = {
   /**
    * Group the clients based on the provided name.
    */
-  group?: Group
+  group?: UserGroup
   /**
    * Array containing exclude parameters to exclude/skip tags/operations/methods/paths.
    */
@@ -266,37 +213,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.
@@ -367,20 +283,19 @@ export type Options = {
    * ```
    */
   transformers?: Array<Visitor>
-}
+} & EnumTypeOptions
 
 type ResolvedOptions = {
   output: Output
-  group: Options['group']
+  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']>
   paramsCasing: Options['paramsCasing']
-  resolver: ResolverTs
   transformers: Array<Visitor>
 }
 
-export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions, ResolverTs, BuilderTs>
+export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions, ResolverTs>

package/src/utils.ts

@@ -0,0 +1,103 @@
+import { createProperty, createSchema } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
+import type { ResolverTs } from './types.ts'
+
+type BuildParamsSchemaOptions = {
+  params: Array<ParameterNode>
+  node: OperationNode
+  resolver: ResolverTs
+}
+
+type BuildOperationSchemaOptions = {
+  node: OperationNode
+  resolver: ResolverTs
+}
+
+export function buildParams({ params, node, 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, 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', optional: true }),
+      }),
+      createProperty({
+        name: 'pathParams',
+        required: pathParams.length > 0,
+        schema: pathParams.length > 0 ? buildParams({ params: pathParams, node, resolver }) : createSchema({ type: 'never' }),
+      }),
+      createProperty({
+        name: 'queryParams',
+        schema:
+          queryParams.length > 0
+            ? createSchema({ ...buildParams({ params: queryParams, node, resolver }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'headerParams',
+        schema:
+          headerParams.length > 0
+            ? createSchema({ ...buildParams({ params: headerParams, node, resolver }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'url',
+        required: true,
+        schema: createSchema({ type: 'url', path: node.path }),
+      }),
+    ],
+  })
+}
+
+export function buildResponses({ node, 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, 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) })),
+  })
+}