@kubb/plugin-ts 5.0.0-alpha.12 → 5.0.0-alpha.14

package/src/plugin.ts

@@ -1,9 +1,9 @@
 import path from 'node:path'
 import { camelCase } from '@internals/utils'
 import { walk } from '@kubb/ast'
-import { createPlugin, type Group, getBarrelFiles, getMode, renderOperation, renderSchema } from '@kubb/core'
-import { typeGenerator } from './generators'
-import { resolverTs, resolverTsLegacy } from './resolverTs.ts'
+import { createPlugin, type Group, getBarrelFiles, getMode, mergeResolvers, renderOperation, renderSchema } from '@kubb/core'
+import { typeGenerator } from './generators/index.ts'
+import { resolverTs, resolverTsLegacy } from './resolvers/index.ts'
 import type { PluginTs } from './types.ts'
 
 export const pluginTsName = 'plugin-ts' satisfies PluginTs['name']
@@ -20,27 +20,15 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
     optionalType = 'questionToken',
     arrayType = 'array',
     syntaxType = 'type',
-    transformers = {},
     paramsCasing,
     generators = [typeGenerator].filter(Boolean),
     legacy = false,
+    resolvers: userResolvers,
+    transformers = [],
   } = options
 
   const baseResolver = legacy ? resolverTsLegacy : resolverTs
-
-  // When a `transformers.name` callback is provided, wrap the resolver so that
-  // every name produced by `default()` (and therefore by every helper that calls
-  // `this.default(...)`) flows through the user's transformer.
-  const resolver: typeof baseResolver = transformers?.name
-    ? {
-        ...baseResolver,
-        default(name, type) {
-          const resolved = baseResolver.default(name, type)
-
-          return transformers.name!(resolved, type) || resolved
-        },
-      }
-    : baseResolver
+  const resolver = mergeResolvers(...(userResolvers ?? [baseResolver]))
 
   let resolveNameWarning = false
 
@@ -48,7 +36,6 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
     name: pluginTsName,
     options: {
       output,
-      transformers,
       optionalType,
       arrayType,
       enumType,
@@ -59,6 +46,8 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
       paramsCasing,
       legacy,
       resolver,
+      baseResolver,
+      transformers,
     },
     resolvePath(baseName, pathMode, options) {
       const root = path.resolve(this.config.root, this.config.output.path)
@@ -114,60 +103,57 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
 
       await openInStudio({ ast: true })
 
-      await walk(
-        rootNode,
-        {
-          async schema(schemaNode) {
-            const writeTasks = generators.map(async (generator) => {
-              if (generator.type === 'react' && generator.version === '2') {
-                const options = resolver.resolveOptions(schemaNode, { options: plugin.options, exclude, include, override })
-
-                if (options === null) {
-                  return
-                }
-
-                await renderSchema(schemaNode, {
-                  options,
-                  adapter,
-                  config,
-                  fabric,
-                  Component: generator.Schema,
-                  plugin,
-                  driver,
-                  mode,
-                })
+      await walk(rootNode, {
+        depth: 'shallow',
+        async schema(schemaNode) {
+          const writeTasks = generators.map(async (generator) => {
+            if (generator.type === 'react' && generator.version === '2') {
+              const options = resolver.resolveOptions(schemaNode, { options: plugin.options, exclude, include, override })
+
+              if (options === null) {
+                return
               }
-            })
-
-            await Promise.all(writeTasks)
-          },
-          async operation(operationNode) {
-            const writeTasks = generators.map(async (generator) => {
-              if (generator.type === 'react' && generator.version === '2') {
-                const options = resolver.resolveOptions(operationNode, { options: plugin.options, exclude, include, override })
-
-                if (options === null) {
-                  return
-                }
-
-                await renderOperation(operationNode, {
-                  options,
-                  adapter,
-                  config,
-                  fabric,
-                  Component: generator.Operation,
-                  plugin,
-                  driver,
-                  mode,
-                })
+
+              await renderSchema(schemaNode, {
+                options,
+                adapter,
+                config,
+                fabric,
+                Component: generator.Schema,
+                plugin,
+                driver,
+                mode,
+              })
+            }
+          })
+
+          await Promise.all(writeTasks)
+        },
+        async operation(operationNode) {
+          const writeTasks = generators.map(async (generator) => {
+            if (generator.type === 'react' && generator.version === '2') {
+              const options = resolver.resolveOptions(operationNode, { options: plugin.options, exclude, include, override })
+
+              if (options === null) {
+                return
               }
-            })
 
-            await Promise.all(writeTasks)
-          },
+              await renderOperation(operationNode, {
+                options,
+                adapter,
+                config,
+                fabric,
+                Component: generator.Operation,
+                plugin,
+                driver,
+                mode,
+              })
+            }
+          })
+
+          await Promise.all(writeTasks)
         },
-        { depth: 'shallow' },
-      )
+      })
 
       const barrelFiles = await getBarrelFiles(this.fabric.files, {
         type: output.barrelType ?? 'named',

package/src/printer.ts

@@ -134,11 +134,14 @@ function buildPropertyType(schema: SchemaNode, baseType: ts.TypeNode, optionalTy
  * Collects JSDoc annotation strings (description, deprecated, min/max, pattern, default, example, type) for a schema node.
  */
 function buildPropertyJSDocComments(schema: SchemaNode): Array<string | undefined> {
+  const isArray = schema.type === 'array'
+
   return [
     'description' in schema && schema.description ? `@description ${jsStringEscape(schema.description)}` : undefined,
     'deprecated' in schema && schema.deprecated ? '@deprecated' : undefined,
-    'min' in schema && schema.min !== undefined ? `@minLength ${schema.min}` : undefined,
-    'max' in schema && schema.max !== undefined ? `@maxLength ${schema.max}` : undefined,
+    // minItems/maxItems on arrays should not be emitted as @minLength/@maxLength
+    !isArray && 'min' in schema && schema.min !== undefined ? `@minLength ${schema.min}` : undefined,
+    !isArray && 'max' in schema && schema.max !== undefined ? `@maxLength ${schema.max}` : undefined,
     'pattern' in schema && schema.pattern ? `@pattern ${schema.pattern}` : undefined,
     'default' in schema && schema.default !== undefined
       ? `@default ${'primitive' in schema && schema.primitive === 'string' ? stringify(schema.default as string) : schema.default}`

package/src/resolvers/index.ts

@@ -0,0 +1,2 @@
+export { resolverTs } from './resolverTs.ts'
+export { resolverTsLegacy } from './resolverTsLegacy.ts'

package/src/{resolverTs.ts → resolvers/resolverTs.ts}

@@ -1,6 +1,6 @@
 import { pascalCase } from '@internals/utils'
 import { defineResolver } from '@kubb/core'
-import type { PluginTs } from './types.ts'
+import type { PluginTs } from '../types.ts'
 
 function resolveName(name: string, type?: 'file' | 'function' | 'type' | 'const'): string {
   return pascalCase(name, { isFile: type === 'file' })
@@ -26,6 +26,7 @@ function resolveName(name: string, type?: 'file' | 'function' | 'type' | 'const'
  */
 export const resolverTs = defineResolver<PluginTs>(() => {
   return {
+    name: 'default',
     default(name, type) {
       return resolveName(name, type)
     },
@@ -83,13 +84,11 @@ export const resolverTs = defineResolver<PluginTs>(() => {
     resolvePathParamsTypedName(_node) {
       throw new Error('resolvePathParamsTypedName is only available in legacy mode (legacy: true). Use resolveParamTypedName per individual parameter instead.')
     },
-    resolveQueryParamsName(_node) {
-      throw new Error('resolveQueryParamsName is only available in legacy mode (legacy: true). Use resolveParamName per individual parameter instead.')
+    resolveQueryParamsName(node) {
+      return this.resolveName(`${node.operationId} QueryParams`)
     },
-    resolveQueryParamsTypedName(_node) {
-      throw new Error(
-        'resolveQueryParamsTypedName is only available in legacy mode (legacy: true). Use resolveParamTypedName per individual parameter instead.',
-      )
+    resolveQueryParamsTypedName(node) {
+      return this.resolveTypedName(`${node.operationId} QueryParams`)
     },
     resolveHeaderParamsName(_node) {
       throw new Error('resolveHeaderParamsName is only available in legacy mode (legacy: true). Use resolveParamName per individual parameter instead.')
@@ -101,85 +100,3 @@ export const resolverTs = defineResolver<PluginTs>(() => {
     },
   }
 })
-
-/**
- * Legacy resolver for `@kubb/plugin-ts` that reproduces the naming conventions
- * used before the v2 resolver refactor. Enable via `legacy: true` in plugin options.
- *
- * Key differences from the default resolver:
- * - Response status types: `<OperationId><StatusCode>` (e.g. `CreatePets201`) instead of `<OperationId>Status201`
- * - Default/error responses: `<OperationId>Error` instead of `<OperationId>StatusDefault`
- * - Request body: `<OperationId>MutationRequest` (non-GET) / `<OperationId>QueryRequest` (GET)
- * - Combined responses type: `<OperationId>Mutation` / `<OperationId>Query`
- * - Response union: `<OperationId>MutationResponse` / `<OperationId>QueryResponse`
- *
- * @example
- * ```ts
- * import { resolverTsLegacy } from '@kubb/plugin-ts'
- *
- * resolverTsLegacy.resolveResponseStatusTypedName(node, 201)  // → 'CreatePets201'
- * resolverTsLegacy.resolveResponseStatusTypedName(node, 'default')  // → 'CreatePetsError'
- * resolverTsLegacy.resolveDataTypedName(node)  // → 'CreatePetsMutationRequest' (POST)
- * resolverTsLegacy.resolveResponsesTypedName(node)  // → 'CreatePetsMutation' (POST)
- * resolverTsLegacy.resolveResponseTypedName(node)  // → 'CreatePetsMutationResponse' (POST)
- * ```
- */
-export const resolverTsLegacy = defineResolver<PluginTs>(() => {
-  return {
-    ...resolverTs,
-    resolveResponseStatusName(node, statusCode) {
-      if (statusCode === 'default') {
-        return this.resolveName(`${node.operationId} Error`)
-      }
-      return this.resolveName(`${node.operationId} ${statusCode}`)
-    },
-    resolveResponseStatusTypedName(node, statusCode) {
-      if (statusCode === 'default') {
-        return this.resolveTypedName(`${node.operationId} Error`)
-      }
-      return this.resolveTypedName(`${node.operationId} ${statusCode}`)
-    },
-    resolveDataName(node) {
-      const suffix = node.method === 'GET' ? 'QueryRequest' : 'MutationRequest'
-      return this.resolveName(`${node.operationId} ${suffix}`)
-    },
-    resolveDataTypedName(node) {
-      const suffix = node.method === 'GET' ? 'QueryRequest' : 'MutationRequest'
-      return this.resolveTypedName(`${node.operationId} ${suffix}`)
-    },
-    resolveResponsesName(node) {
-      const suffix = node.method === 'GET' ? 'Query' : 'Mutation'
-      return this.resolveName(`${node.operationId} ${suffix}`)
-    },
-    resolveResponsesTypedName(node) {
-      const suffix = node.method === 'GET' ? 'Query' : 'Mutation'
-      return this.resolveTypedName(`${node.operationId} ${suffix}`)
-    },
-    resolveResponseName(node) {
-      const suffix = node.method === 'GET' ? 'QueryResponse' : 'MutationResponse'
-      return this.resolveName(`${node.operationId} ${suffix}`)
-    },
-    resolveResponseTypedName(node) {
-      const suffix = node.method === 'GET' ? 'QueryResponse' : 'MutationResponse'
-      return this.resolveTypedName(`${node.operationId} ${suffix}`)
-    },
-    resolvePathParamsName(node) {
-      return this.resolveName(`${node.operationId} PathParams`)
-    },
-    resolvePathParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} PathParams`)
-    },
-    resolveQueryParamsName(node) {
-      return this.resolveName(`${node.operationId} QueryParams`)
-    },
-    resolveQueryParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} QueryParams`)
-    },
-    resolveHeaderParamsName(node) {
-      return this.resolveName(`${node.operationId} HeaderParams`)
-    },
-    resolveHeaderParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} HeaderParams`)
-    },
-  }
-})

package/src/resolvers/resolverTsLegacy.ts

@@ -0,0 +1,86 @@
+import { defineResolver } from '@kubb/core'
+import type { PluginTs } from '../types.ts'
+import { resolverTs } from './resolverTs.ts'
+
+/**
+ * Legacy resolver for `@kubb/plugin-ts` that reproduces the naming conventions
+ * used before the v2 resolver refactor. Enable via `legacy: true` in plugin options.
+ *
+ * Key differences from the default resolver:
+ * - Response status types: `<OperationId><StatusCode>` (e.g. `CreatePets201`) instead of `<OperationId>Status201`
+ * - Default/error responses: `<OperationId>Error` instead of `<OperationId>StatusDefault`
+ * - Request body: `<OperationId>MutationRequest` (non-GET) / `<OperationId>QueryRequest` (GET)
+ * - Combined responses type: `<OperationId>Mutation` / `<OperationId>Query`
+ * - Response union: `<OperationId>MutationResponse` / `<OperationId>QueryResponse`
+ *
+ * @example
+ * ```ts
+ * import { resolverTsLegacy } from '@kubb/plugin-ts'
+ *
+ * resolverTsLegacy.resolveResponseStatusTypedName(node, 201)  // → 'CreatePets201'
+ * resolverTsLegacy.resolveResponseStatusTypedName(node, 'default')  // → 'CreatePetsError'
+ * resolverTsLegacy.resolveDataTypedName(node)  // → 'CreatePetsMutationRequest' (POST)
+ * resolverTsLegacy.resolveResponsesTypedName(node)  // → 'CreatePetsMutation' (POST)
+ * resolverTsLegacy.resolveResponseTypedName(node)  // → 'CreatePetsMutationResponse' (POST)
+ * ```
+ */
+export const resolverTsLegacy = defineResolver<PluginTs>(() => {
+  return {
+    ...resolverTs,
+    name: 'legacy',
+    resolveResponseStatusName(node, statusCode) {
+      if (statusCode === 'default') {
+        return this.resolveName(`${node.operationId} Error`)
+      }
+      return this.resolveName(`${node.operationId} ${statusCode}`)
+    },
+    resolveResponseStatusTypedName(node, statusCode) {
+      if (statusCode === 'default') {
+        return this.resolveTypedName(`${node.operationId} Error`)
+      }
+      return this.resolveTypedName(`${node.operationId} ${statusCode}`)
+    },
+    resolveDataName(node) {
+      const suffix = node.method === 'GET' ? 'QueryRequest' : 'MutationRequest'
+      return this.resolveName(`${node.operationId} ${suffix}`)
+    },
+    resolveDataTypedName(node) {
+      const suffix = node.method === 'GET' ? 'QueryRequest' : 'MutationRequest'
+      return this.resolveTypedName(`${node.operationId} ${suffix}`)
+    },
+    resolveResponsesName(node) {
+      const suffix = node.method === 'GET' ? 'Query' : 'Mutation'
+      return `${this.default(node.operationId, 'function')}${suffix}`
+    },
+    resolveResponsesTypedName(node) {
+      const suffix = node.method === 'GET' ? 'Query' : 'Mutation'
+      return `${this.default(node.operationId, 'type')}${suffix}`
+    },
+    resolveResponseName(node) {
+      const suffix = node.method === 'GET' ? 'QueryResponse' : 'MutationResponse'
+      return this.resolveName(`${node.operationId} ${suffix}`)
+    },
+    resolveResponseTypedName(node) {
+      const suffix = node.method === 'GET' ? 'QueryResponse' : 'MutationResponse'
+      return this.resolveTypedName(`${node.operationId} ${suffix}`)
+    },
+    resolvePathParamsName(node) {
+      return this.resolveName(`${node.operationId} PathParams`)
+    },
+    resolvePathParamsTypedName(node) {
+      return this.resolveTypedName(`${node.operationId} PathParams`)
+    },
+    resolveQueryParamsName(node) {
+      return this.resolveName(`${node.operationId} QueryParams`)
+    },
+    resolveQueryParamsTypedName(node) {
+      return this.resolveTypedName(`${node.operationId} QueryParams`)
+    },
+    resolveHeaderParamsName(node) {
+      return this.resolveName(`${node.operationId} HeaderParams`)
+    },
+    resolveHeaderParamsTypedName(node) {
+      return this.resolveTypedName(`${node.operationId} HeaderParams`)
+    },
+  }
+})

package/src/types.ts

@@ -1,5 +1,5 @@
-import type { OperationNode, ParameterNode, SchemaNode, StatusCode } from '@kubb/ast/types'
-import type { Group, Output, PluginFactoryOptions, ResolveNameParams, Resolver } from '@kubb/core'
+import type { OperationNode, ParameterNode, SchemaNode, StatusCode, Visitor } from '@kubb/ast/types'
+import type { Group, Output, PluginFactoryOptions, Resolver } 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'
@@ -260,12 +260,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
-  }
   /**
    * How to style your params, by default no casing is applied
    * - 'camelcase' uses camelCase for pathParams, queryParams and headerParams property names
@@ -283,15 +277,39 @@ export type Options = {
   UNSTABLE_NAMING?: true
   /**
    * Enable legacy naming conventions for backwards compatibility.
-   * When enabled, operation-level types use the old naming scheme:
-   * - GET responses → `<OperationId>QueryResponse`, `<OperationId>Query`
-   * - Non-GET responses → `<OperationId>MutationResponse`, `<OperationId>Mutation`
-   * - Request body → `<OperationId>QueryRequest` / `<OperationId>MutationRequest`
-   * - Response status codes → `<OperationId><StatusCode>` (e.g. `CreatePets201`)
-   * - Default/error response → `<OperationId>Error`
    * @default false
    */
   legacy?: boolean
+  /**
+   * Array of named resolvers that control naming conventions.
+   * Later entries override earlier ones (last wins).
+   * Built-in: `resolverTs` (default), `resolverTsLegacy`.
+   * @default [resolverTs]
+   */
+  resolvers?: Array<ResolverTs>
+  /**
+   * Array of AST visitors applied to each SchemaNode/OperationNode before printing.
+   * Uses `transform()` from `@kubb/ast` — visitors can modify, replace, or annotate nodes.
+   *
+   * @example Remove writeOnly properties from response types
+   * ```ts
+   * transformers: [{
+   *   property(node) {
+   *     if (node.schema.writeOnly) return undefined
+   *   }
+   * }]
+   * ```
+   *
+   * @example Force all dates to plain strings
+   * ```ts
+   * transformers: [{
+   *   schema(node) {
+   *     if (node.type === 'date') return { ...node, type: 'string' }
+   *   }
+   * }]
+   * ```
+   */
+  transformers?: Array<Visitor>
 }
 
 type ResolvedOptions = {
@@ -302,11 +320,17 @@ type ResolvedOptions = {
   enumKeyCasing: NonNullable<Options['enumKeyCasing']>
   optionalType: NonNullable<Options['optionalType']>
   arrayType: NonNullable<Options['arrayType']>
-  transformers: NonNullable<Options['transformers']>
   syntaxType: NonNullable<Options['syntaxType']>
   paramsCasing: Options['paramsCasing']
   legacy: NonNullable<Options['legacy']>
   resolver: ResolverTs
+  /**
+   * The resolver without user naming overrides applied.
+   * Used internally to derive stable names for unnamed enums and grouped params
+   * so that the schema tree stays consistent regardless of `transformers.name` / custom resolvers.
+   */
+  baseResolver: ResolverTs
+  transformers: Array<Visitor>
 }
 
 export type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, never, ResolvePathOptions, ResolverTs>