@kubb/plugin-ts 5.0.0-alpha.3 → 5.0.0-alpha.31

package/src/generators/typeGeneratorLegacy.tsx

@@ -0,0 +1,349 @@
+import { pascalCase } from '@internals/utils'
+import { caseParams, createProperty, createSchema, narrowSchema, schemaTypes, transform } from '@kubb/ast'
+import type { OperationNode, ParameterNode, SchemaNode } from '@kubb/ast/types'
+import { defineGenerator } 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 { printerTs } from '../printers/printerTs.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 = {
+  resolver: ResolverTs
+}
+
+function buildLegacyResponsesSchemaNode(node: OperationNode, { 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.resolveResponseStatusName(node, successResponses[0]!.statusCode) })
+        : createSchema({
+            type: 'union',
+            members: successResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) })),
+          })
+      : createSchema({ type: 'any', primitive: undefined })
+
+  const errorsSchema =
+    errorResponses.length > 0
+      ? errorResponses.length === 1
+        ? createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, errorResponses[0]!.statusCode) })
+        : createSchema({
+            type: 'union',
+            members: errorResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, res.statusCode) })),
+          })
+      : createSchema({ type: 'any', primitive: undefined })
+
+  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.resolveDataName(node) }),
+      }),
+    )
+  }
+
+  const queryParam = node.parameters.find((p) => p.in === 'query')
+  if (queryParam) {
+    properties.push(
+      createProperty({
+        name: 'QueryParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveQueryParamsName(node, queryParam) }),
+      }),
+    )
+  }
+
+  const pathParam = node.parameters.find((p) => p.in === 'path')
+  if (pathParam) {
+    properties.push(
+      createProperty({
+        name: 'PathParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolvePathParamsName(node, pathParam) }),
+      }),
+    )
+  }
+
+  const headerParam = node.parameters.find((p) => p.in === 'header')
+  if (headerParam) {
+    properties.push(
+      createProperty({
+        name: 'HeaderParams',
+        required: true,
+        schema: createSchema({ type: 'ref', name: resolver.resolveHeaderParamsName(node, headerParam) }),
+      }),
+    )
+  }
+
+  properties.push(createProperty({ name: 'Errors', required: true, schema: errorsSchema }))
+
+  return createSchema({ type: 'object', properties })
+}
+
+function buildLegacyResponseUnionSchemaNode(node: OperationNode, { 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', primitive: undefined })
+  }
+
+  if (successResponses.length === 1) {
+    return createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(node, successResponses[0]!.statusCode) })
+  }
+
+  return createSchema({
+    type: 'union',
+    members: successResponses.map((res) => createSchema({ type: 'ref', name: resolver.resolveResponseStatusName(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',
+  schema(node, options) {
+    const { enumType, enumTypeSuffix, enumKeyCasing, syntaxType, optionalType, arrayType, output, group } = options
+    const { adapter, config, resolver, root } = this
+
+    if (!node.name) {
+      return
+    }
+
+    const mode = this.getMode(output)
+
+    const imports = adapter.getImports(node, (schemaName) => ({
+      name: resolver.resolveTypeName(schemaName),
+      path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+    }))
+
+    const isEnumSchema = !!narrowSchema(node, 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 }),
+    } as const
+
+    const schemaPrinter = printerTs({
+      optionalType,
+      arrayType,
+      enumType,
+      enumTypeSuffix,
+      name: meta.name,
+      syntaxType,
+      description: node.description,
+      resolver,
+    })
+
+    return (
+      <File
+        baseName={meta.file.baseName}
+        path={meta.file.path}
+        meta={meta.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={meta.file.path} path={imp.path} name={imp.name} isTypeOnly />
+          ))}
+        <Type
+          name={meta.name}
+          node={node}
+          enumType={enumType}
+          enumTypeSuffix={enumTypeSuffix}
+          enumKeyCasing={enumKeyCasing}
+          resolver={resolver}
+          printer={schemaPrinter}
+        />
+      </File>
+    )
+  },
+  operation(node, options) {
+    const { enumType, enumTypeSuffix, enumKeyCasing, optionalType, arrayType, syntaxType, paramsCasing, group, output } = options
+    const { adapter, config, resolver, root } = this
+
+    const mode = this.getMode(output)
+    const params = 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 }),
+    } as const
+
+    function renderSchemaType({
+      schema,
+      name,
+      description,
+      keysToOmit,
+    }: {
+      schema: SchemaNode | null
+      name: string
+      description?: string
+      keysToOmit?: Array<string>
+    }) {
+      if (!schema) return null
+
+      const imports = adapter.getImports(schema, (schemaName) => ({
+        name: resolver.resolveTypeName(schemaName),
+        path: resolver.resolveFile({ name: schemaName, extname: '.ts' }, { root, output, group }).path,
+      }))
+
+      const opPrinter = printerTs({
+        optionalType,
+        arrayType,
+        enumType,
+        enumTypeSuffix,
+        name,
+        syntaxType,
+        description,
+        keysToOmit,
+        resolver,
+      })
+
+      return (
+        <>
+          {mode === 'split' &&
+            imports.map((imp) => (
+              <File.Import key={[name, imp.path, imp.isTypeOnly].join('-')} root={meta.file.path} path={imp.path} name={imp.name} isTypeOnly />
+            ))}
+          <Type
+            name={name}
+            node={schema}
+            enumType={enumType}
+            enumTypeSuffix={enumTypeSuffix}
+            enumKeyCasing={enumKeyCasing}
+            resolver={resolver}
+            printer={opPrinter}
+          />
+        </>
+      )
+    }
+
+    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({
+        schema: res.schema ? nameUnnamedEnums(res.schema, baseResponseName) : res.schema,
+        name: responseName,
+        description: res.description,
+        keysToOmit: res.keysToOmit,
+      })
+    })
+
+    const requestType = node.requestBody?.schema
+      ? renderSchemaType({
+          schema: nameUnnamedEnums(node.requestBody.schema, resolverTsLegacy.resolveDataName(node)),
+          name: resolver.resolveDataName(node),
+          description: node.requestBody.description ?? node.requestBody.schema.description,
+          keysToOmit: node.requestBody.keysToOmit,
+        })
+      : null
+
+    const legacyParamTypes = [
+      pathParams.length > 0
+        ? renderSchemaType({
+            schema: buildGroupedParamsSchema({ params: pathParams, parentName: resolverTsLegacy.resolvePathParamsName(node, pathParams[0]!) }),
+            name: resolver.resolvePathParamsName(node, pathParams[0]!),
+          })
+        : null,
+      queryParams.length > 0
+        ? renderSchemaType({
+            schema: buildGroupedParamsSchema({ params: queryParams, parentName: resolverTsLegacy.resolveQueryParamsName(node, queryParams[0]!) }),
+            name: resolver.resolveQueryParamsName(node, queryParams[0]!),
+          })
+        : null,
+      headerParams.length > 0
+        ? renderSchemaType({
+            schema: buildGroupedParamsSchema({ params: headerParams, parentName: resolverTsLegacy.resolveHeaderParamsName(node, headerParams[0]!) }),
+            name: resolver.resolveHeaderParamsName(node, headerParams[0]!),
+          })
+        : null,
+    ]
+
+    const legacyResponsesType = renderSchemaType({
+      schema: buildLegacyResponsesSchemaNode(node, { resolver }),
+      name: resolver.resolveResponsesName(node),
+    })
+
+    const legacyResponseType = renderSchemaType({
+      schema: buildLegacyResponseUnionSchemaNode(node, { resolver }),
+      name: resolver.resolveResponseName(node),
+    })
+
+    return (
+      <File
+        baseName={meta.file.baseName}
+        path={meta.file.path}
+        meta={meta.file.meta}
+        banner={resolver.resolveBanner(adapter.rootNode, { output, config })}
+        footer={resolver.resolveFooter(adapter.rootNode, { output, config })}
+      >
+        {legacyParamTypes}
+        {responseTypes}
+        {requestType}
+        {legacyResponseType}
+        {legacyResponsesType}
+      </File>
+    )
+  },
+})

package/src/index.ts

@@ -1,2 +1,10 @@
+export { Enum } from './components/Enum.tsx'
+export { Type } from './components/Type.tsx'
+export { typeGenerator } from './generators/typeGenerator.tsx'
 export { pluginTs, pluginTsName } from './plugin.ts'
-export type { PluginTs } from './types.ts'
+export { functionPrinter } from './printers/functionPrinter.ts'
+export type { PrinterTsFactory, PrinterTsNodes, PrinterTsOptions } from './printers/printerTs.ts'
+export { printerTs } from './printers/printerTs.ts'
+export { resolverTs } from './resolvers/resolverTs.ts'
+export { resolverTsLegacy } from './resolvers/resolverTsLegacy.ts'
+export type { PluginTs, ResolverTs } from './types.ts'

package/src/plugin.ts

@@ -1,14 +1,31 @@
-import path from 'node:path'
-import { camelCase, pascalCase } from '@internals/utils'
-import { walk } from '@kubb/ast'
-import { definePlugin, type Group, getBarrelFiles, getMode } from '@kubb/core'
-import { buildOperation, buildSchema, OperationGenerator, pluginOasName, SchemaGenerator } from '@kubb/plugin-oas'
-import { typeGenerator, typeGeneratorV2 } from './generators'
+import { camelCase } from '@internals/utils'
+import { createPlugin, type Group, getPreset, mergeGenerators } from '@kubb/core'
+import { version } from '../package.json'
+import { presets } 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']
 
-export const pluginTs = definePlugin<PluginTs>((options) => {
+/**
+ * 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' },
     group,
@@ -16,194 +33,99 @@ export const pluginTs = definePlugin<PluginTs>((options) => {
     include,
     override = [],
     enumType = 'asConst',
+    enumTypeSuffix = 'Key',
     enumKeyCasing = 'none',
-    enumSuffix = 'enum',
-    dateType = 'string',
-    integerType = 'number',
-    unknownType = 'any',
     optionalType = 'questionToken',
     arrayType = 'array',
-    emptySchemaType = unknownType,
     syntaxType = 'type',
-    transformers = {},
-    mapper = {},
     paramsCasing,
-    generators = [typeGenerator, typeGeneratorV2].filter(Boolean),
-    contentType,
-    UNSTABLE_NAMING,
+    printer,
+    compatibilityPreset = 'default',
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
-  // @deprecated Will be removed in v5 when collisionDetection defaults to true
-  const usedEnumNames = {}
+  const preset = getPreset({
+    preset: compatibilityPreset,
+    presets: presets,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators,
+  })
+
+  const generators = preset.generators ?? []
+  const mergedGenerator = mergeGenerators(generators)
+
+  let resolveNameWarning = false
+  let resolvePathWarning = false
 
   return {
     name: pluginTsName,
-    options: {
-      output,
-      transformers,
-      dateType,
-      integerType,
-      optionalType,
-      arrayType,
-      enumType,
-      enumKeyCasing,
-      enumSuffix,
-      unknownType,
-      emptySchemaType,
-      syntaxType,
-      group,
-      override,
-      mapper,
-      paramsCasing,
-      usedEnumNames,
+    version,
+    get resolver() {
+      return preset.resolver
     },
-    pre: [pluginOasName],
-    //resolveOptions(operation|schema): ResolvedOptions
-    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)
+    get transformer() {
+      return preset.transformer
+    },
+    get options() {
+      return {
+        output,
+        exclude,
+        include,
+        override,
+        optionalType,
+        group: group
+          ? ({
+              ...group,
+              name: (ctx) => {
+                if (group.type === 'path') {
+                  return `${ctx.group.split('/')[1]}`
+                }
+                return `${camelCase(ctx.group)}Controller`
+              },
+            } satisfies Group)
+          : undefined,
+        arrayType,
+        enumType,
+        enumTypeSuffix,
+        enumKeyCasing,
+        syntaxType,
+        paramsCasing,
+        printer,
       }
-
-      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,
-        )
+    },
+    resolvePath(baseName, pathMode, options) {
+      if (!resolvePathWarning) {
+        this.warn('Do not use resolvePath for pluginTs, use resolverTs.resolvePath instead')
+        resolvePathWarning = true
       }
 
-      return path.resolve(root, output.path, baseName)
+      return this.plugin.resolver.resolvePath(
+        { baseName, pathMode, tag: options?.group?.tag, path: options?.group?.path },
+        { root: this.root, output, group: this.plugin.options.group },
+      )
     },
     resolveName(name, type) {
-      const resolvedName = pascalCase(name, { isFile: type === 'file' })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
+      if (!resolveNameWarning) {
+        this.warn('Do not use resolveName for pluginTs, use resolverTs.default instead')
+        resolveNameWarning = true
       }
 
-      return resolvedName
+      return this.plugin.resolver.default(name, type)
     },
-    async install() {
-      const { config, fabric, plugin, adapter, rootNode, pluginManager, openInStudio } = this
-
-      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') {
-                  await buildSchema(schemaNode, {
-                    adapter,
-                    config,
-                    fabric,
-                    Component: generator.Schema,
-                    plugin,
-                    pluginManager,
-                    mode,
-                    version: generator.version,
-                  })
-                }
-              })
-
-              await writeTasks
-            },
-            async operation(operationNode) {
-              const writeTasks = generators.map(async (generator) => {
-                if (generator.type === 'react' && generator.version === '2') {
-                  await buildOperation(operationNode, {
-                    adapter,
-                    config,
-                    fabric,
-                    Component: generator.Operation,
-                    plugin,
-                    pluginManager,
-                    mode,
-                    version: generator.version,
-                  })
-                }
-              })
-
-              await writeTasks
-            },
-          },
-          { depth: 'shallow' },
-        )
-
-        return
-      }
-
-      // v1 flow
-
-      const oas = await this.getOas()
-
-      const schemaGenerator = new SchemaGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        pluginManager: this.pluginManager,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        include: undefined,
-        override,
-        mode,
-        output: output.path,
-      })
-
-      const schemaFiles = await schemaGenerator.build(...generators)
-      await this.upsertFile(...schemaFiles)
-
-      const operationGenerator = new OperationGenerator(this.plugin.options, {
-        fabric: this.fabric,
-        oas,
-        pluginManager: this.pluginManager,
-        events: this.events,
-        plugin: this.plugin,
-        contentType,
-        exclude,
-        include,
-        override,
-        mode,
-        UNSTABLE_NAMING,
-      })
-
-      const operationFiles = await operationGenerator.build(...generators)
-      await this.upsertFile(...operationFiles)
-
-      const barrelFiles = await getBarrelFiles(this.fabric.files, {
-        type: output.barrelType ?? 'named',
-        root,
-        output,
-        meta: {
-          pluginName: this.plugin.name,
-        },
-      })
-
-      await this.upsertFile(...barrelFiles)
+    async schema(node, options) {
+      return mergedGenerator.schema?.call(this, node, options)
+    },
+    async operation(node, options) {
+      return mergedGenerator.operation?.call(this, node, options)
+    },
+    async operations(nodes, options) {
+      return mergedGenerator.operations?.call(this, nodes, options)
+    },
+    async buildStart() {
+      await this.openInStudio({ ast: true })
     },
   }
 })

package/src/presets.ts

@@ -0,0 +1,28 @@
+import { definePresets } from '@kubb/core'
+import { typeGenerator } from './generators/typeGenerator.tsx'
+import { typeGeneratorLegacy } from './generators/typeGeneratorLegacy.tsx'
+import { printerTs } from './printers/printerTs.ts'
+import { resolverTs } from './resolvers/resolverTs.ts'
+import { resolverTsLegacy } from './resolvers/resolverTsLegacy.ts'
+import type { 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: {
+    name: 'default',
+    resolver: resolverTs,
+    generators: [typeGenerator],
+    printer: printerTs,
+  },
+  kubbV4: {
+    name: 'kubbV4',
+    resolver: resolverTsLegacy,
+    generators: [typeGeneratorLegacy],
+    printer: printerTs,
+  },
+})