@kubb/plugin-ts 5.0.0-alpha.11 → 5.0.0-alpha.13

package/src/generators/utils.ts

@@ -0,0 +1,300 @@
+import { pascalCase } from '@internals/utils'
+import { createProperty, createSchema, narrowSchema, transform } 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
+}
+
+/**
+ * Builds an `ObjectSchemaNode` for a group of parameters (path/query/header).
+ * Each property is a `ref` schema pointing to the individually-resolved parameter type.
+ * The ref name includes the parameter location so generated type names follow
+ * the `<OperationId><Location><ParamName>` convention.
+ */
+export function buildParamsSchema({ params, node, resolver }: BuildParamsSchemaOptions): SchemaNode {
+  return createSchema({
+    type: 'object',
+    properties: params.map((param) =>
+      createProperty({
+        name: param.name,
+        schema: createSchema({
+          type: 'ref',
+          name: resolver.resolveParamName(node, param),
+          optional: !param.required,
+        }),
+      }),
+    ),
+  })
+}
+
+type BuildOperationSchemaOptions = {
+  node: OperationNode
+  resolver: ResolverTs
+}
+
+/**
+ * Builds an `ObjectSchemaNode` representing the `<OperationId>RequestConfig` type:
+ * - `data`         → request body ref (optional) or `never`
+ * - `pathParams`   → inline object of path param refs, or `never`
+ * - `queryParams`  → inline object of query param refs (optional), or `never`
+ * - `headerParams` → inline object of header param refs (optional), or `never`
+ * - `url`          → Express-style template literal (plugin-ts extension, handled by printer)
+ */
+export function buildDataSchemaNode({ 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.resolveDataTypedName(node),
+              optional: true,
+            })
+          : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'pathParams',
+        schema: pathParams.length > 0 ? buildParamsSchema({ params: pathParams, node, resolver }) : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'queryParams',
+        schema:
+          queryParams.length > 0
+            ? createSchema({ ...buildParamsSchema({ params: queryParams, node, resolver }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'headerParams',
+        schema:
+          headerParams.length > 0
+            ? createSchema({ ...buildParamsSchema({ params: headerParams, node, resolver }), optional: true })
+            : createSchema({ type: 'never', optional: true }),
+      }),
+      createProperty({
+        name: 'url',
+        schema: createSchema({ type: 'url', path: node.path }),
+      }),
+    ],
+  })
+}
+
+/**
+ * Builds an `ObjectSchemaNode` representing `<OperationId>Responses` — keyed by HTTP status code.
+ * Numeric status codes produce unquoted numeric keys (e.g. `200:`).
+ * All responses are included; those without a schema are represented as a ref to a `never` type.
+ */
+export function buildResponsesSchemaNode({ 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),
+        schema: createSchema({
+          type: 'ref',
+          name: resolver.resolveResponseStatusTypedName(node, res.statusCode),
+        }),
+      }),
+    ),
+  })
+}
+
+/**
+ * Builds a `UnionSchemaNode` representing `<OperationId>Response` — all response types in union format.
+ * Returns `null` when the operation has no responses with schemas.
+ */
+export function buildResponseUnionSchemaNode({ 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.resolveResponseStatusTypedName(node, res.statusCode),
+      }),
+    ),
+  })
+}
+
+type BuildGroupedParamsSchemaOptions = {
+  params: Array<ParameterNode>
+  /**
+   * Parent type name (e.g. `FindPetsByStatusQueryParams`) used to derive enum names
+   * for inline enum properties (e.g. `FindPetsByStatusQueryParamsStatusEnum`).
+   */
+  parentName?: string
+}
+
+/**
+ * Builds an `ObjectSchemaNode` for a grouped parameters type (path/query/header) in legacy mode.
+ * Each property directly embeds the parameter's schema inline (not a ref).
+ * Used to generate `<OperationId>PathParams`, `<OperationId>QueryParams`, `<OperationId>HeaderParams`.
+ * @deprecated Legacy only — will be removed in v6.
+ */
+export function buildGroupedParamsSchema({ params, parentName }: BuildGroupedParamsSchemaOptions): SchemaNode {
+  return createSchema({
+    type: 'object',
+    properties: params.map((param) => {
+      let schema = { ...param.schema, optional: !param.required } as SchemaNode
+      // Name unnamed enum properties so they are emitted as enum declarations
+      if (narrowSchema(schema, 'enum') && !schema.name && parentName) {
+        schema = { ...schema, name: pascalCase([parentName, param.name, 'enum'].join(' ')) }
+      }
+      return createProperty({
+        name: param.name,
+        schema,
+      })
+    }),
+  })
+}
+
+/**
+ * Builds the legacy wrapper `ObjectSchemaNode` for `<OperationId>Mutation` / `<OperationId>Query`.
+ * Structure: `{ Response, Request?, QueryParams?, PathParams?, HeaderParams?, Errors }`.
+ * Mirrors the v4 naming convention where this type acts as a namespace for the operation's shapes.
+ *
+ * @deprecated Legacy only — will be removed in v6.
+ */
+export function buildLegacyResponsesSchemaNode({ node, resolver }: BuildOperationSchemaOptions): SchemaNode | null {
+  const isGet = node.method.toLowerCase() === 'get'
+  const successResponses = node.responses.filter((res) => {
+    const code = Number(res.statusCode)
+    return !Number.isNaN(code) && code >= 200 && code < 300
+  })
+  const errorResponses = node.responses.filter((res) => res.statusCode === 'default' || Number(res.statusCode) >= 400)
+
+  const responseSchema =
+    successResponses.length > 0
+      ? successResponses.length === 1
+        ? createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, successResponses[0]!.statusCode) })
+        : createSchema({
+            type: 'union',
+            members: successResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, res.statusCode) })),
+          })
+      : createSchema({ type: 'any' })
+
+  const errorsSchema =
+    errorResponses.length > 0
+      ? errorResponses.length === 1
+        ? createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, errorResponses[0]!.statusCode) })
+        : createSchema({
+            type: 'union',
+            members: errorResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, res.statusCode) })),
+          })
+      : createSchema({ type: 'any' })
+
+  const properties = [createProperty({ name: 'Response', schema: responseSchema })]
+
+  if (!isGet && node.requestBody?.schema) {
+    properties.push(
+      createProperty({
+        name: 'Request',
+        schema: createSchema({ type: 'ref', name: resolver.resolveDataTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'query') && resolver.resolveQueryParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'QueryParams',
+        schema: createSchema({ type: 'ref', name: resolver.resolveQueryParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'path') && resolver.resolvePathParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'PathParams',
+        schema: createSchema({ type: 'ref', name: resolver.resolvePathParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'header') && resolver.resolveHeaderParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'HeaderParams',
+        schema: createSchema({ type: 'ref', name: resolver.resolveHeaderParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  properties.push(createProperty({ name: 'Errors', schema: errorsSchema }))
+
+  return createSchema({ type: 'object', properties })
+}
+
+/**
+ * Builds the legacy response union for `<OperationId>MutationResponse` / `<OperationId>QueryResponse`.
+ * In legacy mode this is the **success** response only (not the full union including errors).
+ * Returns an `any` schema when there is no success response, matching v4 behavior.
+ * @deprecated Legacy only — will be removed in v6.
+ */
+export function buildLegacyResponseUnionSchemaNode({ node, resolver }: BuildOperationSchemaOptions): SchemaNode {
+  const successResponses = node.responses.filter((res) => {
+    const code = Number(res.statusCode)
+    return !Number.isNaN(code) && code >= 200 && code < 300
+  })
+
+  if (successResponses.length === 0) {
+    return createSchema({ type: 'any' })
+  }
+
+  if (successResponses.length === 1) {
+    return createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, successResponses[0]!.statusCode) })
+  }
+
+  return createSchema({
+    type: 'union',
+    members: successResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusTypedName(node, res.statusCode) })),
+  })
+}
+
+/**
+ * Names unnamed enum nodes within a schema tree based on the parent type name.
+ * Used in legacy mode to ensure inline enums in response/request schemas get
+ * extracted as named enum declarations (e.g. `DeletePet200Enum`).
+ *
+ * @deprecated Legacy only — will be removed in v6.
+ */
+export function nameUnnamedEnums(node: SchemaNode, parentName: string): SchemaNode {
+  return transform(node, {
+    schema(n) {
+      if (n.type === 'enum' && !n.name) {
+        return { ...n, name: pascalCase([parentName, 'enum'].join(' ')) }
+      }
+      return undefined
+    },
+    property(p) {
+      const enumNode = narrowSchema(p.schema, 'enum')
+      if (enumNode && !enumNode.name) {
+        return {
+          ...p,
+          schema: { ...enumNode, name: pascalCase([parentName, p.name, 'enum'].join(' ')) },
+        }
+      }
+      return undefined
+    },
+  })
+}

package/src/index.ts

@@ -1,3 +1,2 @@
 export { pluginTs, pluginTsName } from './plugin.ts'
-export { resolverTs } from './resolverTs.ts'
 export type { PluginTs } from './types.ts'

package/src/plugin.ts

@@ -2,9 +2,8 @@ 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 { OperationGenerator, pluginOasName, SchemaGenerator } from '@kubb/plugin-oas'
-import { typeGenerator, typeGeneratorV2 } from './generators'
-import { resolverTs } from './resolverTs.ts'
+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']
@@ -18,45 +17,50 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
     override = [],
     enumType = 'asConst',
     enumKeyCasing = 'none',
-    enumSuffix = 'enum',
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
     optionalType = 'questionToken',
     arrayType = 'array',
-    emptySchemaType = unknownType,
     syntaxType = 'type',
     transformers = {},
     paramsCasing,
-    generators = [typeGenerator, typeGeneratorV2].filter(Boolean),
-    contentType,
-    UNSTABLE_NAMING,
+    generators = [typeGenerator].filter(Boolean),
+    legacy = false,
   } = options
 
-  // @deprecated Will be removed in v5 when collisionDetection defaults to true
-  const usedEnumNames = {}
+  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
+
+  let resolveNameWarning = false
 
   return {
     name: pluginTsName,
     options: {
       output,
       transformers,
-      dateType,
-      integerType,
       optionalType,
       arrayType,
       enumType,
       enumKeyCasing,
-      enumSuffix,
-      unknownType,
-      emptySchemaType,
       syntaxType,
       group,
       override,
       paramsCasing,
-      usedEnumNames,
+      legacy,
+      resolver,
+      baseResolver,
     },
-    pre: [pluginOasName],
     resolvePath(baseName, pathMode, options) {
       const root = path.resolve(this.config.root, this.config.output.path)
       const mode = pathMode ?? getMode(path.resolve(root, output.path))
@@ -92,13 +96,12 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
       return path.resolve(root, output.path, baseName)
     },
     resolveName(name, type) {
-      const resolvedName = resolverTs.default(name, type)
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
+      if (!resolveNameWarning) {
+        this.driver.events.emit('warn', 'Do not use resolveName for pluginTs, use resolverTs instead')
+        resolveNameWarning = true
       }
 
-      return resolvedName
+      return resolver.default(name, type)
     },
     async install() {
       const { config, fabric, plugin, adapter, rootNode, driver, openInStudio } = this
@@ -106,114 +109,66 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
       const root = path.resolve(config.root, config.output.path)
       const mode = getMode(path.resolve(root, output.path))
 
-      if (adapter) {
-        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 = resolverTs.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 Promise.all(writeTasks)
-            },
-            async operation(operationNode) {
-              const writeTasks = generators.map(async (generator) => {
-                if (generator.type === 'react' && generator.version === '2') {
-                  const options = resolverTs.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,
-                  })
-                }
-              })
+      if (!adapter) {
+        throw new Error('Plugin cannot work without adapter being set')
+      }
 
-              await Promise.all(writeTasks)
-            },
-          },
-          { depth: 'shallow' },
-        )
+      await openInStudio({ ast: true })
 
-        const barrelFiles = await getBarrelFiles(this.fabric.files, {
-          type: output.barrelType ?? 'named',
-          root,
-          output,
-          meta: {
-            pluginName: this.plugin.name,
-          },
-        })
+      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 })
 
-        await this.upsertFile(...barrelFiles)
+                if (options === null) {
+                  return
+                }
 
-        return
-      }
+                await renderSchema(schemaNode, {
+                  options,
+                  adapter,
+                  config,
+                  fabric,
+                  Component: generator.Schema,
+                  plugin,
+                  driver,
+                  mode,
+                })
+              }
+            })
 
-      // v1 flow
-
-      const oas = await this.getOas()
-
-      const schemaGenerator = new SchemaGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        include: undefined,
-        override,
-        mode,
-        output: output.path,
-      })
+            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 })
 
-      const schemaFiles = await schemaGenerator.build(...generators)
-      await this.upsertFile(...schemaFiles)
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        driver: this.driver,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-        UNSTABLE_NAMING,
-      })
+                if (options === null) {
+                  return
+                }
+
+                await renderOperation(operationNode, {
+                  options,
+                  adapter,
+                  config,
+                  fabric,
+                  Component: generator.Operation,
+                  plugin,
+                  driver,
+                  mode,
+                })
+              }
+            })
 
-      const operationFiles = await operationGenerator.build(...generators)
-      await this.upsertFile(...operationFiles)
+            await Promise.all(writeTasks)
+          },
+        },
+        { depth: 'shallow' },
+      )
 
       const barrelFiles = await getBarrelFiles(this.fabric.files, {
         type: output.barrelType ?? 'named',

package/src/printer.ts

@@ -1,4 +1,4 @@
-import { jsStringEscape, pascalCase, stringify } from '@internals/utils'
+import { jsStringEscape, stringify } from '@internals/utils'
 import { isPlainStringType } from '@kubb/ast'
 import type { ArraySchemaNode, SchemaNode } from '@kubb/ast/types'
 import type { PrinterFactoryOptions } from '@kubb/core'
@@ -6,7 +6,7 @@ import { definePrinter } from '@kubb/core'
 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'
-import type { PluginTs } from './types.ts'
+import type { PluginTs, ResolverTs } from './types.ts'
 
 type TsOptions = {
   /**
@@ -41,6 +41,10 @@ type TsOptions = {
    * Forces type-alias syntax even when `syntaxType` is `'interface'`.
    */
   keysToOmit?: Array<string>
+  /**
+   * Resolver used to transform raw schema names into valid TypeScript identifiers.
+   */
+  resolver: ResolverTs
 }
 
 /**
@@ -130,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}`
@@ -235,7 +242,14 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         if (!node.name) {
           return undefined
         }
-        return factory.createTypeReferenceNode(node.name, undefined)
+        // Parser-generated refs (with $ref) carry raw schema names that need resolving.
+        // Use the canonical name from the $ref path — node.name may have been overridden
+        // (e.g. by single-member allOf flatten using the property-derived child name).
+        // Inline refs (without $ref) from utils already carry resolved type names.
+        const refName = node.ref ? (node.ref.split('/').at(-1) ?? node.name) : node.name
+        const name = node.ref ? this.options.resolver.default(refName, 'type') : refName
+
+        return factory.createTypeReferenceNode(name, undefined)
       },
       enum(node) {
         const values = node.namedEnumValues?.map((v) => v.value) ?? node.enumValues ?? []
@@ -249,7 +263,7 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
           return factory.createUnionDeclaration({ withParentheses: true, nodes: literalNodes }) ?? undefined
         }
 
-        const resolvedName = pascalCase(node.name)
+        const resolvedName = this.options.resolver.default(node.name, 'type')
         const typeName = ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) ? `${resolvedName}Key` : resolvedName
 
         return factory.createTypeReferenceNode(typeName, undefined)

package/src/resolvers/index.ts

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