@kubb/ast 5.0.0-beta.6 → 5.0.0-beta.60

package/src/nodes/function.ts

@@ -1,84 +1,101 @@
+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 & {
+  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 & {
+  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 & {
+  kind: 'ObjectBindingPattern'
   /**
-   * Node kind.
+   * Bound elements, rendered in order.
    */
-  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
-      }
-  )
+  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,103 +107,32 @@ export type ParamsTypeNode = BaseNode & {
  *
  * @example Rest parameter
  * `...name: Type[]`
+ *
+ * @example Destructured group
+ * `{ id, name? }: { id: string; name?: string } = {}`
  */
 export type FunctionParameterNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   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.
+   * Parameter name, or an {@link ObjectBindingPatternNode} for a destructured group.
    */
-  kind: 'ParameterGroup'
+  name: string | ObjectBindingPatternNode
   /**
-   * The individual parameters that form the group.
-   * Rendered as a destructured object or spread inline when `inline` is `true`.
+   * Type annotation as a {@link TypeExpression}. Omit for untyped output.
    */
-  properties: Array<FunctionParameterNode>
+  type?: TypeExpression
   /**
-   * Optional explicit type annotation for the whole group.
-   * When absent, printers auto-compute it from `properties`.
-   */
-  type?: ParamsTypeNode
-  /**
-   * 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
 }
 
 /**
@@ -196,28 +142,142 @@ export type ParameterGroupNode = BaseNode & {
  * Nodes are plain immutable data.
  *
  * 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
+ * - `declaration` → `(id: string, config: Config = {})` function declaration parameters
+ * - `call`        → `(id, { method, url })` function call arguments
  */
 export type FunctionParametersNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'FunctionParameters'
   /**
    * 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
+
+/**
+ * Definition for the {@link ObjectBindingPatternNode}.
+ */
+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
 
 /**
- * Handler map keys — one per `FunctionParamNode` kind.
+ * Definition for the {@link FunctionParametersNode}.
  */
-export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'
+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/http.ts

@@ -2,7 +2,7 @@
  * All supported HTTP status code literals as strings, as used in API specs
  * (for example, `"200"` and `"404"`).
  */
-export type HttpStatusCode =
+type HttpStatusCode =
   // 1xx Informational
   | '100'
   | '101'
@@ -83,37 +83,3 @@ export type HttpStatusCode =
  * ```
  */
 export type StatusCode = HttpStatusCode | 'default'
-
-/**
- * Supported media type strings used in request and response bodies.
- *
- * @example
- * ```ts
- * const mediaType: MediaType = 'application/json'
- * ```
- */
-export type MediaType =
-  // Application
-  | 'application/json'
-  | 'application/xml'
-  | 'application/x-www-form-urlencoded'
-  | 'application/octet-stream'
-  | 'application/pdf'
-  | 'application/zip'
-  | 'application/graphql'
-  // Multipart
-  | 'multipart/form-data'
-  // Text
-  | 'text/plain'
-  | 'text/html'
-  | 'text/csv'
-  | 'text/xml'
-  // Image
-  | 'image/png'
-  | 'image/jpeg'
-  | 'image/gif'
-  | 'image/webp'
-  | 'image/svg+xml'
-  // Audio / Video
-  | 'audio/mpeg'
-  | 'video/mp4'

package/src/nodes/index.ts

@@ -1,36 +1,44 @@
 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'
 import type { ParameterNode } from './parameter.ts'
 import type { PropertyNode } from './property.ts'
+import type { RequestBodyNode } from './requestBody.ts'
 import type { ResponseNode } from './response.ts'
-import type { InputNode } from './root.ts'
 import type { SchemaNode } from './schema.ts'
 
-export type { BaseNode, NodeKind } from './base.ts'
-export type { ArrowFunctionNode, BreakNode, CodeNode, ConstNode, FunctionNode, JSDocNode, JsxNode, TextNode, TypeDeclarationNode, TypeNode } from './code.ts'
+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 { HttpStatusCode, MediaType, StatusCode } from './http.ts'
-export type { HttpMethod, OperationNode } from './operation.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'
 export type { OutputNode } from './output.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
 export type { PropertyNode } from './property.ts'
+export type { RequestBodyNode } from './requestBody.ts'
 export type { ResponseNode } from './response.ts'
-export type { InputMeta, InputNode } from './root.ts'
 export type {
   ArraySchemaNode,
-  ComplexSchemaType,
   DateSchemaNode,
   DatetimeSchemaNode,
   EnumSchemaNode,
-  EnumValueNode,
-  FormatStringSchemaNode,
   IntersectionSchemaNode,
-  Ipv4SchemaNode,
-  Ipv6SchemaNode,
   NumberSchemaNode,
   ObjectSchemaNode,
   PrimitiveSchemaType,
@@ -40,7 +48,6 @@ export type {
   SchemaNode,
   SchemaNodeByType,
   SchemaType,
-  SpecialSchemaType,
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
@@ -74,6 +81,8 @@ export type Node =
   | PropertyNode
   | ParameterNode
   | ResponseNode
+  | RequestBodyNode
+  | ContentNode
   | FunctionParamNode
   | FileNode
   | ImportNode
@@ -81,6 +90,5 @@ export type Node =
   | SourceNode
   | ConstNode
   | TypeNode
-  | ParamsTypeNode
   | FunctionNode
   | ArrowFunctionNode