@kubb/ast 5.0.0-alpha.9 → 5.0.0-beta.75

package/src/nodes/function.ts

@@ -0,0 +1,223 @@
+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.
+ *
+ * - `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']`.
+ *
+ * @example Reference variant
+ * ```ts
+ * createParamsType({ variant: 'reference', name: 'QueryParams' })
+ * // QueryParams
+ * ```
+ *
+ * @example Struct variant
+ * ```ts
+ * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
+ * // { petId: string }
+ * ```
+ *
+ * @example Member variant
+ * ```ts
+ * createParamsType({ variant: 'member', base: 'PathParams', key: 'petId' })
+ * // PathParams['petId']
+ * ```
+ */
+export type ParamsTypeNode = 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
+      }
+  )
+
+/**
+ * AST node for one function parameter.
+ *
+ * @example Required parameter
+ * `name: Type`
+ *
+ * @example Optional parameter
+ * `name?: Type`
+ *
+ * @example Parameter with default value
+ * `name: Type = defaultValue`
+ *
+ * @example Rest parameter
+ * `...name: Type[]`
+ */
+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.
+   */
+  kind: 'ParameterGroup'
+  /**
+   * The individual parameters that form the group.
+   * Rendered as a destructured object or spread inline when `inline` is `true`.
+   */
+  properties: Array<FunctionParameterNode>
+  /**
+   * 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.
+   */
+  optional?: boolean
+  /**
+   * Default value for the group, written verbatim after `=`.
+   * Commonly `'{}'` to allow omitting the argument entirely.
+   */
+  default?: string
+}
+
+/**
+ * AST node for a complete function parameter list.
+ *
+ * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
+ * 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
+ */
+export type FunctionParametersNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'FunctionParameters'
+  /**
+   * Ordered parameter nodes.
+   */
+  params: ReadonlyArray<FunctionParameterNode | ParameterGroupNode>
+}
+
+/**
+ * Union of all function-parameter AST node variants used by the function-parameter printer.
+ */
+export type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode
+
+/**
+ * Handler map keys — one per `FunctionParamNode` kind.
+ */
+export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'

package/src/nodes/http.ts

@@ -1,6 +1,6 @@
 /**
- * All IANA-registered HTTP status codes as string literals, matching how
- * they appear as keys in API specifications (e.g. `"200"`, `"404"`).
+ * All supported HTTP status code literals as strings, as used in API specs
+ * (for example, `"200"` and `"404"`).
  */
 export type HttpStatusCode =
   // 1xx Informational
@@ -72,13 +72,25 @@ export type HttpStatusCode =
   | '511'
 
 /**
- * A status code as used in an operation response: a specific HTTP status
- * code string or `"default"` as a catch-all fallback.
+ * Response status code literal used by operations.
+ *
+ * Includes specific HTTP status code strings and `"default"` for catch-all responses.
+ *
+ * @example
+ * ```ts
+ * const status: StatusCode = '200'
+ * const fallback: StatusCode = 'default'
+ * ```
  */
 export type StatusCode = HttpStatusCode | 'default'
 
 /**
- * Common IANA media types used in API request/response bodies.
+ * Supported media type strings used in request and response bodies.
+ *
+ * @example
+ * ```ts
+ * const mediaType: MediaType = 'application/json'
+ * ```
  */
 export type MediaType =
   // Application

package/src/nodes/index.ts

@@ -1,17 +1,25 @@
+import type { ArrowFunctionNode, ConstNode, FunctionNode, TypeNode } from './code.ts'
+import type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
+import type { FunctionParamNode, ParamsTypeNode } from './function.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 { ResponseNode } from './response.ts'
-import type { RootNode } from './root.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 { 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 { OutputNode } from './output.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
 export type { PropertyNode } from './property.ts'
 export type { ResponseNode } from './response.ts'
-export type { RootMeta, RootNode } from './root.ts'
+export type { InputMeta, InputNode } from './root.ts'
 export type {
   ArraySchemaNode,
   ComplexSchemaType,
@@ -19,7 +27,10 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FormatStringSchemaNode,
   IntersectionSchemaNode,
+  Ipv4SchemaNode,
+  Ipv6SchemaNode,
   NumberSchemaNode,
   ObjectSchemaNode,
   PrimitiveSchemaType,
@@ -37,10 +48,39 @@ export type {
 } from './schema.ts'
 
 /**
- * Discriminated union of every AST node.
+ * Union of all AST node types.
  *
- * Using a concrete union (instead of the bare `BaseNode` alias) lets
- * TypeScript narrow the type automatically inside `switch (node.kind)`
- * blocks, eliminating the need for manual `as TypeName` casts.
+ * This lets TypeScript narrow types in `switch (node.kind)` blocks.
+ *
+ * @example
+ * ```ts
+ * function getKind(node: Node): string {
+ *   switch (node.kind) {
+ *     case 'Input':
+ *       return 'input'
+ *     case 'Output':
+ *       return 'output'
+ *     default:
+ *       return 'other'
+ *   }
+ * }
+ * ```
  */
-export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode
+export type Node =
+  | InputNode
+  | OutputNode
+  | OperationNode
+  | SchemaNode
+  | PropertyNode
+  | ParameterNode
+  | ResponseNode
+  | FunctionParamNode
+  | FileNode
+  | ImportNode
+  | ExportNode
+  | SourceNode
+  | ConstNode
+  | TypeNode
+  | ParamsTypeNode
+  | FunctionNode
+  | ArrowFunctionNode

package/src/nodes/operation.ts

@@ -6,28 +6,106 @@ import type { SchemaNode } from './schema.ts'
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
 
 /**
- * A spec-agnostic representation of a single API operation.
+ * AST node representing one API operation.
+ *
+ * @example
+ * ```ts
+ * const operation: OperationNode = {
+ *   kind: 'Operation',
+ *   operationId: 'listPets',
+ *   method: 'GET',
+ *   path: '/pets',
+ *   tags: [],
+ *   parameters: [],
+ *   responses: [],
+ * }
+ * ```
  */
 export type OperationNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Operation'
   /**
-   * Unique operation identifier (maps to `operationId` in OAS).
+   * Operation identifier, usually from OpenAPI `operationId`.
    */
   operationId: string
+  /**
+   * HTTP Method like 'GET'
+   */
   method: HttpMethod
   /**
-   * Express-style path string, e.g. `/pets/:petId`.
-   * Derived from the OpenAPI path by converting `{param}` tokens to `:param`.
+   * OpenAPI-style path string, for example `/pets/{petId}`.
+   * Path parameters retain the `{param}` notation from the original spec.
    */
   path: string
+  /**
+   * Group labels for the operation.
+   * Usually copied from OpenAPI `tags`.
+   */
   tags: Array<string>
+  /**
+   * Short one-line operation summary.
+   */
   summary?: string
+  /**
+   * Full operation description.
+   */
   description?: string
+  /**
+   * Marks the operation as deprecated.
+   */
   deprecated?: boolean
+  /**
+   * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
+   */
   parameters: Array<ParameterNode>
   /**
-   * Request body schema. For OAS, this is the schema of the first content entry.
+   * Request body metadata for the operation.
+   */
+  requestBody?: {
+    /**
+     * Human-readable request body description.
+     */
+    description?: string
+    /**
+     * Whether the request body is required (`requestBody.required: true` in the spec).
+     * When `false` or absent, the generated `data` parameter should be optional.
+     */
+    required?: boolean
+    /**
+     * All available content type entries for this request body.
+     *
+     * When the adapter `contentType` option is set, this array contains exactly one entry for
+     * that content type. Otherwise it contains one entry per content type declared in the spec,
+     * so that plugins can generate code for every variant (e.g. separate hooks for
+     * `application/json` and `multipart/form-data`).
+     *
+     * @example
+     * ```ts
+     * // spec has both application/json and multipart/form-data
+     * requestBody.content[0].contentType // 'application/json'
+     * requestBody.content[1].contentType // 'multipart/form-data'
+     * ```
+     */
+    content?: Array<{
+      /**
+       * The content type for this entry (e.g. `'application/json'`).
+       */
+      contentType: string
+      /**
+       * Request body schema for this content type.
+       */
+      schema?: SchemaNode
+      /**
+       * Property keys to exclude from the generated request body type via `Omit<Type, Keys>`.
+       * Set when a referenced schema has `readOnly` fields that should be omitted in request types.
+       */
+      keysToOmit?: Array<string>
+    }>
+  }
+  /**
+   * Operation responses.
    */
-  requestBody?: SchemaNode
   responses: Array<ResponseNode>
 }

package/src/nodes/output.ts

@@ -0,0 +1,26 @@
+import type { BaseNode } from './base.ts'
+import type { FileNode } from './file.ts'
+
+/**
+ * Output AST node that groups all generated file output for one API document.
+ *
+ * Produced by generators and consumed by the build pipeline to write files.
+ *
+ * @example
+ * ```ts
+ * const output: OutputNode = {
+ *   kind: 'Output',
+ *   files: [],
+ * }
+ * ```
+ */
+export type OutputNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Output'
+  /**
+   * Generated file nodes.
+   */
+  files: Array<FileNode>
+}

package/src/nodes/parameter.ts

@@ -4,12 +4,38 @@ import type { SchemaNode } from './schema.ts'
 export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
 
 /**
- * A single input parameter for an operation.
+ * AST node representing one operation parameter.
+ *
+ * @example
+ * ```ts
+ * const param: ParameterNode = {
+ *   kind: 'Parameter',
+ *   name: 'petId',
+ *   in: 'path',
+ *   schema: createSchema({ type: 'string' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type ParameterNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Parameter'
+  /**
+   * Parameter name.
+   */
   name: string
+  /**
+   * Parameter location (`path`, `query`, `header`, or `cookie`).
+   */
   in: ParameterLocation
+  /**
+   * Parameter schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the parameter is required.
+   */
   required: boolean
 }

package/src/nodes/property.ts

@@ -2,11 +2,33 @@ import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A named property within an object schema.
+ * AST node representing one named object property.
+ *
+ * @example
+ * ```ts
+ * const property: PropertyNode = {
+ *   kind: 'Property',
+ *   name: 'id',
+ *   schema: createSchema({ type: 'integer' }),
+ *   required: true,
+ * }
+ * ```
  */
 export type PropertyNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Property'
+  /**
+   * Property key.
+   */
   name: string
+  /**
+   * Property schema.
+   */
   schema: SchemaNode
+  /**
+   * Whether the property is required.
+   */
   required: boolean
 }

package/src/nodes/response.ts

@@ -3,15 +3,41 @@ import type { MediaType, StatusCode } from './http.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * A single response variant for an operation.
+ * AST node representing one operation response variant.
+ *
+ * @example
+ * ```ts
+ * const response: ResponseNode = {
+ *   kind: 'Response',
+ *   statusCode: '200',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
  */
 export type ResponseNode = BaseNode & {
+  /**
+   * Node kind.
+   */
   kind: 'Response'
   /**
    * HTTP status code or `'default'` for a fallback response.
    */
   statusCode: StatusCode
+  /**
+   * Optional response description.
+   */
   description?: string
+  /**
+   * Response body schema.
+   */
   schema: SchemaNode
-  mediaType?: MediaType
+  /**
+   * Response media type.
+   */
+  mediaType?: MediaType | null
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `writeOnly` fields that should not appear in response types.
+   */
+  keysToOmit?: Array<string>
 }

package/src/nodes/root.ts

@@ -3,10 +3,15 @@ import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * Format-agnostic metadata about the API document.
- * Adapters populate whichever fields are available in their source format.
+ * Basic metadata for an API document.
+ * Adapters fill fields that exist in their source format.
+ *
+ * @example
+ * ```ts
+ * const meta: InputMeta = { title: 'Pet API', version: '1.0.0' }
+ * ```
  */
-export type RootMeta = {
+export type InputMeta = {
   /**
    * API title (from `info.title` in OAS/AsyncAPI).
    */
@@ -20,23 +25,40 @@ export type RootMeta = {
    */
   version?: string
   /**
-   * Resolved base URL for the API.
-   * OAS: derived from `servers[serverIndex].url` with variable substitution.
-   * AsyncAPI: derived from `servers[serverIndex].url`.
-   * Drizzle / schema-only formats: not set.
+   * Resolved API base URL.
+   * For OpenAPI and AsyncAPI, this comes from the selected server URL.
    */
   baseURL?: string
 }
 
 /**
- * Top-level container for all schemas and operations in a single API document.
+ * Input AST node that contains all schemas and operations for one API document.
+ * Produced by the adapter and consumed by all Kubb plugins.
+ *
+ * @example
+ * ```ts
+ * const input: InputNode = {
+ *   kind: 'Input',
+ *   schemas: [],
+ *   operations: [],
+ * }
+ * ```
  */
-export type RootNode = BaseNode & {
-  kind: 'Root'
+export type InputNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Input'
+  /**
+   * All schema nodes in the document.
+   */
   schemas: Array<SchemaNode>
+  /**
+   * All operation nodes in the document.
+   */
   operations: Array<OperationNode>
   /**
-   * Format-agnostic document metadata populated by the adapter.
+   * Optional document metadata populated by the adapter.
    */
-  meta?: RootMeta
+  meta?: InputMeta
 }