@kubb/plugin-ts 5.0.0-beta.42 → 5.0.0-beta.64

package/src/types.ts

@@ -1,315 +0,0 @@
-import type { ast, Exclude, Generator, Group, Include, Output, Override, PluginFactoryOptions, Resolver } 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 &
-  ast.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 Resolving type names
-     * `resolver.resolveName('list pets status 200') // → 'ListPetsStatus200'`
-     */
-    resolveTypeName(name: string): string
-    /**
-     * Resolves the file/path name for a given identifier using PascalCase.
-     *
-     * @example Resolving path names
-     * `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: ast.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 Response status names
-     * `resolver.resolveResponseStatusName(node, 200) // → 'ListPetsStatus200'`
-     */
-    resolveResponseStatusName(node: ast.OperationNode, statusCode: ast.StatusCode): string
-    /**
-     * Resolves the name for an operation's request config (`RequestConfig`).
-     *
-     * @example Request config names
-     * `resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'`
-     */
-    resolveRequestConfigName(node: ast.OperationNode): string
-    /**
-     * Resolves the name for the collection of all operation responses (`Responses`).
-     *
-     * @example Responses collection names
-     * `resolver.resolveResponsesName(node) // → 'ListPetsResponses'`
-     */
-    resolveResponsesName(node: ast.OperationNode): string
-    /**
-     * Resolves the name for the union of all operation responses (`Response`).
-     *
-     * @example Response union names
-     * `resolver.resolveResponseName(node) // → 'ListPetsResponse'`
-     */
-    resolveResponseName(node: ast.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 Enum key names with different suffixes
-     * ```ts
-     * 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 Path parameters names
-     * `resolver.resolvePathParamsName(node, param) // → 'GetPetByIdPathParams'`
-     */
-    resolvePathParamsName(node: ast.OperationNode, param: ast.ParameterNode): string
-    /**
-     * Resolves the name for an operation's grouped query parameters type.
-     *
-     * @example Query parameters names
-     * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
-     */
-    resolveQueryParamsName(node: ast.OperationNode, param: ast.ParameterNode): string
-    /**
-     * Resolves the name for an operation's grouped header parameters type.
-     *
-     * @example Header parameters names
-     * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
-     */
-    resolveHeaderParamsName(node: ast.OperationNode, param: ast.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 = {
-  /**
-   * Where the generated `.ts` files are written and how they are exported.
-   *
-   * @default { path: 'types', barrel: { type: 'named' } }
-   */
-  output?: Output
-  /**
-   * Media type read from the OpenAPI spec when an operation defines several.
-   * Defaults to the first JSON-compatible media type Kubb finds.
-   */
-  contentType?: 'application/json' | (string & {})
-  /**
-   * Split generated files into subfolders based on the operation's tag.
-   */
-  group?: Group
-  /**
-   * Skip operations matching at least one entry in the list.
-   */
-  exclude?: Array<Exclude>
-  /**
-   * Restrict generation to operations matching at least one entry in the list.
-   */
-  include?: Array<Include>
-  /**
-   * Apply a different options object to operations matching a pattern.
-   */
-  override?: Array<Override<ResolvedOptions>>
-  /**
-   * 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'
-  /**
-   * 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'
-  /**
-   * Syntax used for array types.
-   * - `'array'` — `Type[]`. Shorter.
-   * - `'generic'` — `Array<Type>`. More readable for complex element types.
-   *
-   * @default 'array'
-   */
-  arrayType?: 'generic' | 'array'
-  /**
-   * 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'
-  /**
-   * Custom generators that run alongside the built-in TypeScript generators.
-   */
-  generators?: Array<Generator<PluginTs>>
-  /**
-   * 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 or operation node before printing.
-   * Methods you omit fall back to the preset transformer.
-   *
-   * @example Drop writeOnly properties from response types
-   * ```ts
-   * transformer: {
-   *   property(node) {
-   *     if (node.schema.writeOnly) return undefined
-   *   }
-   * }
-   * ```
-   */
-  transformer?: ast.Visitor
-  /**
-   * 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 Use the JavaScript `Date` object for date schemas
-   * ```ts
-   * import ts from 'typescript'
-   * pluginTs({
-   *   printer: {
-   *     nodes: {
-   *       date() {
-   *         return ts.factory.createTypeReferenceNode('Date', [])
-   *       },
-   *     },
-   *   },
-   * })
-   * ```
-   */
-  printer?: {
-    nodes?: PrinterTsNodes
-  }
-} & EnumTypeOptions
-
-type ResolvedOptions = {
-  output: Output
-  exclude: Array<Exclude>
-  include: Array<Include> | undefined
-  override: Array<Override<ResolvedOptions>>
-  group: Group | null
-  enumType: NonNullable<Options['enumType']>
-  enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
-  enumKeyCasing: EnumKeyCasing
-  optionalType: NonNullable<Options['optionalType']>
-  arrayType: NonNullable<Options['arrayType']>
-  syntaxType: NonNullable<Options['syntaxType']>
-  paramsCasing: Options['paramsCasing']
-  printer: Options['printer']
-}
-
-export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, ResolverTs>
-
-declare global {
-  namespace Kubb {
-    interface PluginRegistry {
-      'plugin-ts': PluginTs
-    }
-  }
-}

package/src/utils.ts

@@ -1,140 +0,0 @@
-import { jsStringEscape, stringify } from '@internals/utils'
-import { getOperationParameters } from '@internals/shared'
-import { ast } from '@kubb/core'
-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: ast.SchemaNode): Array<string | undefined> {
-  const meta = ast.syncSchemaRef(schema)
-
-  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 [
-    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}` : 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}`
-      : 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' : null].filter(Boolean).join('')
-      : null,
-  ].filter(Boolean)
-}
-
-type BuildParamsSchemaOptions = {
-  params: Array<ast.ParameterNode>
-  resolver: ResolverTs
-}
-
-type BuildOperationSchemaOptions = {
-  resolver: ResolverTs
-}
-
-export function buildParams(node: ast.OperationNode, { params, resolver }: BuildParamsSchemaOptions): ast.SchemaNode {
-  return ast.createSchema({
-    type: 'object',
-    properties: params.map((param) =>
-      ast.createProperty({
-        name: param.name,
-        required: param.required,
-        schema: ast.createSchema({
-          type: 'ref',
-          name: resolver.resolveParamName(node, param),
-        }),
-      }),
-    ),
-  })
-}
-
-export function buildData(node: ast.OperationNode, { resolver }: BuildOperationSchemaOptions): ast.SchemaNode {
-  const { path: pathParams, query: queryParams, header: headerParams } = getOperationParameters(node)
-
-  return ast.createSchema({
-    type: 'object',
-    deprecated: node.deprecated,
-    properties: [
-      ast.createProperty({
-        name: 'data',
-        schema: node.requestBody?.content?.[0]?.schema
-          ? ast.createSchema({ type: 'ref', name: resolver.resolveDataName(node), optional: true })
-          : ast.createSchema({ type: 'never', primitive: undefined, optional: true }),
-      }),
-      ast.createProperty({
-        name: 'pathParams',
-        required: pathParams.length > 0,
-        schema: pathParams.length > 0 ? buildParams(node, { params: pathParams, resolver }) : ast.createSchema({ type: 'never', primitive: undefined }),
-      }),
-      ast.createProperty({
-        name: 'queryParams',
-        schema:
-          queryParams.length > 0
-            ? ast.createSchema({ ...buildParams(node, { params: queryParams, resolver }), optional: true })
-            : ast.createSchema({ type: 'never', primitive: undefined, optional: true }),
-      }),
-      ast.createProperty({
-        name: 'headerParams',
-        schema:
-          headerParams.length > 0
-            ? ast.createSchema({ ...buildParams(node, { params: headerParams, resolver }), optional: true })
-            : ast.createSchema({ type: 'never', primitive: undefined, optional: true }),
-      }),
-      ast.createProperty({
-        name: 'url',
-        required: true,
-        schema: ast.createSchema({ type: 'url', path: node.path }),
-      }),
-    ],
-  })
-}
-
-export function buildResponses(node: ast.OperationNode, { resolver }: BuildOperationSchemaOptions): ast.SchemaNode | null {
-  if (node.responses.length === 0) {
-    return null
-  }
-
-  return ast.createSchema({
-    type: 'object',
-    properties: node.responses.map((res) =>
-      ast.createProperty({
-        name: String(res.statusCode),
-        required: true,
-        schema: ast.createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) }),
-      }),
-    ),
-  })
-}
-
-export function buildResponseUnion(node: ast.OperationNode, { resolver }: BuildOperationSchemaOptions): ast.SchemaNode | null {
-  const responsesWithSchema = node.responses.filter((res) => res.content?.some((entry) => entry.schema))
-
-  if (responsesWithSchema.length === 0) {
-    return null
-  }
-
-  return ast.createSchema({
-    type: 'union',
-    members: responsesWithSchema.map((res) => ast.createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) })),
-  })
-}