@kubb/ast 5.0.0-alpha.1 → 5.0.0-alpha.11

package/dist/{visitor-CmsfJzro.d.ts → visitor-D-l3dMbN.d.ts}

@@ -12,6 +12,9 @@ declare const nodeKinds: {
   readonly property: "Property";
   readonly parameter: "Parameter";
   readonly response: "Response";
+  readonly functionParameter: "FunctionParameter";
+  readonly objectBindingParameter: "ObjectBindingParameter";
+  readonly functionParameters: "FunctionParameters";
 };
 declare const schemaTypes: {
   readonly string: "string";
@@ -46,6 +49,7 @@ declare const schemaTypes: {
   readonly email: "email";
   readonly url: "url";
   readonly blob: "blob";
+  readonly never: "never";
 };
 declare const httpMethods: {
   readonly get: "GET";
@@ -83,7 +87,7 @@ declare const mediaTypes: {
 /**
  * Kind discriminant for every AST node.
  */
-type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response';
+type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response' | 'FunctionParameter' | 'ObjectBindingParameter' | 'FunctionParameters';
 /**
  * Common base for all AST nodes.
  */
@@ -91,6 +95,127 @@ type BaseNode = {
   kind: NodeKind;
 };
 //#endregion
+//#region src/nodes/function.d.ts
+/**
+ * A single named function parameter.
+ *
+ * @example Simple required param
+ * `name: Type`
+ *
+ * @example Optional param
+ * `name?: Type`
+ *
+ * @example Param with default
+ * `name: Type = defaultValue`
+ *
+ * @example Rest / spread param
+ * `...name: Type[]`
+ */
+type FunctionParameterNode = BaseNode & {
+  kind: 'FunctionParameter';
+  /**
+   * The parameter name as it appears in the function signature.
+   */
+  name: string;
+  /**
+   * TypeScript type annotation (raw string, e.g. `"string"`, `"Pet[]"`, `"Partial<Config>"`).
+   * Omit for untyped JavaScript output.
+   */
+  type?: string;
+  /**
+   * When `true` the parameter is emitted as a rest parameter (`...name`).
+   * @default false
+   */
+  rest?: boolean;
+}
+/**
+* Explicitly optional parameter — rendered with `?` in the signature.
+* Cannot be combined with `default`; a parameter with a default is implicitly optional.
+* @example `name?: Type`
+*/
+& ({
+  optional: true;
+  default?: never;
+}
+/**
+ * Required parameter, or a parameter with a default value (implicitly optional).
+ * @example Required: `name: Type`
+ * @example With default: `name: Type = default`
+ */
+| {
+  optional?: false;
+  default?: string;
+});
+/**
+ * An object-destructured function parameter group.
+ *
+ * Renders as `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}` in a declaration,
+ * or as individual top-level params when `inline` is `true`.
+ *
+ * Replaces `mode: 'object'` / `mode: 'inlineSpread'` from the legacy `FunctionParams` API.
+ *
+ * @example Object destructuring with auto-computed type (declaration)
+ * `{ id, name }: { id: string; name: string } = {}`
+ *
+ * @example Inline (spread) — children emitted as individual top-level params
+ * `id: string, name: string`
+ */
+type ObjectBindingParameterNode = BaseNode & {
+  kind: 'ObjectBindingParameter';
+  /**
+   * The individual parameters that form the destructured object.
+   * Rendered as `{ key1, key2 }` in declarations, or spread inline when `inline` is `true`.
+   */
+  properties: Array<FunctionParameterNode>;
+  /**
+   * Explicit TypeScript type annotation for the whole object param.
+   * When absent the printer auto-computes `{ key1: Type1; key2: Type2 }` from `params`.
+   */
+  type?: string;
+  /**
+   * When `true` the `params` are emitted as individual top-level parameters instead of
+   * being wrapped in a destructuring pattern (`{ key1, key2 }`).
+   *
+   * Equivalent to `mode: 'inlineSpread'` in the legacy `FunctionParams` API.
+   * @default false
+   */
+  inline?: boolean;
+  /**
+   * Whether the whole object group is optional.
+   * When absent the printer auto-computes this: optional if every child param is optional.
+   */
+  optional?: boolean;
+  /**
+   * Default value for the object group, written verbatim after `=`.
+   * Commonly `'{}'` to allow omitting the argument entirely.
+   */
+  default?: string;
+};
+/**
+ * A complete ordered parameter list for a function.
+ *
+ * The printer is responsible for sorting (required → optional → has-default).
+ * Nodes themselves are treated as plain, immutable data.
+ *
+ * Renders differently depending on the output mode:
+ * - `declaration` → `(id: string, config: Config = {})` — typed function parameter list
+ * - `call`        → `(id, { method, url })` — function call arguments
+ * - `keys`        → `{ id, config }` — key names only (for destructuring)
+ * - `values`      → `{ id: id, config: config }` — key → value pairs
+ */
+type FunctionParametersNode = BaseNode & {
+  kind: 'FunctionParameters';
+  params: Array<FunctionParameterNode | ObjectBindingParameterNode>;
+};
+/**
+ * The three function-signature AST node variants.
+ */
+type FunctionNode = FunctionParameterNode | ObjectBindingParameterNode | FunctionParametersNode;
+/**
+ * Handler map keys — one per `FunctionNode` kind.
+ */
+type FunctionNodeType = 'functionParameter' | 'objectBindingParameter' | 'functionParameters';
+//#endregion
 //#region src/nodes/property.d.ts
 /**
  * A named property within an object schema.
@@ -103,14 +228,14 @@ type PropertyNode = BaseNode & {
 };
 //#endregion
 //#region src/nodes/schema.d.ts
-type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'object' | 'array' | 'date';
+type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'never' | 'object' | 'array' | 'date';
 type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum';
 /**
  * Semantic types requiring special handling in code generation (e.g. generating a `Date` object or a branded type).
  */
 type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'blob';
 type SchemaType = PrimitiveSchemaType | ComplexSchemaType | SpecialSchemaType;
-type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint'>;
+type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'union' | 'intersection' | 'enum' | 'ref' | 'datetime' | 'date' | 'time' | 'string' | 'number' | 'integer' | 'bigint' | 'url'>;
 /**
  * Base fields shared by every schema variant. Does not include spec-specific fields.
  */
@@ -284,6 +409,16 @@ type NumberSchemaNode = SchemaNodeBase & {
 type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType;
 };
+/**
+ * URL schema, optionally carrying an Express-style path template for template literal generation.
+ */
+type UrlSchemaNode = SchemaNodeBase & {
+  type: 'url';
+  /**
+   * Express-style path (e.g. `'/pets/:petId'`). When set, printers may emit a template literal type.
+   */
+  path?: string;
+};
 /**
  * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
  */
@@ -307,15 +442,16 @@ type SchemaNodeByType = {
   any: ScalarSchemaNode;
   unknown: ScalarSchemaNode;
   void: ScalarSchemaNode;
+  never: ScalarSchemaNode;
   uuid: ScalarSchemaNode;
   email: ScalarSchemaNode;
-  url: ScalarSchemaNode;
+  url: UrlSchemaNode;
   blob: ScalarSchemaNode;
 };
 /**
  * Discriminated union of all schema variants.
  */
-type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | ScalarSchemaNode;
+type SchemaNode = ObjectSchemaNode | ArraySchemaNode | UnionSchemaNode | IntersectionSchemaNode | EnumSchemaNode | RefSchemaNode | DatetimeSchemaNode | DateSchemaNode | TimeSchemaNode | StringSchemaNode | NumberSchemaNode | UrlSchemaNode | ScalarSchemaNode;
 //#endregion
 //#region src/nodes/parameter.d.ts
 type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
@@ -357,7 +493,7 @@ type ResponseNode = BaseNode & {
    */
   statusCode: StatusCode;
   description?: string;
-  schema?: SchemaNode;
+  schema: SchemaNode;
   mediaType?: MediaType;
 };
 //#endregion
@@ -373,6 +509,10 @@ type OperationNode = BaseNode & {
    */
   operationId: string;
   method: HttpMethod;
+  /**
+   * Express-style path string, e.g. `/pets/:petId`.
+   * Derived from the OpenAPI path by converting `{param}` tokens to `:param`.
+   */
   path: string;
   tags: Array<string>;
   summary?: string;
@@ -392,7 +532,17 @@ type OperationNode = BaseNode & {
  * Adapters populate whichever fields are available in their source format.
  */
 type RootMeta = {
-  /** API title (from `info.title` in OAS/AsyncAPI). */title?: string; /** API version string (from `info.version` in OAS/AsyncAPI). */
+  /**
+   * API title (from `info.title` in OAS/AsyncAPI).
+   */
+  title?: string;
+  /**
+   * API description (from `info.description` in OAS/AsyncAPI).
+   */
+  description?: string;
+  /**
+   * API version string (from `info.version` in OAS/AsyncAPI).
+   */
   version?: string;
   /**
    * Resolved base URL for the API.
@@ -408,7 +558,10 @@ type RootMeta = {
 type RootNode = BaseNode & {
   kind: 'Root';
   schemas: Array<SchemaNode>;
-  operations: Array<OperationNode>; /** Format-agnostic document metadata populated by the adapter. */
+  operations: Array<OperationNode>;
+  /**
+   * Format-agnostic document metadata populated by the adapter.
+   */
   meta?: RootMeta;
 };
 //#endregion
@@ -420,7 +573,7 @@ type RootNode = BaseNode & {
  * TypeScript narrow the type automatically inside `switch (node.kind)`
  * blocks, eliminating the need for manual `as TypeName` casts.
  */
-type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode;
+type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionNode;
 //#endregion
 //#region src/factory.d.ts
 /**
@@ -460,16 +613,90 @@ declare function createParameter(props: Pick<ParameterNode, 'name' | 'in' | 'sch
 /**
  * Creates a `ResponseNode`.
  */
-declare function createResponse(props: Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode'>>): ResponseNode;
+declare function createResponse(props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>): ResponseNode;
+/**
+ * Creates a `FunctionParameterNode`. `optional` defaults to `false`.
+ *
+ * @example Required typed param
+ * ```ts
+ * createFunctionParameter({ name: 'petId', type: 'string' })
+ * // → petId: string
+ * ```
+ *
+ * @example Optional param
+ * ```ts
+ * createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
+ * // → params?: QueryParams
+ * ```
+ *
+ * @example Param with default (implicitly optional — cannot combine with `optional: true`)
+ * ```ts
+ * createFunctionParameter({ name: 'config', type: 'RequestConfig', default: '{}' })
+ * // → config: RequestConfig = {}
+ * ```
+ */
+declare function createFunctionParameter(props: {
+  name: string;
+  type?: string;
+  rest?: boolean;
+} & ({
+  optional: true;
+  default?: never;
+} | {
+  optional?: false;
+  default?: string;
+})): FunctionParameterNode;
+/**
+ * Creates an `ObjectBindingParameterNode` — an object-destructured parameter group.
+ *
+ * @example Destructured object param
+ * ```ts
+ * createObjectBindingParameter({
+ *   properties: [
+ *     createFunctionParameter({ name: 'id', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'name', type: 'string', optional: true }),
+ *   ],
+ *   default: '{}',
+ * })
+ * // declaration → { id, name? }: { id: string; name?: string } = {}
+ * // call        → { id, name }
+ * ```
+ *
+ * @example Inline — children emitted as individual top-level params
+ * ```ts
+ * createObjectBindingParameter({
+ *   properties: [createFunctionParameter({ name: 'petId', type: 'string', optional: false })],
+ *   inline: true,
+ * })
+ * // declaration → petId: string
+ * // call        → petId
+ * ```
+ */
+declare function createObjectBindingParameter(props: Pick<ObjectBindingParameterNode, 'properties'> & Partial<Omit<ObjectBindingParameterNode, 'kind' | 'properties'>>): ObjectBindingParameterNode;
+/**
+ * Creates a `FunctionParametersNode` from an ordered list of params.
+ *
+ * @example
+ * ```ts
+ * createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'config', type: 'RequestConfig', optional: false, default: '{}' }),
+ *   ],
+ * })
+ * ```
+ */
+declare function createFunctionParameters(props?: Partial<Omit<FunctionParametersNode, 'kind'>>): FunctionParametersNode;
 //#endregion
 //#region src/printer.d.ts
 /**
  * Handler context for `definePrinter` — mirrors `PluginContext` from `@kubb/core`.
- * Available as `this` inside each node handler.
+ * Available as `this` inside each node handler and the optional root-level `print`.
+ * `this.print` always dispatches to the `nodes` handlers (node-level printer).
  */
 type PrinterHandlerContext<TOutput, TOptions extends object> = {
   /**
-   * Recursively print a nested `SchemaNode`.
+   * Recursively print a nested `SchemaNode` using the node-level handlers.
    */
   print: (node: SchemaNode) => TOutput | null | undefined;
   /**
@@ -486,18 +713,19 @@ type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = Sch
  * Shape of the type parameter passed to `definePrinter`.
  * Mirrors `AdapterFactoryOptions` / `PluginFactoryOptions` from `@kubb/core`.
  *
- * - `TName` — unique string identifier (e.g. `'zod'`, `'ts'`)
- * - `TOptions` — options passed to and stored on the printer
- * - `TOutput` — the type emitted by `print` (typically `string`)
+ * - `TName`        — unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions`     — options passed to and stored on the printer
+ * - `TOutput`      — the type emitted by node handlers
+ * - `TPrintOutput` — the type emitted by the public `print` override (defaults to `TOutput`)
  */
-type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown> = {
+type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown, TPrintOutput = TOutput> = {
   name: TName;
   options: TOptions;
   output: TOutput;
+  printOutput: TPrintOutput;
 };
 /**
  * The object returned by calling a `definePrinter` instance.
- * Mirrors the shape of `Adapter` from `@kubb/core`.
  */
 type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
   /**
@@ -509,14 +737,17 @@ type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    */
   options: T['options'];
   /**
-   * Emits `TOutput` from a `SchemaNode`. Returns `null | undefined` when no handler matches.
-   */
-  print: (node: SchemaNode) => T['output'] | null | undefined;
-  /**
-   * Maps `print` over an array of `SchemaNode`s.
+   * Public printer. If the builder provides a root-level `print`, this calls that
+   * higher-level function (which may produce full declarations). Otherwise falls back
+   * to the node-level dispatcher
    */
-  for: (nodes: Array<SchemaNode>) => Array<T['output'] | null | undefined>;
+  print: (node: SchemaNode) => T['printOutput'] | null | undefined;
 };
+/**
+ * Builder function passed to `definePrinter`. Receives the resolved options and returns the
+ * printer configuration: a unique `name`, the stored `options`, node-level `nodes` handlers,
+ * and an optional root-level `print` override.
+ */
 type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) => {
   name: T['name'];
   /**
@@ -524,39 +755,58 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
    */
   options: T['options'];
   nodes: Partial<{ [K in SchemaType]: PrinterHandler<T['output'], T['options'], K> }>;
+  /**
+   * Optional root-level print override. When provided, becomes the public `printer.print`.
+   * `this.print(node)` inside this function calls the node-level dispatcher (`nodes` handlers),
+   * not the override itself — so recursion is safe.
+   */
+  print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null | undefined;
 };
 /**
- * Creates a named printer factory. Mirrors the `definePlugin` / `defineAdapter` pattern
+ * Creates a named printer factory. Mirrors the `createPlugin` / `createAdapter` pattern
  * from `@kubb/core` — wraps a builder to make options optional and separates raw options
  * from resolved options.
  *
- * @example
+ * The builder receives resolved options and returns:
+ * - `name` — a unique identifier for the printer
+ * - `options` — options stored on the returned printer instance
+ * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
+ * - `print` _(optional)_ — a root-level override that becomes the public `printer.print`.
+ *   Inside it, `this.print(node)` still dispatches to the `nodes` map — safe recursion, no infinite loop.
+ *
+ * When no `print` override is provided, `printer.print` is the node-level dispatcher directly.
+ *
+ * @example Basic usage — Zod schema printer
  * ```ts
- * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, { strict: boolean }, string>
+ * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
  *
- * export const zodPrinter = definePrinter<ZodPrinter>((options) => {
- *   const { strict = true } = options
- *   return {
- *     name: 'zod',
- *     options: { strict },
- *     nodes: {
- *       string(node) {
- *         return `z.string()`
- *       },
- *       object(node) {
- *         const props = node.properties
- *           ?.map(p => `${p.name}: ${this.print(p)}`)
- *           .join(', ') ?? ''
- *         return `z.object({ ${props} })`
- *       },
+ * export const zodPrinter = definePrinter<ZodPrinter>((options) => ({
+ *   name: 'zod',
+ *   options: { strict: options.strict ?? true },
+ *   nodes: {
+ *     string: () => 'z.string()',
+ *     object(node) {
+ *       const props = node.properties.map(p => `${p.name}: ${this.print(p.schema)}`).join(', ')
+ *       return `z.object({ ${props} })`
  *     },
- *   }
- * })
+ *   },
+ * }))
+ * ```
+ *
+ * @example With a root-level `print` override to wrap output in a full declaration
+ * ```ts
+ * type TsPrinter = PrinterFactoryOptions<'ts', { typeName?: string }, ts.TypeNode, ts.Node>
  *
- * const printer = zodPrinter({ strict: false })
- * printer.name            // 'zod'
- * printer.options         // { strict: false }
- * printer.print(node)     // 'z.string()'
+ * export const printerTs = definePrinter<TsPrinter>((options) => ({
+ *   name: 'ts',
+ *   options,
+ *   nodes: { string: () => factory.keywordTypeNodes.string },
+ *   print(node) {
+ *     const type = this.print(node) // calls the node-level dispatcher
+ *     if (!type || !this.options.typeName) return type
+ *     return factory.createTypeAliasDeclaration(this.options.typeName, type)
+ *   },
+ * }))
  * ```
  */
 declare function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T>;
@@ -645,5 +895,5 @@ declare function transform(node: Node, visitor: Visitor, options?: VisitorOption
  */
 declare function collect<T>(node: Node, visitor: CollectVisitor<T>, options?: VisitorOptions): Array<T>;
 //#endregion
-export { UnionSchemaNode as $, MediaType as A, IntersectionSchemaNode as B, Node as C, OperationNode as D, HttpMethod as E, ComplexSchemaType as F, ScalarSchemaNode as G, ObjectSchemaNode as H, DateSchemaNode as I, SchemaNodeByType as J, ScalarSchemaType as K, DatetimeSchemaNode as L, ParameterLocation as M, ParameterNode as N, ResponseNode as O, ArraySchemaNode as P, TimeSchemaNode as Q, EnumSchemaNode as R, createSchema as S, RootNode as T, PrimitiveSchemaType as U, NumberSchemaNode as V, RefSchemaNode as W, SpecialSchemaType as X, SchemaType as Y, StringSchemaNode as Z, createOperation as _, transform as a, mediaTypes as at, createResponse as b, buildRefMap as c, Printer as d, PropertyNode as et, PrinterFactoryOptions as f, DistributiveOmit as g, definePrinter as h, collect as i, httpMethods as it, StatusCode as j, HttpStatusCode as k, refMapToObject as l, PrinterHandlerContext as m, CollectVisitor as n, NodeKind as nt, walk as o, nodeKinds as ot, PrinterHandler as p, SchemaNode as q, Visitor as r, VisitorDepth as rt, RefMap as s, schemaTypes as st, AsyncVisitor as t, BaseNode as tt, resolveRef as u, createParameter as v, RootMeta as w, createRoot as x, createProperty as y, EnumValueNode as z };
-//# sourceMappingURL=visitor-CmsfJzro.d.ts.map
+export { TimeSchemaNode as $, HttpStatusCode as A, EnumValueNode as B, createSchema as C, HttpMethod as D, RootNode as E, ArraySchemaNode as F, RefSchemaNode as G, NumberSchemaNode as H, ComplexSchemaType as I, SchemaNode as J, ScalarSchemaNode as K, DateSchemaNode as L, StatusCode as M, ParameterLocation as N, OperationNode as O, ParameterNode as P, StringSchemaNode as Q, DatetimeSchemaNode as R, createRoot as S, RootMeta as T, ObjectSchemaNode as U, IntersectionSchemaNode as V, PrimitiveSchemaType as W, SchemaType as X, SchemaNodeByType as Y, SpecialSchemaType as Z, createObjectBindingParameter as _, transform as a, FunctionParameterNode as at, createProperty as b, buildRefMap as c, BaseNode as ct, Printer as d, httpMethods as dt, UnionSchemaNode as et, PrinterFactoryOptions as f, mediaTypes as ft, createFunctionParameters as g, createFunctionParameter as h, collect as i, FunctionNodeType as it, MediaType as j, ResponseNode as k, refMapToObject as l, NodeKind as lt, DistributiveOmit as m, schemaTypes as mt, CollectVisitor as n, PropertyNode as nt, walk as o, FunctionParametersNode as ot, definePrinter as p, nodeKinds as pt, ScalarSchemaType as q, Visitor as r, FunctionNode as rt, RefMap as s, ObjectBindingParameterNode as st, AsyncVisitor as t, UrlSchemaNode as tt, resolveRef as u, VisitorDepth as ut, createOperation as v, Node as w, createResponse as x, createParameter as y, EnumSchemaNode as z };
+//# sourceMappingURL=visitor-D-l3dMbN.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.11",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",
@@ -45,7 +45,8 @@
     "!/**/__snapshots__/**"
   ],
   "devDependencies": {
-    "@types/node": "^22.19.15"
+    "@types/node": "^22.19.15",
+    "@internals/utils": "0.0.0"
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",

package/src/constants.ts

@@ -21,7 +21,10 @@ export const nodeKinds = {
   property: 'Property',
   parameter: 'Parameter',
   response: 'Response',
-} as const satisfies Record<Lowercase<NodeKind>, NodeKind>
+  functionParameter: 'FunctionParameter',
+  objectBindingParameter: 'ObjectBindingParameter',
+  functionParameters: 'FunctionParameters',
+} as const satisfies Record<string, NodeKind>
 
 export const schemaTypes = {
   string: 'string',
@@ -56,6 +59,7 @@ export const schemaTypes = {
   email: 'email',
   url: 'url',
   blob: 'blob',
+  never: 'never',
 } as const satisfies Record<SchemaType, SchemaType>
 
 export const httpMethods = {

package/src/factory.ts

@@ -1,4 +1,15 @@
-import type { ObjectSchemaNode, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
+import type {
+  FunctionParameterNode,
+  FunctionParametersNode,
+  ObjectBindingParameterNode,
+  ObjectSchemaNode,
+  OperationNode,
+  ParameterNode,
+  PropertyNode,
+  ResponseNode,
+  RootNode,
+  SchemaNode,
+} from './nodes/index.ts'
 
 /**
  * Distributive variant of `Omit` that preserves union members.
@@ -76,9 +87,98 @@ export function createParameter(
 /**
  * Creates a `ResponseNode`.
  */
-export function createResponse(props: Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode'>>): ResponseNode {
+export function createResponse(
+  props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>,
+): ResponseNode {
   return {
     ...props,
     kind: 'Response',
   }
 }
+
+/**
+ * Creates a `FunctionParameterNode`. `optional` defaults to `false`.
+ *
+ * @example Required typed param
+ * ```ts
+ * createFunctionParameter({ name: 'petId', type: 'string' })
+ * // → petId: string
+ * ```
+ *
+ * @example Optional param
+ * ```ts
+ * createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
+ * // → params?: QueryParams
+ * ```
+ *
+ * @example Param with default (implicitly optional — cannot combine with `optional: true`)
+ * ```ts
+ * createFunctionParameter({ name: 'config', type: 'RequestConfig', default: '{}' })
+ * // → config: RequestConfig = {}
+ * ```
+ */
+export function createFunctionParameter(
+  props: { name: string; type?: string; rest?: boolean } & ({ optional: true; default?: never } | { optional?: false; default?: string }),
+): FunctionParameterNode {
+  return {
+    optional: false,
+    ...props,
+    kind: 'FunctionParameter',
+  } as FunctionParameterNode
+}
+
+/**
+ * Creates an `ObjectBindingParameterNode` — an object-destructured parameter group.
+ *
+ * @example Destructured object param
+ * ```ts
+ * createObjectBindingParameter({
+ *   properties: [
+ *     createFunctionParameter({ name: 'id', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'name', type: 'string', optional: true }),
+ *   ],
+ *   default: '{}',
+ * })
+ * // declaration → { id, name? }: { id: string; name?: string } = {}
+ * // call        → { id, name }
+ * ```
+ *
+ * @example Inline — children emitted as individual top-level params
+ * ```ts
+ * createObjectBindingParameter({
+ *   properties: [createFunctionParameter({ name: 'petId', type: 'string', optional: false })],
+ *   inline: true,
+ * })
+ * // declaration → petId: string
+ * // call        → petId
+ * ```
+ */
+export function createObjectBindingParameter(
+  props: Pick<ObjectBindingParameterNode, 'properties'> & Partial<Omit<ObjectBindingParameterNode, 'kind' | 'properties'>>,
+): ObjectBindingParameterNode {
+  return {
+    ...props,
+    kind: 'ObjectBindingParameter',
+  }
+}
+
+/**
+ * Creates a `FunctionParametersNode` from an ordered list of params.
+ *
+ * @example
+ * ```ts
+ * createFunctionParameters({
+ *   params: [
+ *     createFunctionParameter({ name: 'petId', type: 'string', optional: false }),
+ *     createFunctionParameter({ name: 'config', type: 'RequestConfig', optional: false, default: '{}' }),
+ *   ],
+ * })
+ * ```
+ */
+export function createFunctionParameters(props: Partial<Omit<FunctionParametersNode, 'kind'>> = {}): FunctionParametersNode {
+  return {
+    params: [],
+    ...props,
+    kind: 'FunctionParameters',
+  }
+}