@kubb/plugin-ts 5.0.0-alpha.8 → 5.0.0-beta.3

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 { createPlugin, type Group, getBarrelFiles, getMode, resolveOptions } from '@kubb/core'
-import { buildOperation, buildSchema, OperationGenerator, pluginOasName, SchemaGenerator } from '@kubb/plugin-oas'
-import { typeGenerator, typeGeneratorV2 } from './generators'
+import { camelCase } from '@internals/utils'
+import { definePlugin, type Group } from '@kubb/core'
+import { typeGenerator } from './generators/typeGenerator.tsx'
+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.
+ */
 export const pluginTsName = 'plugin-ts' satisfies PluginTs['name']
 
-export const pluginTs = createPlugin<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 = definePlugin<PluginTs>((options) => {
   const {
     output = { path: 'types', barrelType: 'named' },
     group,
@@ -16,216 +33,61 @@ export const pluginTs = createPlugin<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 = {},
     paramsCasing,
-    generators = [typeGenerator, typeGeneratorV2].filter(Boolean),
-    contentType,
-    UNSTABLE_NAMING,
+    printer,
+    resolver: userResolver,
+    transformer: userTransformer,
+    generators: userGenerators = [],
   } = options
 
-  // @deprecated Will be removed in v5 when collisionDetection defaults to true
-  const usedEnumNames = {}
+  const groupConfig = group
+    ? ({
+        ...group,
+        name: (ctx) => {
+          if (group.type === 'path') {
+            return `${ctx.group.split('/')[1]}`
+          }
+          return `${camelCase(ctx.group)}Controller`
+        },
+      } satisfies Group)
+    : undefined
 
   return {
     name: pluginTsName,
-    options: {
-      output,
-      transformers,
-      dateType,
-      integerType,
-      optionalType,
-      arrayType,
-      enumType,
-      enumKeyCasing,
-      enumSuffix,
-      unknownType,
-      emptySchemaType,
-      syntaxType,
-      group,
-      override,
-      paramsCasing,
-      usedEnumNames,
-    },
-    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))
-
-      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,
-        )
-      }
-
-      return path.resolve(root, output.path, baseName)
-    },
-    resolveName(name, type) {
-      const resolvedName = pascalCase(name, { isFile: type === 'file' })
-
-      if (type) {
-        return transformers?.name?.(resolvedName, type) || resolvedName
-      }
-
-      return resolvedName
-    },
-    async install() {
-      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) {
-        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 = resolveOptions(schemaNode, { options: plugin.options, exclude, include, override })
-
-                  if (options === null) {
-                    return
-                  }
-
-                  await buildSchema(schemaNode, {
-                    options,
-                    adapter,
-                    config,
-                    fabric,
-                    Component: generator.Schema,
-                    plugin,
-                    driver,
-                    mode,
-                    version: generator.version,
-                  })
-                }
-              })
-
-              await Promise.all(writeTasks)
-            },
-            async operation(operationNode) {
-              const writeTasks = generators.map(async (generator) => {
-                if (generator.type === 'react' && generator.version === '2') {
-                  const options = resolveOptions(operationNode, { options: plugin.options, exclude, include, override })
-
-                  if (options === null) {
-                    return
-                  }
-
-                  await buildOperation(operationNode, {
-                    options,
-                    adapter,
-                    config,
-                    fabric,
-                    Component: generator.Operation,
-                    plugin,
-                    driver,
-                    mode,
-                    version: generator.version,
-                  })
-                }
-              })
-
-              await Promise.all(writeTasks)
-            },
-          },
-          { depth: 'shallow' },
-        )
-
-        const barrelFiles = await getBarrelFiles(this.fabric.files, {
-          type: output.barrelType ?? 'named',
-          root,
+    options,
+    hooks: {
+      'kubb:plugin:setup'(ctx) {
+        ctx.setOptions({
           output,
-          meta: {
-            pluginName: this.plugin.name,
-          },
+          exclude,
+          include,
+          override,
+          optionalType,
+          group: groupConfig,
+          arrayType,
+          enumType,
+          enumTypeSuffix,
+          enumKeyCasing,
+          syntaxType,
+          paramsCasing,
+          printer,
         })
-
-        await this.upsertFile(...barrelFiles)
-
-        return
-      }
-
-      // 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,
-      })
-
-      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,
-      })
-
-      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)
+        ctx.setResolver(userResolver ? { ...resolverTs, ...userResolver } : resolverTs)
+        if (userTransformer) {
+          ctx.setTransformer(userTransformer)
+        }
+        ctx.addGenerator(typeGenerator)
+        for (const gen of userGenerators) {
+          ctx.addGenerator(gen)
+        }
+      },
     },
   }
 })
+
+export default pluginTs

package/src/printers/functionPrinter.ts

@@ -0,0 +1,197 @@
+import { ast } from '@kubb/core'
+import { PARAM_RANK } from '../constants.ts'
+
+/**
+ * Maps each function-printer handler key to its concrete node type.
+ */
+export type FunctionNodeByType = {
+  functionParameter: ast.FunctionParameterNode
+  parameterGroup: ast.ParameterGroupNode
+  functionParameters: ast.FunctionParametersNode
+  paramsType: ast.ParamsTypeNode
+}
+
+const kindToHandlerKey = {
+  FunctionParameter: 'functionParameter',
+  ParameterGroup: 'parameterGroup',
+  FunctionParameters: 'functionParameters',
+  ParamsType: 'paramsType',
+} satisfies Record<string, ast.FunctionNodeType>
+
+/**
+ * Creates a function-parameter printer factory.
+ *
+ * Uses `createPrinterFactory` and dispatches handlers by `node.kind`
+ * (for function nodes) rather than by `node.type` (for schema nodes).
+ */
+export const defineFunctionPrinter = ast.createPrinterFactory<ast.FunctionParamNode, ast.FunctionNodeType, FunctionNodeByType>(
+  (node) => kindToHandlerKey[node.kind],
+)
+
+export type FunctionPrinterOptions = {
+  /**
+   * Rendering modes supported by `functionPrinter`.
+   *
+   * | Mode          | Output example                              | Use case                        |
+   * |---------------|---------------------------------------------|---------------------------------|
+   * | `declaration` | `id: string, config: Config = {}`           | Function parameter declaration |
+   * | `call`        | `id, { method, url }`                       | Function call arguments |
+   * | `keys`        | `{ id, config }`                            | Key names only (destructuring) |
+   * | `values`      | `{ id: id, config: config }`                | Key/value object entries |
+   */
+  mode: 'declaration' | 'call' | 'keys' | 'values'
+  /**
+   * Optional transformation applied to every parameter name before printing.
+   */
+  transformName?: (name: string) => string
+  /**
+   * Optional transformation applied to every type string before printing.
+   */
+  transformType?: (type: string) => string
+}
+
+type DefaultPrinter = ast.PrinterFactoryOptions<'functionParameters', FunctionPrinterOptions, string>
+
+function rank(param: ast.FunctionParameterNode | ast.ParameterGroupNode): number {
+  if (param.kind === 'ParameterGroup') {
+    if (param.default) return PARAM_RANK.withDefault
+    const isOptional = param.optional ?? param.properties.every((p) => p.optional || p.default !== undefined)
+    return isOptional ? PARAM_RANK.optional : PARAM_RANK.required
+  }
+  if (param.rest) return PARAM_RANK.rest
+  if (param.default) return PARAM_RANK.withDefault
+  return param.optional ? PARAM_RANK.optional : PARAM_RANK.required
+}
+
+function sortParams(params: ReadonlyArray<ast.FunctionParameterNode | ast.ParameterGroupNode>): Array<ast.FunctionParameterNode | ast.ParameterGroupNode> {
+  return [...params].sort((a, b) => rank(a) - rank(b))
+}
+
+function sortChildParams(params: Array<ast.FunctionParameterNode>): Array<ast.FunctionParameterNode> {
+  return [...params].sort((a, b) => rank(a) - rank(b))
+}
+
+/**
+ * Default function-signature printer.
+ * Covers the four standard output modes used across Kubb plugins.
+ *
+ * @example
+ * ```ts
+ * const printer = functionPrinter({ mode: 'declaration' })
+ *
+ * const sig = createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'config', type: 'Config', optional: false, default: '{}' }),
+ *   ],
+ * })
+ *
+ * printer.print(sig)  // → "petId: string, config: Config = {}"
+ * ```
+ */
+export const functionPrinter = defineFunctionPrinter<DefaultPrinter>((options) => ({
+  name: 'functionParameters',
+  options,
+  nodes: {
+    paramsType(node) {
+      if (node.kind !== 'ParamsType') return null
+      if (node.variant === 'member') {
+        return `${node.base}['${node.key}']`
+      }
+      if (node.variant === 'struct') {
+        const parts = node.properties.map((p) => {
+          const typeStr = this.transform(p.type)
+          const key = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(p.name) ? p.name : JSON.stringify(p.name)
+          return p.optional ? `${key}?: ${typeStr}` : `${key}: ${typeStr}`
+        })
+        return `{ ${parts.join('; ')} }`
+      }
+      if (node.variant === 'reference') {
+        return node.name
+      }
+      return null
+    },
+    functionParameter(node) {
+      const { mode, transformName, transformType } = this.options
+      const name = transformName ? transformName(node.name) : node.name
+
+      const rawType = node.type ? this.transform(node.type) : undefined
+      const type = rawType != null && transformType ? transformType(rawType) : rawType
+
+      if (mode === 'keys' || mode === 'values') {
+        return node.rest ? `...${name}` : name
+      }
+
+      if (mode === 'call') {
+        return node.rest ? `...${name}` : name
+      }
+
+      if (node.rest) {
+        return type ? `...${name}: ${type}` : `...${name}`
+      }
+      if (type) {
+        if (node.optional) return `${name}?: ${type}`
+        return node.default ? `${name}: ${type} = ${node.default}` : `${name}: ${type}`
+      }
+      return node.default ? `${name} = ${node.default}` : name
+    },
+    parameterGroup(node) {
+      const { mode, transformName, transformType } = this.options
+      const sorted = sortChildParams(node.properties)
+      const isOptional = node.optional ?? sorted.every((p) => p.optional || p.default !== undefined)
+
+      if (node.inline) {
+        return sorted
+          .map((p) => this.transform(p))
+          .filter(Boolean)
+          .join(', ')
+      }
+
+      if (mode === 'keys' || mode === 'values') {
+        const keys = sorted.map((p) => p.name).join(', ')
+        return `{ ${keys} }`
+      }
+
+      if (mode === 'call') {
+        const keys = sorted.map((p) => p.name).join(', ')
+        return `{ ${keys} }`
+      }
+
+      const names = sorted.map((p) => {
+        const n = transformName ? transformName(p.name) : p.name
+
+        return n
+      })
+
+      const nameStr = names.length ? `{ ${names.join(', ')} }` : undefined
+      if (!nameStr) return null
+
+      let typeAnnotation: string | undefined = node.type ? (this.transform(node.type) ?? undefined) : undefined
+      if (!typeAnnotation) {
+        const typeParts = sorted
+          .filter((p) => p.type)
+          .map((p) => {
+            const rawT = p.type ? this.transform(p.type) : undefined
+            const t = rawT != null && transformType ? transformType(rawT) : rawT
+            return p.optional || p.default !== undefined ? `${p.name}?: ${t}` : `${p.name}: ${t}`
+          })
+        typeAnnotation = typeParts.length ? `{ ${typeParts.join('; ')} }` : undefined
+      }
+
+      if (typeAnnotation) {
+        if (isOptional) return `${nameStr}: ${typeAnnotation} = ${node.default ?? '{}'}`
+        return node.default ? `${nameStr}: ${typeAnnotation} = ${node.default}` : `${nameStr}: ${typeAnnotation}`
+      }
+
+      return node.default ? `${nameStr} = ${node.default}` : nameStr
+    },
+    functionParameters(node) {
+      const sorted = sortParams(node.params)
+
+      return sorted
+        .map((p) => this.transform(p))
+        .filter(Boolean)
+        .join(', ')
+    },
+  },
+}))