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

package/src/printers/functionPrinter.ts

@@ -0,0 +1,194 @@
+import type { PrinterFactoryOptions } from '@kubb/ast'
+import { createPrinterFactory } from '@kubb/ast'
+import type { FunctionNode, FunctionNodeType, FunctionParameterNode, FunctionParametersNode, ParameterGroupNode, TypeNode } from '@kubb/ast/types'
+
+/**
+ * Maps each function-printer handler key to its concrete node type.
+ */
+export type FunctionNodeByType = {
+  functionParameter: FunctionParameterNode
+  parameterGroup: ParameterGroupNode
+  functionParameters: FunctionParametersNode
+  type: TypeNode
+}
+
+const kindToHandlerKey = {
+  FunctionParameter: 'functionParameter',
+  ParameterGroup: 'parameterGroup',
+  FunctionParameters: 'functionParameters',
+  Type: 'type',
+} satisfies Record<string, 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 = createPrinterFactory<FunctionNode, 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 = PrinterFactoryOptions<'functionParameters', FunctionPrinterOptions, string>
+
+function rank(param: FunctionParameterNode | ParameterGroupNode): number {
+  if (param.kind === 'ParameterGroup') {
+    if (param.default) return 2
+    const isOptional = param.optional ?? param.properties.every((p) => p.optional || p.default !== undefined)
+    return isOptional ? 1 : 0
+  }
+  if (param.rest) return 3
+  if (param.default) return 2
+  return param.optional ? 1 : 0
+}
+
+function sortParams(params: ReadonlyArray<FunctionParameterNode | ParameterGroupNode>): Array<FunctionParameterNode | ParameterGroupNode> {
+  return [...params].sort((a, b) => rank(a) - rank(b))
+}
+
+function sortChildParams(params: Array<FunctionParameterNode>): Array<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: {
+    type(node) {
+      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)
+          return p.optional ? `${p.name}?: ${typeStr}` : `${p.name}: ${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(', ')
+    },
+  },
+}))

package/src/printers/printerTs.ts

@@ -37,7 +37,7 @@ type TsOptions = {
    * When set, `printer.print(node)` produces a full `type Name = …` declaration.
    * When omitted, `printer.print(node)` returns the raw type node.
    */
-  typeName?: string
+  name?: string
 
   /**
    * JSDoc `@description` comment added to the generated type or interface declaration.
@@ -52,6 +52,12 @@ type TsOptions = {
    * Resolver used to transform raw schema names into valid TypeScript identifiers.
    */
   resolver: ResolverTs
+  /**
+   * Names of top-level schemas that are enums.
+   * When set, the `ref` handler uses the suffixed type name (e.g. `StatusKey`) for enum refs
+   * instead of the plain PascalCase name, so imports align with what the enum file actually exports.
+   */
+  enumSchemaNames?: Set<string>
 }
 
 /**
@@ -254,7 +260,17 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         // (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
+
+        // When a Key suffix is configured, enum refs must use the suffixed name (e.g. `StatusKey`)
+        // so the reference matches what the enum file actually exports.
+        const isEnumRef =
+          node.ref && ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix && this.options.enumSchemaNames?.has(refName)
+
+        const name = isEnumRef
+          ? this.options.resolver.resolveEnumKeyName({ name: refName } as SchemaNode, this.options.enumTypeSuffix!)
+          : node.ref
+            ? this.options.resolver.default(refName, 'type')
+            : refName
 
         return factory.createTypeReferenceNode(name, undefined)
       },
@@ -272,7 +288,7 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
 
         const resolvedName =
           ENUM_TYPES_WITH_KEY_SUFFIX.has(this.options.enumType) && this.options.enumTypeSuffix
-            ? this.options.resolver.resolveEnumKeyTypedName(node as unknown as SchemaNode, this.options.enumTypeSuffix)
+            ? this.options.resolver.resolveEnumKeyName(node as unknown as SchemaNode, this.options.enumTypeSuffix)
             : this.options.resolver.default(node.name, 'type')
 
         return factory.createTypeReferenceNode(resolvedName, undefined)
@@ -360,16 +376,16 @@ export const printerTs = definePrinter<TsPrinter>((options) => {
         type = factory.createUnionDeclaration({ nodes: [type, factory.keywordTypeNodes.undefined] })
       }
 
-      // Without typeName, return the type node as-is (no declaration wrapping).
-      const { typeName, syntaxType = 'type', description, keysToOmit } = this.options
-      if (!typeName) {
+      // Without name, return the type node as-is (no declaration wrapping).
+      const { name, syntaxType = 'type', description, keysToOmit } = this.options
+      if (!name) {
         return safePrint(type)
       }
 
       const useTypeGeneration = syntaxType === 'type' || type.kind === factory.syntaxKind.union || !!keysToOmit?.length
 
       const typeNode = factory.createTypeDeclaration({
-        name: typeName,
+        name,
         isExportable: true,
         type: keysToOmit?.length
           ? factory.createOmitDeclaration({

package/src/resolvers/resolverTs.ts

@@ -19,8 +19,7 @@ function resolveName(name: string, type?: 'file' | 'function' | 'type' | 'const'
  * import { resolver } from '@kubb/plugin-ts'
  *
  * resolver.default('list pets', 'type')              // → 'ListPets'
- * resolver.resolveName('list pets status 200')        // → 'listPetsStatus200'
- * resolver.resolveTypedName('list pets status 200')   // → 'ListPetsStatus200'
+ * resolver.resolveName('list pets status 200')        // → 'ListPetsStatus200'
  * resolver.resolvePathName('list pets', 'file')       // → 'listPets'
  * ```
  */
@@ -34,74 +33,38 @@ export const resolverTs = defineResolver<PluginTs>(() => {
     resolveName(name) {
       return this.default(name, 'function')
     },
-    resolveTypedName(name) {
-      return this.default(name, 'type')
-    },
     resolvePathName(name, type) {
       return this.default(name, type)
     },
     resolveParamName(node, param) {
-      return this.resolveName(`${node.operationId} ${this.default(param.in)} ${param.name}`)
-    },
-    resolveParamTypedName(node, param) {
-      return this.resolveTypedName(`${node.operationId} ${this.default(param.in)} ${param.name}`)
+      return this.resolveName(`${node.operationId} ${param.in} ${param.name}`)
     },
     resolveResponseStatusName(node, statusCode) {
       return this.resolveName(`${node.operationId} Status ${statusCode}`)
     },
-    resolveResponseStatusTypedName(node, statusCode) {
-      return this.resolveTypedName(`${node.operationId} Status ${statusCode}`)
-    },
     resolveDataName(node) {
       return this.resolveName(`${node.operationId} Data`)
     },
-    resolveDataTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} Data`)
-    },
     resolveRequestConfigName(node) {
       return this.resolveName(`${node.operationId} RequestConfig`)
     },
-    resolveRequestConfigTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} RequestConfig`)
-    },
     resolveResponsesName(node) {
       return this.resolveName(`${node.operationId} Responses`)
     },
-    resolveResponsesTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} Responses`)
-    },
     resolveResponseName(node) {
       return this.resolveName(`${node.operationId} Response`)
     },
-    resolveResponseTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} Response`)
-    },
-    resolveEnumKeyTypedName(node, enumTypeSuffix = 'key') {
-      return `${this.resolveTypedName(node.name ?? '')}${enumTypeSuffix}`
-    },
-    resolvePathParamsName(_node) {
-      throw new Error("resolvePathParamsName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamName per individual parameter instead.")
-    },
-    resolvePathParamsTypedName(_node) {
-      throw new Error(
-        "resolvePathParamsTypedName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamTypedName per individual parameter instead.",
-      )
-    },
-    resolveQueryParamsName(_node) {
-      throw new Error("resolveQueryParamsName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamName per individual parameter instead.")
+    resolveEnumKeyName(node, enumTypeSuffix = 'key') {
+      return `${this.resolveName(node.name ?? '')}${enumTypeSuffix}`
     },
-    resolveQueryParamsTypedName(_node) {
-      throw new Error(
-        "resolveQueryParamsTypedName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamTypedName per individual parameter instead.",
-      )
+    resolvePathParamsName(node, param) {
+      return this.resolveParamName(node, param)
     },
-    resolveHeaderParamsName(_node) {
-      throw new Error("resolveHeaderParamsName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamName per individual parameter instead.")
+    resolveQueryParamsName(node, param) {
+      return this.resolveParamName(node, param)
     },
-    resolveHeaderParamsTypedName(_node) {
-      throw new Error(
-        "resolveHeaderParamsTypedName is only available with compatibilityPreset: 'kubbV4'. Use resolveParamTypedName per individual parameter instead.",
-      )
+    resolveHeaderParamsName(node, param) {
+      return this.resolveParamName(node, param)
     },
   }
 })

package/src/resolvers/resolverTsLegacy.ts

@@ -35,53 +35,26 @@ export const resolverTsLegacy = defineResolver<PluginTs>(() => {
       }
       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}`
+      return this.resolveName(`${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) {
+    resolvePathParamsName(node, _param) {
       return this.resolveName(`${node.operationId} PathParams`)
     },
-    resolvePathParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} PathParams`)
-    },
-    resolveQueryParamsName(node) {
+    resolveQueryParamsName(node, _param) {
       return this.resolveName(`${node.operationId} QueryParams`)
     },
-    resolveQueryParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} QueryParams`)
-    },
-    resolveHeaderParamsName(node) {
+    resolveHeaderParamsName(node, _param) {
       return this.resolveName(`${node.operationId} HeaderParams`)
     },
-    resolveHeaderParamsTypedName(node) {
-      return this.resolveTypedName(`${node.operationId} HeaderParams`)
-    },
   }
 })