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

package/src/generators/typeGeneratorLegacy.tsx

@@ -0,0 +1,348 @@
+import path from 'node:path'
+import { pascalCase } from '@internals/utils'
+import { caseParams, composeTransformers, createProperty, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
+import { defineGenerator, getMode } from '@kubb/core'
+import { File } from '@kubb/react-fabric'
+import { Type } from '../components/Type.tsx'
+import { ENUM_TYPES_WITH_KEY_SUFFIX } from '../constants.ts'
+import { resolverTsLegacy } from '../resolvers/resolverTsLegacy.ts'
+import type { PluginTs, ResolverTs } from '../types'
+
+type BuildGroupedParamsSchemaOptions = {
+  params: Array<ParameterNode>
+  parentName?: string
+}
+
+function buildGroupedParamsSchema({ params, parentName }: BuildGroupedParamsSchemaOptions): SchemaNode {
+  return createSchema({
+    type: 'object',
+    properties: params.map((param) => {
+      let schema = param.schema
+      if (narrowSchema(schema, 'enum') && !schema.name && parentName) {
+        schema = { ...schema, name: pascalCase([parentName, param.name, 'enum'].join(' ')) }
+      }
+      return createProperty({
+        name: param.name,
+        required: param.required,
+        schema,
+      })
+    }),
+  })
+}
+
+type BuildOperationSchemaOptions = {
+  node: OperationNode
+  resolver: ResolverTs
+}
+
+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', required: true, schema: responseSchema })]
+
+  if (!isGet && node.requestBody?.schema) {
+    properties.push(
+      createProperty({
+        name: 'Request',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveDataTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'query') && resolver.resolveQueryParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'QueryParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveQueryParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'path') && resolver.resolvePathParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'PathParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolvePathParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  if (node.parameters.some((p) => p.in === 'header') && resolver.resolveHeaderParamsTypedName) {
+    properties.push(
+      createProperty({
+        name: 'HeaderParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveHeaderParamsTypedName(node) }),
+      }),
+    )
+  }
+
+  properties.push(createProperty({ name: 'Errors', required: true, schema: errorsSchema }))
+
+  return createSchema({ type: 'object', properties })
+}
+
+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) })),
+  })
+}
+
+function nameUnnamedEnums(node: SchemaNode, parentName: string): SchemaNode {
+  return transform(node, {
+    schema(n) {
+      const enumNode = narrowSchema(n, 'enum')
+      if (enumNode && !enumNode.name) {
+        return { ...enumNode, 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
+    },
+  })
+}
+
+export const typeGeneratorLegacy = defineGenerator<PluginTs>({
+  name: 'typescript-legacy',
+  type: 'react',
+  Operation({ node, adapter, options, config }) {
+    const { enumType, enumTypeSuffix, enumKeyCasing, optionalType, arrayType, syntaxType, paramsCasing, group, output, resolver, transformers = [] } = options
+
+    const root = path.resolve(config.root, config.output.path)
+    const mode = getMode(path.resolve(root, output.path))
+
+    const file = resolver.resolveFile({ name: node.operationId, extname: '.ts', tag: node.tags[0] ?? 'default', path: node.path }, { root, output, group })
+    const params = caseParams(node.parameters, paramsCasing)
+
+    function renderSchemaType({
+      node: schemaNode,
+      name,
+      typedName,
+      description,
+      keysToOmit,
+    }: {
+      node: SchemaNode | null
+      name: string
+      typedName: string
+      description?: string
+      keysToOmit?: Array<string>
+    }) {
+      if (!schemaNode) {
+        return null
+      }
+
+      const transformedNode = transform(schemaNode, composeTransformers(...transformers))
+
+      const imports = adapter.getImports(transformedNode, (schemaName) => ({
+        name: resolver.default(schemaName, 'type'),
+        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+      }))
+
+      return (
+        <>
+          {mode === 'split' &&
+            imports.map((imp) => <File.Import key={[name, imp.path, imp.isTypeOnly].join('-')} root={file.path} path={imp.path} name={imp.name} isTypeOnly />)}
+          <Type
+            name={name}
+            typedName={typedName}
+            node={transformedNode}
+            description={description}
+            enumType={enumType}
+            enumTypeSuffix={enumTypeSuffix}
+            enumKeyCasing={enumKeyCasing}
+            optionalType={optionalType}
+            arrayType={arrayType}
+            syntaxType={syntaxType}
+            resolver={resolver}
+            keysToOmit={keysToOmit}
+          />
+        </>
+      )
+    }
+
+    const pathParams = params.filter((p) => p.in === 'path')
+    const queryParams = params.filter((p) => p.in === 'query')
+    const headerParams = params.filter((p) => p.in === 'header')
+
+    const responseTypes = node.responses.map((res) => {
+      const responseName = resolver.resolveResponseStatusName(node, res.statusCode)
+      const baseResponseName = resolverTsLegacy.resolveResponseStatusName(node, res.statusCode)
+
+      return renderSchemaType({
+        node: res.schema ? nameUnnamedEnums(res.schema, baseResponseName) : res.schema,
+        name: responseName,
+        typedName: resolver.resolveResponseStatusTypedName(node, res.statusCode),
+        description: res.description,
+        keysToOmit: res.keysToOmit,
+      })
+    })
+
+    const requestType = node.requestBody?.schema
+      ? renderSchemaType({
+          node: nameUnnamedEnums(node.requestBody.schema, resolverTsLegacy.resolveDataName(node)),
+          name: resolver.resolveDataName(node),
+          typedName: resolver.resolveDataTypedName(node),
+          description: node.requestBody.description ?? node.requestBody.schema.description,
+          keysToOmit: node.requestBody.keysToOmit,
+        })
+      : null
+
+    const legacyParamTypes = [
+      pathParams.length > 0
+        ? renderSchemaType({
+            node: buildGroupedParamsSchema({ params: pathParams, parentName: resolverTsLegacy.resolvePathParamsName!(node) }),
+            name: resolver.resolvePathParamsName!(node),
+            typedName: resolver.resolvePathParamsTypedName!(node),
+          })
+        : null,
+      queryParams.length > 0
+        ? renderSchemaType({
+            node: buildGroupedParamsSchema({ params: queryParams, parentName: resolverTsLegacy.resolveQueryParamsName!(node) }),
+            name: resolver.resolveQueryParamsName!(node),
+            typedName: resolver.resolveQueryParamsTypedName!(node),
+          })
+        : null,
+      headerParams.length > 0
+        ? renderSchemaType({
+            node: buildGroupedParamsSchema({ params: headerParams, parentName: resolverTsLegacy.resolveHeaderParamsName!(node) }),
+            name: resolver.resolveHeaderParamsName!(node),
+            typedName: resolver.resolveHeaderParamsTypedName!(node),
+          })
+        : null,
+    ]
+
+    const legacyResponsesType = renderSchemaType({
+      node: buildLegacyResponsesSchemaNode({ node, resolver }),
+      name: resolver.resolveResponsesName(node),
+      typedName: resolver.resolveResponsesTypedName(node),
+    })
+
+    const legacyResponseType = renderSchemaType({
+      node: buildLegacyResponseUnionSchemaNode({ node, resolver }),
+      name: resolver.resolveResponseName(node),
+      typedName: resolver.resolveResponseTypedName(node),
+    })
+
+    return (
+      <File
+        baseName={file.baseName}
+        path={file.path}
+        meta={file.meta}
+        banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
+        footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
+      >
+        {legacyParamTypes}
+        {responseTypes}
+        {requestType}
+        {legacyResponseType}
+        {legacyResponsesType}
+      </File>
+    )
+  },
+  Schema({ node, adapter, options, config }) {
+    const { enumType, enumTypeSuffix, enumKeyCasing, syntaxType, optionalType, arrayType, output, group, resolver, transformers = [] } = options
+
+    const root = path.resolve(config.root, config.output.path)
+    const mode = getMode(path.resolve(root, output.path))
+
+    if (!node.name) {
+      return
+    }
+
+    const transformedNode = transform(node, composeTransformers(...transformers))
+
+    const imports = adapter.getImports(transformedNode, (schemaName) => ({
+      name: resolver.default(schemaName, 'type'),
+      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+    }))
+
+    const isEnumSchema = !!narrowSchema(node, schemaTypes.enum)
+
+    const typedName =
+      ENUM_TYPES_WITH_KEY_SUFFIX.has(enumType) && isEnumSchema ? resolver.resolveEnumKeyTypedName(node, enumTypeSuffix) : resolver.resolveTypedName(node.name)
+
+    const type = {
+      name: resolver.resolveName(node.name),
+      typedName,
+      file: resolver.resolveFile({ name: node.name, extname: '.ts' }, { root, output, group }),
+    } as const
+
+    return (
+      <File
+        baseName={type.file.baseName}
+        path={type.file.path}
+        meta={type.file.meta}
+        banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
+        footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
+      >
+        {mode === 'split' &&
+          imports.map((imp) => (
+            <File.Import key={[node.name, imp.path, imp.isTypeOnly].join('-')} root={type.file.path} path={imp.path} name={imp.name} isTypeOnly />
+          ))}
+        <Type
+          name={type.name}
+          typedName={type.typedName}
+          node={transformedNode}
+          enumType={enumType}
+          enumTypeSuffix={enumTypeSuffix}
+          enumKeyCasing={enumKeyCasing}
+          optionalType={optionalType}
+          arrayType={arrayType}
+          syntaxType={syntaxType}
+          resolver={resolver}
+        />
+      </File>
+    )
+  },
+})

package/src/index.ts

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

package/src/plugin.ts

@@ -1,13 +1,30 @@
 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/index.ts'
+import { createPlugin, getBarrelFiles, renderOperation, renderSchema } from '@kubb/core'
 import { getPreset } from './presets.ts'
 import type { PluginTs } from './types.ts'
 
+/**
+ * Canonical plugin name for `@kubb/plugin-ts`, used to identify the plugin in driver lookups and warnings.
+ */
 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`.
+ *
+ * @example
+ * ```ts
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   plugins: [pluginTs({ output: { path: 'types' }, enumType: 'asConst' })],
+ * })
+ * ```
+ */
 export const pluginTs = createPlugin<PluginTs>((options) => {
   const {
     output = { path: 'types', barrelType: 'named' },
@@ -16,78 +33,56 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
     include,
     override = [],
     enumType = 'asConst',
+    enumTypeSuffix = 'Key',
     enumKeyCasing = 'none',
     optionalType = 'questionToken',
     arrayType = 'array',
     syntaxType = 'type',
     paramsCasing,
-    generators = [typeGenerator].filter(Boolean),
     compatibilityPreset = 'default',
-    resolvers: userResolvers,
+    resolvers: userResolvers = [],
     transformers: userTransformers = [],
+    generators: userGenerators = [],
   } = options
 
-  const { baseResolver, resolver, transformers } = getPreset(compatibilityPreset, {
+  const { resolver, transformers, generators } = getPreset(compatibilityPreset, {
     resolvers: userResolvers,
     transformers: userTransformers,
+    generators: userGenerators,
   })
 
   let resolveNameWarning = false
+  let resolvePathWarning = false
 
   return {
     name: pluginTsName,
     options: {
       output,
       optionalType,
+      group,
       arrayType,
       enumType,
+      enumTypeSuffix,
       enumKeyCasing,
       syntaxType,
-      group,
-      override,
       paramsCasing,
-      compatibilityPreset,
-      baseResolver,
       resolver,
       transformers,
     },
     resolvePath(baseName, pathMode, options) {
-      const root = path.resolve(this.config.root, this.config.output.path)
-      const mode = pathMode ?? getMode(path.resolve(root, output.path))
-
-      if (mode === 'single') {
-        /**
-         * when output is a file then we will always append to the same file(output file), see fileManager.addOrAppend
-         * Other plugins then need to call addOrAppend instead of just add from the fileManager class
-         */
-        return path.resolve(root, output.path)
-      }
-
-      if (group && (options?.group?.path || options?.group?.tag)) {
-        const groupName: Group['name'] = group?.name
-          ? group.name
-          : (ctx) => {
-              if (group?.type === 'path') {
-                return `${ctx.group.split('/')[1]}`
-              }
-              return `${camelCase(ctx.group)}Controller`
-            }
-
-        return path.resolve(
-          root,
-          output.path,
-          groupName({
-            group: group.type === 'path' ? options.group.path! : options.group.tag!,
-          }),
-          baseName,
-        )
+      if (!resolvePathWarning) {
+        this.driver.events.emit('warn', 'Do not use resolvePath for pluginTs, use resolverTs.resolvePath instead')
+        resolvePathWarning = true
       }
 
-      return path.resolve(root, output.path, baseName)
+      return resolver.resolvePath(
+        { baseName, pathMode, tag: options?.group?.tag, path: options?.group?.path },
+        { root: path.resolve(this.config.root, this.config.output.path), output, group },
+      )
     },
     resolveName(name, type) {
       if (!resolveNameWarning) {
-        this.driver.events.emit('warn', 'Do not use resolveName for pluginTs, use resolverTs instead')
+        this.driver.events.emit('warn', 'Do not use resolveName for pluginTs, use resolverTs.default instead')
         resolveNameWarning = true
       }
 
@@ -97,7 +92,6 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
       const { config, fabric, plugin, adapter, rootNode, driver, openInStudio } = this
 
       const root = path.resolve(config.root, config.output.path)
-      const mode = getMode(path.resolve(root, output.path))
 
       if (!adapter) {
         throw new Error('Plugin cannot work without adapter being set')
@@ -124,7 +118,6 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
                 Component: generator.Schema,
                 plugin,
                 driver,
-                mode,
               })
             }
           })
@@ -148,7 +141,6 @@ export const pluginTs = createPlugin<PluginTs>((options) => {
                 Component: generator.Operation,
                 plugin,
                 driver,
-                mode,
               })
             }
           })

package/src/presets.ts

@@ -1,23 +1,43 @@
 import type { Visitor } from '@kubb/ast/types'
-import { type CompatibilityPreset, definePreset, definePresets, getPreset as getCorePreset } from '@kubb/core'
+import { type CompatibilityPreset, definePreset, definePresets, type Generator, getPreset as getCorePreset } from '@kubb/core'
+import { typeGenerator, typeGeneratorLegacy } from './generators/index.ts'
 import { resolverTs, resolverTsLegacy } from './resolvers/index.ts'
-import type { ResolverTs } from './types.ts'
+import type { PluginTs, ResolverTs } from './types.ts'
 
+/**
+ * Built-in preset registry for `@kubb/plugin-ts`.
+ *
+ * - `default` — uses `resolverTs` and `typeGenerator` (current naming conventions).
+ * - `kubbV4` — uses `resolverTsLegacy` and `typeGeneratorLegacy` (Kubb v4 naming conventions).
+ */
 export const presets = definePresets<ResolverTs>({
-  default: definePreset('default', { resolvers: [resolverTs] }),
-  kubbV4: definePreset('kubbV4', { resolvers: [resolverTsLegacy] }),
+  default: definePreset('default', { resolvers: [resolverTs], generators: [typeGenerator] }),
+  kubbV4: definePreset('kubbV4', { resolvers: [resolverTsLegacy], generators: [typeGeneratorLegacy] }),
 })
 
 type GetPresetOptions = {
-  resolvers?: Array<ResolverTs>
-  transformers?: Array<Visitor>
+  resolvers: Array<ResolverTs>
+  transformers: Array<Visitor>
+  generators: Array<Generator<PluginTs>>
 }
 
-export function getPreset(preset: CompatibilityPreset, { resolvers, transformers }: GetPresetOptions = {}) {
+/**
+ * Resolves a compatibility preset for `plugin-ts`, merging user-supplied resolvers,
+ * transformers, and generators on top of the built-in preset defaults.
+ *
+ * `resolverTs` is always prepended to the resolver list as the baseline.
+ *
+ * @example
+ * ```ts
+ * const preset = getPreset('kubbV4', { resolvers: [], transformers: [], generators: [] })
+ * ```
+ */
+export function getPreset(preset: CompatibilityPreset, { resolvers, transformers, generators }: GetPresetOptions) {
   return getCorePreset({
     preset,
     presets,
     resolvers: [resolverTs, ...(resolvers ?? [])],
     transformers,
+    generators,
   })
 }

package/src/printers/index.ts

@@ -0,0 +1 @@
+export { printerTs } from './printerTs.ts'