@kubb/ast 5.0.0-beta.5 → 5.0.0-beta.51

package/src/nodes/code.ts

@@ -36,21 +36,21 @@ export type ConstNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Optional explicit type annotation.
    * @example 'Pet'
    */
-  type?: string
+  type?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Whether to append `as const` to the declaration.
    * @default false
    */
-  asConst?: boolean
+  asConst?: boolean | null
   /**
    * Child nodes representing the value of the constant (children of the `Const` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -83,11 +83,11 @@ export type TypeNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Child nodes representing the type body (children of the `Type` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -95,12 +95,6 @@ export type TypeNode = BaseNode & {
   nodes?: Array<CodeNode>
 }
 
-/**
- * Convenience alias for {@link TypeNode}.
- * @deprecated Use `TypeNode` directly.
- */
-export type TypeDeclarationNode = TypeNode
-
 /**
  * AST node representing a TypeScript `function` declaration.
  *
@@ -126,35 +120,35 @@ export type FunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean
+  default?: boolean | null
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string
+  params?: string | null
   /**
    * Whether the function should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean
+  async?: boolean | null
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string
+  returnType?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Child nodes representing the function body (children of the `Function` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -187,40 +181,40 @@ export type ArrowFunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean
+  default?: boolean | null
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string
+  params?: string | null
   /**
    * Whether the arrow function should be exported.
    * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
    * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean
+  async?: boolean | null
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string
+  returnType?: string | null
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode
+  JSDoc?: JSDocNode | null
   /**
    * Render the arrow function body as a single-line expression.
    * @default false
    */
-  singleLine?: boolean
+  singleLine?: boolean | null
   /**
    * Child nodes representing the function body (children of the `Function.Arrow` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -255,7 +249,7 @@ export type TextNode = BaseNode & {
  * AST node representing a line break in the source output.
  *
  * Corresponds to `<br/>` in JSX components. When printed, produces an empty
- * string that — joined with `\n` by `printNodes` — creates a blank line
+ * string that, joined with `\n` by `printNodes` creates a blank line
  * between surrounding code nodes.
  *
  * @example

package/src/nodes/content.ts

@@ -0,0 +1,37 @@
+import type { BaseNode } from './base.ts'
+import type { SchemaNode } from './schema.ts'
+
+/**
+ * AST node representing one content-type entry of a request body or response.
+ *
+ * One entry per content type declared in the spec (e.g. `application/json`,
+ * `multipart/form-data`), each carrying its own body schema.
+ *
+ * @example
+ * ```ts
+ * const content: ContentNode = {
+ *   kind: 'Content',
+ *   contentType: 'application/json',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
+ */
+export type ContentNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Content'
+  /**
+   * The content type for this entry (e.g. `'application/json'`).
+   */
+  contentType: string
+  /**
+   * Body schema for this content type.
+   */
+  schema?: SchemaNode
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `readOnly`/`writeOnly` fields that should be omitted.
+   */
+  keysToOmit?: Array<string> | null
+}

package/src/nodes/file.ts

@@ -4,7 +4,7 @@ import type { CodeNode } from './code.ts'
 /**
  * Supported file extensions.
  */
-export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
+type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
 
 type ImportName = string | Array<string | { propertyName: string; name?: string }>
 
@@ -50,18 +50,18 @@ export type ImportNode = BaseNode & {
    * - `false` generates `import { Type } from './path'`
    * @default false
    */
-  isTypeOnly?: boolean
+  isTypeOnly?: boolean | null
   /**
    * Import entire module as namespace.
    * - `true` generates `import * as Name from './path'`
    * - `false` generates standard import
    * @default false
    */
-  isNameSpace?: boolean
+  isNameSpace?: boolean | null
   /**
    * When set, the import path is resolved relative to this root.
    */
-  root?: string
+  root?: string | null
 }
 
 /**
@@ -94,7 +94,7 @@ export type ExportNode = BaseNode & {
    * @example ['useState']
    * @example 'React'
    */
-  name?: string | Array<string>
+  name?: string | Array<string> | null
   /**
    * Path for the export.
    * @example '@kubb/core'
@@ -106,14 +106,14 @@ export type ExportNode = BaseNode & {
    * - `false` generates `export { Type } from './path'`
    * @default false
    */
-  isTypeOnly?: boolean
+  isTypeOnly?: boolean | null
   /**
    * Export as an aliased namespace.
    * - `true` generates `export * as aliasName from './path'`
    * - `false` generates a standard export
    * @default false
    */
-  asAlias?: boolean
+  asAlias?: boolean | null
 }
 
 /**
@@ -134,22 +134,22 @@ export type SourceNode = BaseNode & {
   /**
    * Optional name identifying this source (used for deduplication and barrel generation).
    */
-  name?: string
+  name?: string | null
   /**
    * Mark this source as a type-only export.
    * @default false
    */
-  isTypeOnly?: boolean
+  isTypeOnly?: boolean | null
   /**
    * Include `export` keyword in the generated source.
    * @default false
    */
-  isExportable?: boolean
+  isExportable?: boolean | null
   /**
    * Include this source in barrel/index file generation.
    * @default false
    */
-  isIndexable?: boolean
+  isIndexable?: boolean | null
   /**
    * Structured child nodes representing the content of this source fragment, in DOM order.
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -180,8 +180,8 @@ export type SourceNode = BaseNode & {
 export type FileNode<TMeta extends object = object> = BaseNode & {
   kind: 'File'
   /**
-   * Unique identifier derived from a SHA256 hash of the file path.
-   * @default hash
+   * Unique identifier derived from a SHA256 hash of the file path. Computed
+   * by `createFile`; callers do not need to provide it.
    */
   id: string
   /**
@@ -221,10 +221,12 @@ export type FileNode<TMeta extends object = object> = BaseNode & {
   meta?: TMeta
   /**
    * Optional banner prepended to the generated file content.
+   * Accepts `null` so `resolver.resolveBanner()` results can be passed directly.
    */
-  banner?: string
+  banner?: string | null
   /**
    * Optional footer appended to the generated file content.
+   * Accepts `null` so `resolver.resolveFooter()` results can be passed directly.
    */
-  footer?: string
+  footer?: string | null
 }

package/src/nodes/function.ts

@@ -4,9 +4,9 @@ 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.
+ * - `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.
+ * - `member` a single named field accessed from a named group type.
  *   TypeScript renders as `PathParams['petId']`.
  *
  * @example Reference variant
@@ -35,7 +35,7 @@ export type ParamsTypeNode = BaseNode & {
 } & (
     | {
         /**
-         * Reference variant — a plain type name or identifier.
+         * Reference variant, a plain type name or identifier.
          * TypeScript renders as-is, e.g. `string`, `QueryParams`, `Partial<Config>`.
          */
         variant: 'reference'
@@ -46,7 +46,7 @@ export type ParamsTypeNode = BaseNode & {
       }
     | {
         /**
-         * Struct variant — an inline anonymous type grouping named fields.
+         * Struct variant, an inline anonymous type grouping named fields.
          * TypeScript renders as `{ key: Type; other?: OtherType }`.
          */
         variant: 'struct'
@@ -61,7 +61,7 @@ export type ParamsTypeNode = BaseNode & {
       }
     | {
         /**
-         * Member variant — a single named field accessed from a group type.
+         * Member variant, a single named field accessed from a group type.
          * TypeScript renders as `Base['key']`.
          */
         variant: 'member'
@@ -122,7 +122,7 @@ export type FunctionParameterNode = BaseNode & {
    */
   rest?: boolean
 } /**
- * Optional parameter — rendered with `?` and may be omitted by the caller.
+ * 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 }
@@ -196,10 +196,10 @@ 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
+ * - `keys`        → `{ id, config }` key names only (for destructuring)
+ * - `values`      → `{ id: id, config: config }` key → value pairs
  */
 export type FunctionParametersNode = BaseNode & {
   /**
@@ -218,6 +218,6 @@ export type FunctionParametersNode = BaseNode & {
 export type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode
 
 /**
- * Handler map keys — one per `FunctionParamNode` kind.
+ * Handler map keys, one per `FunctionParamNode` kind.
  */
 export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'

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,7 +1,8 @@
 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 { OperationNode } from './operation.ts'
+import type { OperationNode, RequestBodyNode } from './operation.ts'
 import type { OutputNode } from './output.ts'
 import type { ParameterNode } from './parameter.ts'
 import type { PropertyNode } from './property.ts'
@@ -9,28 +10,24 @@ 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 { StatusCode } from './http.ts'
+export type { GenericOperationNode, HttpMethod, HttpOperationNode, OperationNode, RequestBodyNode } 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 { InputMeta, InputNode } from './root.ts'
+export type { InputMeta, InputNode, InputStreamNode } from './root.ts'
 export type {
   ArraySchemaNode,
-  ComplexSchemaType,
   DateSchemaNode,
   DatetimeSchemaNode,
   EnumSchemaNode,
-  EnumValueNode,
-  FormatStringSchemaNode,
   IntersectionSchemaNode,
-  Ipv4SchemaNode,
-  Ipv6SchemaNode,
   NumberSchemaNode,
   ObjectSchemaNode,
   PrimitiveSchemaType,
@@ -40,7 +37,6 @@ export type {
   SchemaNode,
   SchemaNodeByType,
   SchemaType,
-  SpecialSchemaType,
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
@@ -74,6 +70,8 @@ export type Node =
   | PropertyNode
   | ParameterNode
   | ResponseNode
+  | RequestBodyNode
+  | ContentNode
   | FunctionParamNode
   | FileNode
   | ImportNode

package/src/nodes/operation.ts

@@ -1,44 +1,67 @@
 import type { BaseNode } from './base.ts'
+import type { ContentNode } from './content.ts'
 import type { ParameterNode } from './parameter.ts'
 import type { ResponseNode } from './response.ts'
-import type { SchemaNode } from './schema.ts'
 
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE'
 
 /**
- * AST node representing one API operation.
+ * Transport an operation belongs to.
+ */
+type OperationProtocol = 'http'
+
+/**
+ * AST node representing an operation request body.
+ *
+ * Body schemas live exclusively inside the `content` array (one entry per content type),
+ * mirroring {@link ResponseNode}.
  *
  * @example
  * ```ts
- * const operation: OperationNode = {
- *   kind: 'Operation',
- *   operationId: 'listPets',
- *   method: 'GET',
- *   path: '/pets',
- *   tags: [],
- *   parameters: [],
- *   responses: [],
+ * const requestBody: RequestBodyNode = {
+ *   kind: 'RequestBody',
+ *   required: true,
+ *   content: [{ kind: 'Content', contentType: 'application/json', schema: createSchema({ type: 'string' }) }],
  * }
  * ```
  */
-export type OperationNode = BaseNode & {
+export type RequestBodyNode = BaseNode & {
   /**
    * Node kind.
    */
-  kind: 'Operation'
+  kind: 'RequestBody'
   /**
-   * Operation identifier, usually from OpenAPI `operationId`.
+   * Human-readable request body description.
    */
-  operationId: string
+  description?: string
   /**
-   * HTTP Method like 'GET'
+   * Whether the request body is required (`requestBody.required: true` in the spec).
+   * When `false` or absent, the generated `data` parameter should be optional.
    */
-  method: HttpMethod
+  required?: boolean
   /**
-   * OpenAPI-style path string, for example `/pets/{petId}`.
-   * Path parameters retain the `{param}` notation from the original spec.
+   * 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`).
    */
-  path: string
+  content?: Array<ContentNode>
+}
+
+/**
+ * Fields shared by every operation, regardless of transport.
+ */
+type OperationNodeBase = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Operation'
+  /**
+   * Operation identifier, usually from OpenAPI `operationId`.
+   */
+  operationId: string
   /**
    * Group labels for the operation.
    * Usually copied from OpenAPI `tags`.
@@ -61,51 +84,64 @@ export type OperationNode = BaseNode & {
    */
   parameters: Array<ParameterNode>
   /**
-   * 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>
-    }>
-  }
+   * Request body for the operation.
+   */
+  requestBody?: RequestBodyNode
   /**
    * Operation responses.
    */
   responses: Array<ResponseNode>
 }
+
+/**
+ * Operation served over HTTP/REST (OpenAPI). `method` and `path` are guaranteed.
+ *
+ * @example
+ * ```ts
+ * const operation: HttpOperationNode = {
+ *   kind: 'Operation',
+ *   operationId: 'listPets',
+ *   protocol: 'http',
+ *   method: 'GET',
+ *   path: '/pets',
+ *   tags: [],
+ *   parameters: [],
+ *   responses: [],
+ * }
+ * ```
+ */
+export type HttpOperationNode = OperationNodeBase & {
+  /**
+   * Transport the operation belongs to.
+   */
+  protocol?: 'http'
+  /**
+   * HTTP method like `'GET'`.
+   */
+  method: HttpMethod
+  /**
+   * OpenAPI-style path string, for example `/pets/{petId}`, with `{param}` notation preserved.
+   */
+  path: string
+}
+
+/**
+ * Operation for a non-HTTP transport. HTTP-only fields are forbidden.
+ */
+export type GenericOperationNode = OperationNodeBase & {
+  /**
+   * Transport the operation belongs to.
+   */
+  protocol?: Exclude<OperationProtocol, 'http'>
+  method?: never
+  path?: never
+}
+
+/**
+ * AST node representing one API operation.
+ *
+ * Discriminated on `protocol`: an {@link HttpOperationNode} (`protocol: 'http'`) guarantees
+ * `method` and `path`, while a {@link GenericOperationNode} omits them. Narrow with
+ * `isHttpOperationNode(node)` or `node.protocol === 'http'` before reading `method`/`path`.
+ */
+export type OperationNode = HttpOperationNode | GenericOperationNode