@kubb/ast 5.0.0-beta.56 → 5.0.0-beta.58

package/src/nodes/function.ts

@@ -1,84 +1,110 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 
 /**
- * AST node representing a language-agnostic type expression used as a function parameter
- * type annotation. Each language printer renders the variant into its own syntax.
+ * A language-agnostic type expression used as a function parameter type annotation.
  *
- * - `struct` an inline anonymous type grouping named fields.
- *   TypeScript renders as `{ petId: string; name?: string }`.
- * - `member` a single named field accessed from a named group type.
- *   TypeScript renders as `PathParams['petId']`.
+ * - 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']`
+ */
+export type TypeExpression = string | TypeLiteralNode | IndexedAccessTypeNode
+
+/**
+ * AST node for an inline anonymous object type grouping named fields.
+ * TypeScript renders as `{ key: Type; other?: OtherType }`.
  *
- * @example Reference variant
+ * @example
  * ```ts
- * createParamsType({ variant: 'reference', name: 'QueryParams' })
- * // QueryParams
+ * createTypeLiteral({ members: [{ name: 'petId', type: 'string', optional: false }] })
+ * // { petId: string }
  * ```
+ */
+export type TypeLiteralNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  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
+  }>
+}
+
+/**
+ * AST node for a single field accessed from a named group type.
+ * TypeScript renders as `objectType['indexType']`.
  *
- * @example Struct variant
+ * @example
  * ```ts
- * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
- * // { petId: string }
+ * createIndexedAccessType({ objectType: 'GetPetPathParams', indexType: 'petId' })
+ * // GetPetPathParams['petId']
  * ```
+ */
+export type IndexedAccessTypeNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'IndexedAccessType'
+  /**
+   * Name of the type being indexed, e.g. `'GetPetPathParams'`.
+   */
+  objectType: string
+  /**
+   * Field key to access, e.g. `'petId'`.
+   */
+  indexType: string
+}
+
+/**
+ * AST node for an object destructuring binding, used as the name of a grouped function parameter.
+ * TypeScript renders as `{ id, name }` or `{ id: renamed }` when `propertyName` differs.
  *
- * @example Member variant
+ * @example
  * ```ts
- * createParamsType({ variant: 'member', base: 'PathParams', key: 'petId' })
- * // PathParams['petId']
+ * createObjectBindingPattern({ elements: [{ name: 'id' }, { name: 'name' }] })
+ * // { id, name }
  * ```
  */
-export type ParamsTypeNode = BaseNode & {
+export type ObjectBindingPatternNode = BaseNode & {
   /**
    * Node kind.
    */
-  kind: 'ParamsType'
-} & (
-    | {
-        /**
-         * Reference variant, a plain type name or identifier.
-         * TypeScript renders as-is, e.g. `string`, `QueryParams`, `Partial<Config>`.
-         */
-        variant: 'reference'
-        /**
-         * The full type name string, e.g. `'string'`, `'QueryParams'`, `'Partial<Config>'`.
-         */
-        name: string
-      }
-    | {
-        /**
-         * Struct variant, an inline anonymous type grouping named fields.
-         * TypeScript renders as `{ key: Type; other?: OtherType }`.
-         */
-        variant: 'struct'
-        /**
-         * Properties of the struct type.
-         */
-        properties: Array<{
-          name: string
-          optional: boolean
-          type: ParamsTypeNode
-        }>
-      }
-    | {
-        /**
-         * Member variant, a single named field accessed from a group type.
-         * TypeScript renders as `Base['key']`.
-         */
-        variant: 'member'
-        /**
-         * Base type name, e.g. `'DeletePetPathParams'`.
-         */
-        base: string
-        /**
-         * The field name to access, e.g. `'petId'`.
-         */
-        key: string
-      }
-  )
+  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
+  }>
+}
 
 /**
  * AST node for 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`
  *
@@ -90,6 +116,9 @@ export type ParamsTypeNode = BaseNode & {
  *
  * @example Rest parameter
  * `...name: Type[]`
+ *
+ * @example Destructured group
+ * `{ id, name? }: { id: string; name?: string } = {}`
  */
 export type FunctionParameterNode = BaseNode & {
   /**
@@ -97,96 +126,25 @@ export type FunctionParameterNode = BaseNode & {
    */
   kind: 'FunctionParameter'
   /**
-   * Parameter name in the generated signature.
-   */
-  name: string
-  /**
-   * Type annotation as a structured {@link ParamsTypeNode}.
-   * Omit for untyped output.
-   *
-   * @example Reference type node
-   * `{ kind: 'ParamsType', variant: 'reference', name: 'string' }` → `petId: string`
-   *
-   * @example Struct type node
-   * `{ kind: 'ParamsType', variant: 'struct', properties: [...] }` → `{ key: Type; other?: OtherType }`
-   *
-   * @example Member type node
-   * `{ kind: 'ParamsType', variant: 'member', base: 'PathParams', key: 'petId' }` → `PathParams['petId']`
-   */
-  type?: ParamsTypeNode
-  /**
-   * When `true` the parameter is emitted as a rest parameter.
-   *
-   * @example Rest parameter
-   * `...name: Type[]`
-   */
-  rest?: boolean
-} /**
- * Optional parameter, rendered with `?` and may be omitted by the caller.
- * Cannot be combined with `default` because a defaulted parameter is already optional.
- */ & (
-    | { optional: true; default?: never }
-    /**
-     * Required parameter, or a parameter with a default value.
-     *
-     * @example Required
-     * `name: Type`
-     *
-     * @example With default
-     * `name: Type = default`
-     */
-    | { optional?: false; default?: string }
-  )
-
-/**
- * AST node for a group of related function parameters treated as a single unit.
- *
- * Each language printer decides how to render this group:
- * - TypeScript/JS: destructured object `{ key1, key2 }: { key1: Type1; key2: Type2 } = {}`
- * - Python: keyword-only args or a typed dict parameter
- * - C# / Kotlin: named record / data-class parameter
- *
- * When `inline` is `true`, the group is spread as individual top-level parameters
- * rather than wrapped in a single grouped construct.
- *
- * @example Grouped destructuring
- * `{ id, name }: { id: string; name: string } = {}`
- *
- * @example Inline (spread as individual parameters)
- * `id: string, name: string`
- */
-export type ParameterGroupNode = BaseNode & {
-  /**
-   * Node kind.
-   */
-  kind: 'ParameterGroup'
-  /**
-   * The individual parameters that form the group.
-   * Rendered as a destructured object or spread inline when `inline` is `true`.
+   * Parameter name, or an {@link ObjectBindingPatternNode} for a destructured group.
    */
-  properties: Array<FunctionParameterNode>
+  name: string | ObjectBindingPatternNode
   /**
-   * Optional explicit type annotation for the whole group.
-   * When absent, printers auto-compute it from `properties`.
+   * Type annotation as a {@link TypeExpression}. Omit for untyped output.
    */
-  type?: ParamsTypeNode
+  type?: TypeExpression
   /**
-   * When `true`, `properties` are emitted as individual top-level parameters instead of
-   * being wrapped in a single grouped construct.
-   *
-   * @default false
-   */
-  inline?: boolean
-  /**
-   * Whether the group as a whole is optional.
-   * If omitted, printers infer this from child properties.
+   * Whether the parameter is optional, rendered with `?`.
    */
   optional?: boolean
   /**
-   * Default value for the group, written verbatim after `=`.
-   * Commonly `'{}'` to allow omitting the argument entirely.
+   * 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
 }
 
 /**
@@ -198,8 +156,6 @@ export type ParameterGroupNode = BaseNode & {
  * Renders differently depending on the output mode:
  * - `declaration` → `(id: string, config: Config = {})` function declaration parameters
  * - `call`        → `(id, { method, url })` function call arguments
- * - `keys`        → `{ id, config }` key names only (for destructuring)
- * - `values`      → `{ id: id, config: config }` key → value pairs
  */
 export type FunctionParametersNode = BaseNode & {
   /**
@@ -209,15 +165,134 @@ export type FunctionParametersNode = BaseNode & {
   /**
    * Ordered parameter nodes.
    */
-  params: ReadonlyArray<FunctionParameterNode | ParameterGroupNode>
+  params: ReadonlyArray<FunctionParameterNode>
 }
 
 /**
  * Union of all function-parameter AST node variants used by the function-parameter printer.
  */
-export type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode
+export type FunctionParamNode = FunctionParameterNode | FunctionParametersNode | TypeLiteralNode | IndexedAccessTypeNode | ObjectBindingPatternNode
+
+/**
+ * Handler-map keys for the function-parameter printer, one per {@link FunctionParamNode} kind.
+ */
+export type FunctionParamKind = FunctionParamNode['kind']
+
+/**
+ * Definition for the {@link TypeLiteralNode}.
+ */
+export const typeLiteralDef = defineNode<TypeLiteralNode, Pick<TypeLiteralNode, 'members'>>({ kind: 'TypeLiteral' })
+
+/**
+ * Creates a {@link TypeLiteralNode} representing an inline anonymous object type.
+ *
+ * @example
+ * ```ts
+ * createTypeLiteral({ members: [{ name: 'petId', type: 'string', optional: false }] })
+ * // { petId: string }
+ * ```
+ */
+export const createTypeLiteral = typeLiteralDef.create
+
+/**
+ * Definition for the {@link IndexedAccessTypeNode}.
+ */
+export const indexedAccessTypeDef = defineNode<IndexedAccessTypeNode, Omit<IndexedAccessTypeNode, 'kind'>>({ kind: 'IndexedAccessType' })
+
+/**
+ * Creates an {@link IndexedAccessTypeNode} representing a single field accessed from a named type.
+ *
+ * @example
+ * ```ts
+ * createIndexedAccessType({ objectType: 'DeletePetPathParams', indexType: 'petId' })
+ * // DeletePetPathParams['petId']
+ * ```
+ */
+export const createIndexedAccessType = indexedAccessTypeDef.create
 
 /**
- * Handler map keys, one per `FunctionParamNode` kind.
+ * Definition for the {@link ObjectBindingPatternNode}.
  */
-export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'
+export const objectBindingPatternDef = defineNode<ObjectBindingPatternNode, Pick<ObjectBindingPatternNode, 'elements'>>({ kind: 'ObjectBindingPattern' })
+
+/**
+ * Creates an {@link ObjectBindingPatternNode} for a destructured parameter binding.
+ *
+ * @example
+ * ```ts
+ * createObjectBindingPattern({ elements: [{ name: 'id' }, { name: 'name' }] })
+ * // { id, name }
+ * ```
+ */
+export const createObjectBindingPattern = objectBindingPatternDef.create
+
+/**
+ * Plain property descriptor for a destructured group built by {@link createFunctionParameter}.
+ */
+type FunctionParameterProperty = {
+  name: string
+  type: TypeExpression
+  optional?: boolean
+}
+
+type FunctionParameterInput =
+  | { name: string; type?: TypeExpression; optional?: boolean; default?: string; rest?: boolean }
+  | { properties: Array<FunctionParameterProperty>; optional?: boolean; default?: string }
+
+/**
+ * Definition for the {@link FunctionParameterNode}. `optional` defaults to `false`.
+ * Passing `properties` builds a destructured group: an {@link ObjectBindingPatternNode} name
+ * paired with a {@link TypeLiteralNode} type.
+ */
+export const functionParameterDef = defineNode<FunctionParameterNode, FunctionParameterInput>({
+  kind: 'FunctionParameter',
+  build: (input) => {
+    if ('properties' in input) {
+      return {
+        name: createObjectBindingPattern({ elements: input.properties.map((p) => ({ name: p.name })) }),
+        type: createTypeLiteral({ members: input.properties.map((p) => ({ name: p.name, type: p.type, optional: p.optional ?? false })) }),
+        optional: input.optional ?? false,
+        ...(input.default !== undefined ? { default: input.default } : {}),
+      }
+    }
+    return { optional: false, ...input }
+  },
+})
+
+/**
+ * Creates a `FunctionParameterNode`. `optional` defaults to `false`.
+ *
+ * @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 } = {}
+ * ```
+ */
+export const createFunctionParameter = functionParameterDef.create
+
+/**
+ * Definition for the {@link FunctionParametersNode}.
+ */
+export const functionParametersDef = defineNode<FunctionParametersNode, Partial<Omit<FunctionParametersNode, 'kind'>>>({
+  kind: 'FunctionParameters',
+  defaults: { params: [] },
+})
+
+/**
+ * Creates a `FunctionParametersNode` from an ordered list of parameters.
+ *
+ * @example
+ * ```ts
+ * const empty = createFunctionParameters()
+ * // { kind: 'FunctionParameters', params: [] }
+ * ```
+ */
+export function createFunctionParameters(props: Partial<Omit<FunctionParametersNode, 'kind'>> = {}): FunctionParametersNode {
+  return functionParametersDef.create(props)
+}

package/src/nodes/index.ts

@@ -1,7 +1,7 @@
 import type { ArrowFunctionNode, ConstNode, FunctionNode, TypeNode } from './code.ts'
 import type { ContentNode } from './content.ts'
 import type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
-import type { FunctionParamNode, ParamsTypeNode } from './function.ts'
+import type { FunctionParamNode } from './function.ts'
 import type { InputNode } from './input.ts'
 import type { OperationNode } from './operation.ts'
 import type { OutputNode } from './output.ts'
@@ -15,7 +15,16 @@ export type { NodeKind } from './base.ts'
 export type { ArrowFunctionNode, BreakNode, CodeNode, ConstNode, FunctionNode, JSDocNode, JsxNode, TextNode, TypeNode } from './code.ts'
 export type { ContentNode } from './content.ts'
 export type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
-export type { FunctionNodeType, FunctionParameterNode, FunctionParametersNode, FunctionParamNode, ParameterGroupNode, ParamsTypeNode } from './function.ts'
+export type {
+  FunctionParamKind,
+  FunctionParameterNode,
+  FunctionParametersNode,
+  FunctionParamNode,
+  IndexedAccessTypeNode,
+  ObjectBindingPatternNode,
+  TypeExpression,
+  TypeLiteralNode,
+} from './function.ts'
 export type { StatusCode } from './http.ts'
 export type { InputMeta, InputNode } from './input.ts'
 export type { GenericOperationNode, HttpMethod, HttpOperationNode, OperationNode } from './operation.ts'
@@ -81,6 +90,5 @@ export type Node =
   | SourceNode
   | ConstNode
   | TypeNode
-  | ParamsTypeNode
   | FunctionNode
   | ArrowFunctionNode

package/src/nodes/input.ts

@@ -1,4 +1,5 @@
 import type { Streamable } from '@internals/utils'
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
@@ -101,3 +102,39 @@ export type InputNode<Stream extends boolean = false> = BaseNode & {
    */
   operations: Streamable<OperationNode, Stream>
 } & (Stream extends true ? { meta?: InputMeta } : { meta: InputMeta })
+
+/**
+ * Definition for the {@link InputNode}.
+ */
+export const inputDef = defineNode<InputNode, Partial<Omit<InputNode, 'kind'>>>({
+  kind: 'Input',
+  defaults: { schemas: [], operations: [], meta: { circularNames: [], enumNames: [] } },
+  children: ['schemas', 'operations'],
+  visitorKey: 'input',
+})
+
+/**
+ * Creates an `InputNode`. Pass `stream: true` for the streaming variant whose `schemas` and
+ * `operations` are `AsyncIterable` sources and whose `meta` is optional. Otherwise it builds the
+ * eager variant with array `schemas`/`operations` and the defaulted `meta`.
+ *
+ * @example Eager
+ * ```ts
+ * const input = createInput()
+ * // { kind: 'Input', schemas: [], operations: [] }
+ * ```
+ *
+ * @example Streaming
+ * ```ts
+ * const node = createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta: { title: 'My API' } })
+ * ```
+ */
+export function createInput<Stream extends boolean = false>(options: Partial<Omit<InputNode<Stream>, 'kind'>> & { stream?: Stream } = {}): InputNode<Stream> {
+  const { stream, ...overrides } = options
+  // Streaming inputs carry AsyncIterable sources, so skip the array/meta defaults that
+  // inputDef.create applies for the eager variant.
+  if (stream) {
+    return { kind: 'Input', ...overrides } as InputNode<Stream>
+  }
+  return inputDef.create(overrides as Partial<Omit<InputNode, 'kind'>>) as InputNode<Stream>
+}

package/src/nodes/operation.ts

@@ -1,6 +1,7 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { ParameterNode } from './parameter.ts'
-import type { RequestBodyNode } from './requestBody.ts'
+import { createRequestBody, type RequestBodyNode, type UserRequestBody } from './requestBody.ts'
 import type { ResponseNode } from './response.ts'
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
@@ -105,3 +106,60 @@ export type GenericOperationNode = OperationNodeBase & {
  * `isHttpOperationNode(node)` or `node.protocol === 'http'` before reading `method`/`path`.
  */
 export type OperationNode = HttpOperationNode | GenericOperationNode
+
+type OperationInput = {
+  operationId: string
+  method?: HttpOperationNode['method']
+  path?: HttpOperationNode['path']
+  requestBody?: UserRequestBody
+  [key: string]: unknown
+}
+
+/**
+ * Definition for the {@link OperationNode}. HTTP operations (those carrying both
+ * `method` and `path`) are tagged with `protocol: 'http'`, and the request body is
+ * normalized into a `RequestBodyNode`.
+ */
+export const operationDef = defineNode<OperationNode, OperationInput>({
+  kind: 'Operation',
+  build: (props) => {
+    const { requestBody, ...rest } = props
+    const isHttp = rest.method !== undefined && rest.path !== undefined
+
+    return {
+      tags: [],
+      parameters: [],
+      responses: [],
+      ...rest,
+      ...(isHttp ? { protocol: 'http' as const } : {}),
+      requestBody: requestBody ? createRequestBody(requestBody) : undefined,
+    }
+  },
+  children: ['parameters', 'requestBody', 'responses'],
+  visitorKey: 'operation',
+})
+
+/**
+ * Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
+ *
+ * @example
+ * ```ts
+ * const operation = createOperation({ operationId: 'getPetById', method: 'GET', path: '/pet/{petId}' })
+ * // tags, parameters, and responses are []
+ * ```
+ */
+export function createOperation(
+  props: Pick<HttpOperationNode, 'operationId' | 'method' | 'path'> &
+    Partial<Omit<HttpOperationNode, 'kind' | 'operationId' | 'method' | 'path' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): HttpOperationNode
+export function createOperation(
+  props: Pick<GenericOperationNode, 'operationId'> &
+    Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): GenericOperationNode
+export function createOperation(props: OperationInput): OperationNode {
+  return operationDef.create(props)
+}

package/src/nodes/output.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { FileNode } from './file.ts'
 
@@ -24,3 +25,25 @@ export type OutputNode = BaseNode & {
    */
   files: Array<FileNode>
 }
+
+/**
+ * Definition for the {@link OutputNode}.
+ */
+export const outputDef = defineNode<OutputNode, Partial<Omit<OutputNode, 'kind'>>>({
+  kind: 'Output',
+  defaults: { files: [] },
+  visitorKey: 'output',
+})
+
+/**
+ * Creates an `OutputNode` with a stable default for `files`.
+ *
+ * @example
+ * ```ts
+ * const output = createOutput()
+ * // { kind: 'Output', files: [] }
+ * ```
+ */
+export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}): OutputNode {
+  return outputDef.create(overrides)
+}

package/src/nodes/parameter.ts

@@ -1,3 +1,4 @@
+import { defineNode, syncOptionality } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -39,3 +40,35 @@ export type ParameterNode = BaseNode & {
    */
   required: boolean
 }
+
+type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>
+
+/**
+ * Definition for the {@link ParameterNode}. `required` defaults to `false` and the
+ * schema's `optional`/`nullish` flags are kept in sync with it.
+ */
+export const parameterDef = defineNode<ParameterNode, UserParameterNode>({
+  kind: 'Parameter',
+  build: (props) => {
+    const required = props.required ?? false
+    return { ...props, required, schema: syncOptionality(props.schema, required) }
+  },
+  children: ['schema'],
+  visitorKey: 'parameter',
+  rebuild: true,
+})
+
+/**
+ * Creates a `ParameterNode`.
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'petId',
+ *   in: 'path',
+ *   required: true,
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * ```
+ */
+export const createParameter = parameterDef.create