@kubb/plugin-ts 5.0.0-beta.56 → 5.0.0-beta.73

package/dist/index.d.ts

@@ -1,8 +1,56 @@
-import { t as __name } from "./chunk-C0LytTxp.js";
-import { Exclude, Generator, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
+import { n as __name } from "./rolldown-runtime-CNktS9qV.js";
 import ts from "typescript";
+import { Exclude, Group, Include, Output, OutputOptions, Override, PluginFactoryOptions, Resolver, ast } from "@kubb/core";
 import { KubbReactNode } from "@kubb/renderer-jsx/types";
+import { OperationNode } from "@kubb/ast";
 
+//#region ../../internals/shared/src/operation.d.ts
+/**
+ * Resolver interface for building operation parameters.
+ *
+ * `ResolverTs` from `@kubb/plugin-ts` satisfies this interface and can be passed directly.
+ */
+type OperationParamsResolver = {
+  /**
+   * Resolves the type name for an individual parameter.
+   *
+   * @example Individual path parameter name
+   * `resolver.resolveParamName(node, param) // → 'DeletePetPathPetId'`
+   */
+  resolveParamName(node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the request body type name.
+   *
+   * @example Request body type name
+   * `resolver.resolveDataName(node) // → 'CreatePetData'`
+   */
+  resolveDataName(node: ast.OperationNode): string;
+  /**
+   * Resolves the grouped path parameters type name.
+   * When the return value equals `resolveParamName`, no indexed access is emitted.
+   *
+   * @example Grouped path params type name
+   * `resolver.resolvePathParamsName(node, param) // → 'DeletePetPathParams'`
+   */
+  resolvePathParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the grouped query parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped query params type name
+   * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
+   */
+  resolveQueryParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
+  /**
+   * Resolves the grouped header parameters type name.
+   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
+   *
+   * @example Grouped header params type name
+   * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
+   */
+  resolveHeaderParamsName(node: ast.OperationNode, param: ast.ParameterNode): string;
+};
+//#endregion
 //#region src/printers/printerTs.d.ts
 /**
  * Partial map of node-type overrides for the TypeScript printer.
@@ -118,7 +166,7 @@ declare const printerTs: (options?: PrinterTsOptions | undefined) => ast.Printer
  * Extends the base `Resolver` (which provides `default` and `resolveOptions`) with
  * plugin-specific naming helpers for operations, parameters, responses, and schemas.
  */
-type ResolverTs = Resolver & ast.OperationParamsResolver & {
+type ResolverTs = Resolver & OperationParamsResolver & {
   /**
    * Resolves the name for a given raw name (equivalent to `default(name, 'function')`).
    * Since TypeScript only emits types, this is the canonical naming method.
@@ -149,6 +197,9 @@ type ResolverTs = Resolver & ast.OperationParamsResolver & {
   /**
    * Resolves the name for an operation's request config (`RequestConfig`).
    *
+   * The `RequestConfig` suffix is kept through the v5 beta to avoid churn, but it overlaps with the
+   * runtime client's `RequestConfig`. Renaming to `Request` is on the table before stable.
+   *
    * @example Request config names
    * `resolver.resolveRequestConfigName(node) // → 'ListPetsRequestConfig'`
    */
@@ -349,17 +400,6 @@ type Options = OutputOptions & {
    * @default 'array'
    */
   arrayType?: 'generic' | 'array';
-  /**
-   * Rename properties inside `PathParams`, `QueryParams`, and `HeaderParams` types.
-   * Response and request body types are not affected.
-   *
-   * @note Every plugin that touches operation parameters must use the same value.
-   */
-  paramsCasing?: 'camelcase';
-  /**
-   * Custom generators that run alongside the built-in TypeScript generators.
-   */
-  generators?: Array<Generator<PluginTs>>;
   /**
    * Override how names and file paths are built for generated symbols.
    * Methods you omit fall back to the default `resolverTs`. `this` is bound to the
@@ -368,19 +408,22 @@ type Options = OutputOptions & {
    */
   resolver?: Partial<ResolverTs> & ThisType<ResolverTs>;
   /**
-   * AST visitor applied to each schema or operation node before printing.
-   * Methods you omit fall back to the preset transformer.
+   * Macros applied to each schema or operation node before printing.
+   * Callbacks you omit fall back to the preset behavior.
    *
    * @example Drop writeOnly properties from response types
    * ```ts
-   * transformer: {
-   *   property(node) {
-   *     if (node.schema.writeOnly) return undefined
-   *   }
-   * }
+   * macros: [
+   *   {
+   *     name: 'drop-write-only',
+   *     property(node) {
+   *       if (node.schema.writeOnly) return undefined
+   *     },
+   *   },
+   * ]
    * ```
    */
-  transformer?: ast.Visitor;
+  macros?: Array<ast.Macro>;
   /**
    * Replace the TypeScript handler for a specific schema type (`'integer'`, `'date'`, ...).
    * Each handler returns a TypeScript AST node for that schema type. Use `this.transform`
@@ -424,7 +467,6 @@ type ResolvedOptions = {
   optionalType: NonNullable<Options['optionalType']>;
   arrayType: NonNullable<Options['arrayType']>;
   syntaxType: NonNullable<Options['syntaxType']>;
-  paramsCasing: Options['paramsCasing'];
   printer: Options['printer'];
 };
 type PluginTs = PluginFactoryOptions<'plugin-ts', Options, ResolvedOptions, ResolverTs>;
@@ -532,19 +574,229 @@ declare const pluginTsName = "plugin-ts";
  */
 declare const pluginTs: (options?: Options | undefined) => import("@kubb/core").Plugin<PluginTs>;
 //#endregion
+//#region src/printers/functionParams.d.ts
+/**
+ * A type expression used as a function parameter type annotation.
+ *
+ * - a plain `string` is a type reference rendered as-is, e.g. `'string'`, `'QueryParams'`, `'Partial<Config>'`
+ * - a {@link TypeLiteralNode} is an inline anonymous type, e.g. `{ petId: string; name?: string }`
+ * - an {@link IndexedAccessTypeNode} is a single field accessed from a named type, e.g. `PathParams['petId']`
+ */
+type TypeExpression = string | TypeLiteralNode | IndexedAccessTypeNode;
+/**
+ * An inline anonymous object type grouping named fields.
+ * Renders as `{ key: Type; other?: OtherType }`.
+ */
+type TypeLiteralNode = {
+  kind: 'TypeLiteral';
+  /**
+   * Members of the object type, rendered in order.
+   */
+  members: Array<{
+    /**
+     * Member key.
+     */
+    name: string;
+    /**
+     * Member type expression.
+     */
+    type: TypeExpression;
+    /**
+     * Whether the member is optional, rendered with `?`.
+     */
+    optional?: boolean;
+  }>;
+};
+/**
+ * A single field accessed from a named group type. Renders as `target['key']`.
+ */
+type IndexedAccessTypeNode = {
+  kind: 'IndexedAccessType';
+  /**
+   * Name of the type being indexed, e.g. `'GetPetPathParams'`.
+   */
+  target: string;
+  /**
+   * Field key to access, e.g. `'petId'`.
+   */
+  key: string;
+};
+/**
+ * An object destructuring binding, used as the name of a grouped function parameter.
+ * Renders as `{ id, name }` or `{ id: renamed }` when `propertyName` differs.
+ */
+type ObjectBindingPatternNode = {
+  kind: 'ObjectBindingPattern';
+  /**
+   * Bound elements, rendered in order.
+   */
+  elements: Array<{
+    /**
+     * Local binding name.
+     */
+    name: string;
+    /**
+     * Source key when it differs from the binding name, rendered as `propertyName: name`.
+     */
+    propertyName?: string;
+  }>;
+};
+/**
+ * One function parameter.
+ *
+ * A simple parameter has a `string` name. A destructured group has an
+ * {@link ObjectBindingPatternNode} name paired with a {@link TypeLiteralNode} type.
+ *
+ * @example Required parameter
+ * `name: Type`
+ *
+ * @example Optional parameter
+ * `name?: Type`
+ *
+ * @example Parameter with default value
+ * `name: Type = defaultValue`
+ *
+ * @example Rest parameter
+ * `...name: Type[]`
+ *
+ * @example Destructured group
+ * `{ id, name? }: { id: string; name?: string } = {}`
+ */
+type FunctionParameterNode = {
+  kind: 'FunctionParameter';
+  /**
+   * Parameter name, or an {@link ObjectBindingPatternNode} for a destructured group.
+   */
+  name: string | ObjectBindingPatternNode;
+  /**
+   * Type annotation as a {@link TypeExpression}. Omit for untyped output.
+   */
+  type?: TypeExpression;
+  /**
+   * Whether the parameter is optional, rendered with `?`.
+   */
+  optional?: boolean;
+  /**
+   * Default value, written verbatim after `=`. Commonly `'{}'` for a destructured group.
+   */
+  default?: string;
+  /**
+   * When `true` the parameter is emitted as a rest parameter, e.g. `...name: Type[]`.
+   */
+  rest?: boolean;
+};
+/**
+ * A complete function parameter list.
+ *
+ * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
+ */
+type FunctionParametersNode = {
+  kind: 'FunctionParameters';
+  /**
+   * Ordered parameter nodes.
+   */
+  params: ReadonlyArray<FunctionParameterNode>;
+};
+/**
+ * Creates a {@link TypeLiteralNode} representing an inline anonymous object type.
+ *
+ * @example
+ * ```ts
+ * createTypeLiteral({ members: [{ name: 'petId', type: 'string', optional: false }] })
+ * // { petId: string }
+ * ```
+ */
+declare function createTypeLiteral(props: Omit<TypeLiteralNode, 'kind'>): TypeLiteralNode;
+/**
+ * Creates an {@link IndexedAccessTypeNode} representing a single field accessed from a named type.
+ *
+ * @example
+ * ```ts
+ * createIndexedAccessType({ target: 'DeletePetPathParams', key: 'petId' })
+ * // DeletePetPathParams['petId']
+ * ```
+ */
+declare function createIndexedAccessType(props: Omit<IndexedAccessTypeNode, 'kind'>): IndexedAccessTypeNode;
+/**
+ * Creates an {@link ObjectBindingPatternNode} for a destructured parameter binding.
+ *
+ * @example
+ * ```ts
+ * createObjectBindingPattern({ elements: [{ name: 'id' }, { name: 'name' }] })
+ * // { id, name }
+ * ```
+ */
+declare function createObjectBindingPattern(props: Omit<ObjectBindingPatternNode, 'kind'>): ObjectBindingPatternNode;
+/**
+ * Plain property descriptor for a destructured group built by {@link createFunctionParameter}.
+ */
+type FunctionParameterProperty = {
+  name: string;
+  type: TypeExpression;
+  optional?: boolean;
+};
+type FunctionParameterInput = {
+  name: string | ObjectBindingPatternNode;
+  type?: TypeExpression;
+  optional?: boolean;
+  default?: string;
+  rest?: boolean;
+} | {
+  properties: Array<FunctionParameterProperty>;
+  optional?: boolean;
+  default?: string;
+};
+/**
+ * Creates a {@link FunctionParameterNode}. `optional` defaults to `false`.
+ * Passing `properties` builds a destructured group: an {@link ObjectBindingPatternNode} name
+ * paired with a {@link TypeLiteralNode} type.
+ *
+ * @example Optional param
+ * ```ts
+ * createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
+ * // → params?: QueryParams
+ * ```
+ *
+ * @example Destructured group
+ * ```ts
+ * createFunctionParameter({ properties: [{ name: 'id', type: 'string' }, { name: 'name', type: 'string', optional: true }], default: '{}' })
+ * // → { id, name }: { id: string; name?: string } = {}
+ * ```
+ */
+declare function createFunctionParameter(input: FunctionParameterInput): FunctionParameterNode;
+/**
+ * Creates a {@link FunctionParametersNode} from an ordered list of parameters.
+ *
+ * @example
+ * ```ts
+ * const empty = createFunctionParameters()
+ * // { params: [] }
+ * ```
+ */
+declare function createFunctionParameters(props?: Partial<Omit<FunctionParametersNode, 'kind'>>): FunctionParametersNode;
+//#endregion
 //#region src/printers/functionPrinter.d.ts
+/**
+ * Renders a {@link TypeExpression} to its TypeScript source.
+ *
+ * - a `string` is a type reference, returned as-is
+ * - an `IndexedAccessType` becomes `objectType['indexType']`
+ * - a `TypeLiteral` becomes `{ key: Type; key?: Type }`
+ *
+ * `transformType` is applied once to the fully rendered type, matching how the
+ * printer wrapped reference types before the `ts.factory` model.
+ */
+declare function renderType(type: TypeExpression, transformType?: (type: string) => string): string;
 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          | Output example                    | Use case                       |
+   * |---------------|-----------------------------------|--------------------------------|
+   * | `declaration` | `id: string, config: Config = {}` | Function parameter declaration |
+   * | `call`        | `id, { method, url }`             | Function call arguments        |
    */
-  mode: 'declaration' | 'call' | 'keys' | 'values';
+  mode: 'declaration' | 'call';
   /**
    * Optional transformation applied to every parameter name before printing.
    */
@@ -555,8 +807,8 @@ type FunctionPrinterOptions = {
   transformType?: (type: string) => string;
 };
 /**
- * Default function-signature printer.
- * Covers the four standard output modes used across Kubb plugins.
+ * Default function-signature printer. Renders a parameter list in one of two modes:
+ * `declaration` for the function signature and `call` for the call arguments.
  *
  * @example
  * ```ts
@@ -572,13 +824,102 @@ type FunctionPrinterOptions = {
  * printer.print(sig)  // → "petId: string, config: Config = {}"
  * ```
  */
-declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) => {
+declare function functionPrinter(options: FunctionPrinterOptions): {
   name: "functionParameters";
   options: FunctionPrinterOptions;
-  transform: (node: ast.FunctionParamNode) => string | null;
-  print: (node: ast.FunctionParamNode) => string | null;
+  print(node: FunctionParametersNode): string;
 };
 //#endregion
+//#region src/printers/operationParams.d.ts
+/**
+ * Options for {@link createOperationParams}.
+ */
+type CreateOperationParamsOptions = {
+  /**
+   * How all operation parameters are grouped in the function signature.
+   * - `'object'` wraps all params into a single destructured object `{ petId, data, params }`
+   * - `'inline'` emits each param category as a separate top-level parameter
+   */
+  paramsType: 'object' | 'inline';
+  /**
+   * How path parameters are emitted when `paramsType` is `'inline'`.
+   * - `'object'` groups them as `{ petId, storeId }: PathParams`
+   * - `'inline'` spreads them as individual parameters `petId: string, storeId: string`
+   * - `'inlineSpread'` emits a single rest parameter `...pathParams: PathParams`
+   */
+  pathParamsType: 'object' | 'inline' | 'inlineSpread';
+  /**
+   * Converts parameter names to camelCase before output.
+   */
+  paramsCasing?: 'camelcase';
+  /**
+   * Resolver for parameter and request body type names.
+   * Pass `ResolverTs` from `@kubb/plugin-ts` directly.
+   * When omitted, falls back to the schema primitive or `'unknown'`.
+   */
+  resolver?: OperationParamsResolver;
+  /**
+   * Default value for the path parameters binding when `pathParamsType` is `'object'`.
+   * Falls back to `'{}'` when all path params are optional.
+   */
+  pathParamsDefault?: string;
+  /**
+   * Extra parameters appended after the standard operation parameters.
+   *
+   * @example Plugin-specific trailing parameter
+   * ```ts
+   * extraParams: [createFunctionParameter({ name: 'options', type: 'Partial<RequestOptions>', default: '{}' })]
+   * ```
+   */
+  extraParams?: Array<FunctionParameterNode>;
+  /**
+   * Override the default parameter names used for body, query, header, and rest-path groups.
+   *
+   * Useful when targeting languages or frameworks with different naming conventions.
+   *
+   * @default { data: 'data', params: 'params', headers: 'headers', path: 'pathParams' }
+   */
+  paramNames?: {
+    /**
+     * Name for the request body parameter.
+     * @default 'data'
+     */
+    data?: string;
+    /**
+     * Name for the query parameters group parameter.
+     * @default 'params'
+     */
+    params?: string;
+    /**
+     * Name for the header parameters group parameter.
+     * @default 'headers'
+     */
+    headers?: string;
+    /**
+     * Name for the rest path-parameters parameter when `pathParamsType` is `'inlineSpread'`.
+     * @default 'pathParams'
+     */
+    path?: string;
+  };
+  /**
+   * Transforms every resolved type name before it lands in a parameter node, for framework-level
+   * type wrappers.
+   *
+   * @example Vue Query, wrap every parameter type with `MaybeRefOrGetter`
+   * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
+   */
+  typeWrapper?: (type: string) => string;
+};
+/**
+ * Converts an `OperationNode` into function parameters for code generation.
+ *
+ * Centralizes parameter grouping logic for all plugins. `paramsType` chooses between one
+ * destructured object parameter (`object`) and separate top-level parameters (`inline`), while
+ * `pathParamsType` controls how path params render in inline mode. Provide a `resolver` for type
+ * name resolution and `extraParams` for plugin-specific trailing parameters such as an `options` object.
+ */
+declare function createOperationParams(node: OperationNode, options: CreateOperationParamsOptions): FunctionParametersNode;
+//#endregion
 //#region src/resolvers/resolverTs.d.ts
 /**
  * Default resolver used by `@kubb/plugin-ts`. Decides the names and file paths
@@ -600,5 +941,5 @@ declare const functionPrinter: (options?: FunctionPrinterOptions | undefined) =>
  */
 declare const resolverTs: ResolverTs;
 //#endregion
-export { Enum, type PluginTs, type PrinterTsFactory, type PrinterTsNodes, type PrinterTsOptions, type ResolverTs, Type, pluginTs as default, pluginTs, functionPrinter, pluginTsName, printerTs, resolverTs, typeGenerator };
+export { type CreateOperationParamsOptions, Enum, type FunctionParameterNode, type FunctionParametersNode, type IndexedAccessTypeNode, type ObjectBindingPatternNode, type PluginTs, type PrinterTsFactory, type PrinterTsNodes, type PrinterTsOptions, type ResolverTs, Type, type TypeExpression, type TypeLiteralNode, createFunctionParameter, createFunctionParameters, createIndexedAccessType, createObjectBindingPattern, createOperationParams, createTypeLiteral, pluginTs as default, pluginTs, functionPrinter, pluginTsName, printerTs, renderType, resolverTs, typeGenerator };
 //# sourceMappingURL=index.d.ts.map