@kubb/plugin-ts 5.0.0-beta.22 → 5.0.0-beta.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-ts",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.27",
   "description": "Generate TypeScript types, interfaces, and enums from your OpenAPI specification. The foundational plugin that powers type safety across the entire Kubb ecosystem.",
   "keywords": [
     "code-generation",
@@ -46,9 +46,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.22",
-    "@kubb/parser-ts": "5.0.0-beta.22",
-    "@kubb/renderer-jsx": "5.0.0-beta.22",
+    "@kubb/core": "5.0.0-beta.27",
+    "@kubb/parser-ts": "5.0.0-beta.27",
+    "@kubb/renderer-jsx": "5.0.0-beta.27",
     "remeda": "^2.34.1",
     "typescript": "^6.0.3"
   },
@@ -57,7 +57,7 @@
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.22"
+    "@kubb/renderer-jsx": "5.0.0-beta.27"
   },
   "size-limit": [
     {

package/src/components/Enum.tsx

@@ -1,6 +1,6 @@
 import { camelCase, trimQuotes } from '@internals/utils'
 import type { ast } from '@kubb/core'
-import { safePrint } from '@kubb/parser-ts'
+import { parserTs } from '@kubb/parser-ts'
 import { File } from '@kubb/renderer-jsx'
 import type { KubbReactNode } from '@kubb/renderer-jsx/types'
 import { ENUM_TYPES_WITH_KEY_SUFFIX, ENUM_TYPES_WITH_RUNTIME_VALUE, ENUM_TYPES_WITH_TYPE_ONLY } from '../constants.ts'
@@ -72,11 +72,11 @@ export function Enum({ node, enumType, enumTypeSuffix, enumKeyCasing, resolver }
     <>
       {nameNode && (
         <File.Source name={enumName} isExportable isIndexable isTypeOnly={false}>
-          {safePrint(nameNode)}
+          {parserTs.print(nameNode)}
         </File.Source>
       )}
       <File.Source name={typeName} isIndexable isExportable={ENUM_TYPES_WITH_RUNTIME_VALUE.has(enumType)} isTypeOnly={ENUM_TYPES_WITH_TYPE_ONLY.has(enumType)}>
-        {safePrint(typeNode)}
+        {parserTs.print(typeNode)}
       </File.Source>
     </>
   )

package/src/factory.ts

@@ -198,7 +198,7 @@ export function createParameterSignature(
  * Creates a JSDoc comment node from an array of comment strings.
  * Returns null if no comments are provided.
  */
-export function createJSDoc({ comments }: { comments: string[] }) {
+export function createJSDoc({ comments }: { comments: Array<string> }) {
   if (!comments.length) {
     return null
   }
@@ -338,7 +338,7 @@ export function createTypeDeclaration({
 /**
  * Creates a TypeScript namespace declaration (exported module).
  */
-export function createNamespaceDeclaration({ statements, name }: { name: string; statements: ts.Statement[] }) {
+export function createNamespaceDeclaration({ statements, name }: { name: string; statements: Array<ts.Statement> }) {
   return factory.createModuleDeclaration(
     [factory.createToken(ts.SyntaxKind.ExportKeyword)],
     factory.createIdentifier(name),
@@ -519,7 +519,7 @@ export function createEnumDeclaration({
    * Enum name in PascalCase.
    */
   typeName: string
-  enums: [key: string | number, value: string | number | boolean][]
+  enums: Array<[key: string | number, value: string | number | boolean]>
   /**
    * Choose the casing for enum key names.
    * @default 'none'
@@ -740,8 +740,8 @@ export function createUrlTemplateType(path: string): ts.TypeNode {
   }
 
   const segments = normalized.split(/(\{[^}]+\})/)
-  const parts: string[] = []
-  const parameterIndices: number[] = []
+  const parts: Array<string> = []
+  const parameterIndices: Array<number> = []
 
   segments.forEach((segment) => {
     if (segment.startsWith('{') && segment.endsWith('}')) {
@@ -753,7 +753,7 @@ export function createUrlTemplateType(path: string): ts.TypeNode {
   })
 
   const head = ts.factory.createTemplateHead(parts[0] || '')
-  const templateSpans: ts.TemplateLiteralTypeSpan[] = []
+  const templateSpans: Array<ts.TemplateLiteralTypeSpan> = []
 
   parameterIndices.forEach((paramIndex, i) => {
     const isLast = i === parameterIndices.length - 1

package/src/generators/typeGenerator.tsx

@@ -24,6 +24,12 @@ function getPerContentTypeName(dataName: string, suffix: string): string {
   return dataName + suffix
 }
 
+/**
+ * Built-in generator for `@kubb/plugin-ts`. Emits one TypeScript file per
+ * schema in the spec plus per-operation request, response, and parameter
+ * types. Drop-replace with a custom `Generator<PluginTs>` to change how
+ * TypeScript output is produced.
+ */
 export const typeGenerator = defineGenerator<PluginTs>({
   name: 'typescript',
   renderer: jsxRendererSync,
@@ -48,14 +54,14 @@ export const typeGenerator = defineGenerator<PluginTs>({
 
     const imports = adapter.getImports(node, (schemaName) => ({
       name: resolveImportName(schemaName),
-      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
     }))
 
     const isEnumSchema = !!ast.narrowSchema(node, ast.schemaTypes.enum)
 
     const meta = {
       name: ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && isEnumSchema ? resolver.resolveEnumKeyName(node, enumTypeSuffix) : resolver.resolveTypeName(node.name),
-      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group }),
+      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group: group ?? undefined }),
     } as const
 
     const schemaPrinter = printerTs({
@@ -104,7 +110,10 @@ export const typeGenerator = defineGenerator<PluginTs>({
     const params = ast.caseParams(node.parameters, paramsCasing)
 
     const meta = {
-      file: resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group }),
+      file: resolver.resolveFile(
+        { name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path },
+        { root, output, group: group ?? undefined },
+      ),
     } as const
 
     // Build a set of schema names that are enums so the ref handler and getImports
@@ -123,7 +132,7 @@ export const typeGenerator = defineGenerator<PluginTs>({
 
       const imports = adapter.getImports(schema, (schemaName) => ({
         name: resolveImportName(schemaName),
-        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group: group ?? undefined }).path,
       }))
 
       const schemaPrinter = printerTs({

package/src/plugin.ts

@@ -5,23 +5,32 @@ import { resolverTs } from './resolvers/resolverTs.ts'
 import type { PluginTs } from './types.ts'
 
 /**
- * Canonical plugin name for `@kubb/plugin-ts`, used to identify the plugin in driver lookups and warnings.
+ * Canonical plugin name for `@kubb/plugin-ts`. Used for driver lookups and
+ * cross-plugin dependency references.
  */
 export const pluginTsName = 'plugin-ts' satisfies PluginTs['name']
 
 /**
- * The `@kubb/plugin-ts` plugin factory.
- *
- * Generates TypeScript type declarations from an OpenAPI/AST `RootNode`.
- * Walks schemas and operations, delegates rendering to the active generators,
- * and writes barrel files based on `output.barrelType`.
+ * Generates TypeScript `type` aliases and `interface` declarations from an
+ * OpenAPI spec. The foundation that every other Kubb plugin builds on:
+ * clients, query hooks, mocks, and validators all reference the names this
+ * plugin produces.
  *
  * @example
  * ```ts
- * import pluginTs from '@kubb/plugin-ts'
+ * import { defineConfig } from 'kubb'
+ * import { pluginTs } from '@kubb/plugin-ts'
  *
  * export default defineConfig({
- *   plugins: [pluginTs({ output: { path: 'types' }, enumType: 'asConst' })],
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   plugins: [
+ *     pluginTs({
+ *       output: { path: './types' },
+ *       enumType: 'asConst',
+ *       optionalType: 'questionTokenAndUndefined',
+ *     }),
+ *   ],
  * })
  * ```
  */
@@ -55,7 +64,7 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
           return `${camelCase(ctx.group)}Controller`
         },
       } satisfies Group)
-    : undefined
+    : null
 
   return {
     name: pluginTsName,

package/src/printers/printerTs.ts

@@ -1,5 +1,5 @@
 import { ast } from '@kubb/core'
-import { safePrint } from '@kubb/parser-ts'
+import { parserTs } from '@kubb/parser-ts'
 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'
@@ -292,7 +292,7 @@ export const printerTs = ast.definePrinter<PrinterTs>((options) => {
           (meta.nullish || meta.optional) && addsUndefined
             ? factory.createUnionDeclaration({ nodes: [withNullable, factory.keywordTypeNodes.undefined] })
             : withNullable
-        return safePrint(result)
+        return parserTs.print(result)
       }
 
       // When keysToOmit is present, wrap with Omit first, then apply nullable/optional
@@ -320,7 +320,7 @@ export const printerTs = ast.definePrinter<PrinterTs>((options) => {
         }),
       })
 
-      return safePrint(typeNode)
+      return parserTs.print(typeNode)
     },
   }
 })

package/src/resolvers/resolverTs.ts

@@ -1,22 +1,23 @@
-import { pascalCase } from '@internals/utils'
+import { ensureValidVarName, pascalCase } 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-with-isFile 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>(() => {
@@ -24,13 +25,15 @@ export const resolverTs = defineResolver<PluginTs>(() => {
     name: 'default',
     pluginName: 'plugin-ts',
     default(name, type) {
-      return pascalCase(name, { isFile: type === 'file' })
+      const resolved = pascalCase(name, { isFile: type === 'file' })
+      return type === 'file' ? resolved : ensureValidVarName(resolved)
     },
     resolveTypeName(name) {
-      return pascalCase(name)
+      return ensureValidVarName(pascalCase(name))
     },
     resolvePathName(name, type) {
-      return pascalCase(name, { isFile: type === 'file' })
+      const resolved = pascalCase(name, { isFile: type === 'file' })
+      return type === 'file' ? resolved : ensureValidVarName(resolved)
     },
     resolveParamName(node, param) {
       return this.resolveTypeName(`${node.operationId} ${param.in} ${param.name}`)

package/src/types.ts

@@ -115,7 +115,7 @@ type EnumTypeOptions =
       /**
        * Suffix appended to the generated type alias name.
        *
-       * Only affects the type alias — the const object name is unchanged.
+       * Only affects the type alias; the const object name is unchanged.
        *
        * @default 'Key'
        * @example enumTypeSuffix: 'Value' → `export type PetStatusValue = …`
@@ -172,81 +172,89 @@ type EnumTypeOptions =
       enumTypeSuffix?: never
       /**
        * `enumKeyCasing` has no effect for this `enumType`.
-       * Literal and inlineLiteral modes emit only values — keys are discarded entirely.
+       * 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' }
+   * Where the generated `.ts` files are written and how they are exported.
+   *
+   * @default { path: 'types', barrel: { type: 'named' } }
    */
   output?: Output
   /**
-   * Define which contentType should be used.
-   * By default, uses the first valid JSON media type.
+   * 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 & {})
   /**
-   * Group the clients based on the provided name.
+   * Split generated files into subfolders based on the operation's tag.
    */
   group?: Group
   /**
-   * 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 +265,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', [])
    *       },
    *     },
@@ -286,7 +293,7 @@ type ResolvedOptions = {
   exclude: Array<Exclude>
   include: Array<Include> | undefined
   override: Array<Override<ResolvedOptions>>
-  group: Group | undefined
+  group: Group | null
   enumType: NonNullable<Options['enumType']>
   enumTypeSuffix: NonNullable<Options['enumTypeSuffix']>
   enumKeyCasing: EnumKeyCasing

package/src/utils.ts

@@ -16,19 +16,19 @@ export function buildPropertyJSDocComments(schema: ast.SchemaNode): Array<string
   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,
+    meta && 'description' in meta && meta.description ? `@description ${jsStringEscape(meta.description)}` : null,
+    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)
 }