@kubb/ast 5.0.0-beta.3 → 5.0.0-beta.31

package/src/infer.ts

@@ -20,15 +20,25 @@ import type {
  */
 export type ParserOptions = {
   /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   * How `format: 'date-time'` schemas are represented downstream.
+   * - `false` falls through to a plain `string` (no validation).
+   * - `'string'` emits a datetime string node.
+   * - `'stringOffset'` emits a datetime node with timezone offset.
+   * - `'stringLocal'` emits a local datetime node.
+   * - `'date'` emits a `date` node (JavaScript `Date` object).
    */
   dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
   /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   * How `type: 'integer'` (and `format: 'int64'`) maps to TypeScript.
+   * - `'number'` fits most JSON APIs; loses precision above `Number.MAX_SAFE_INTEGER`.
+   * - `'bigint'` is exact for 64-bit IDs, but does not round-trip through JSON.
+   *
+   * @default 'number'
    */
   integerType?: 'number' | 'bigint'
   /**
-   * AST type used when no schema type can be inferred.
+   * AST type used when a schema's type cannot be inferred from the spec
+   * (`additionalProperties: true`, missing `type`, ...).
    */
   unknownType: 'any' | 'unknown' | 'void'
   /**
@@ -36,7 +46,8 @@ export type ParserOptions = {
    */
   emptySchemaType: 'any' | 'unknown' | 'void'
   /**
-   * Suffix appended to derived enum names when building property schema names.
+   * Suffix appended to derived enum names when Kubb has to invent one
+   * (typically for inline enums on object properties).
    */
   enumSuffix: 'enum' | (string & {})
 }
@@ -66,7 +77,7 @@ type ResolveDateTimeNode<TDateType extends ParserOptions['dateType']> = DateTime
 type SchemaNodeMap<TDateType extends ParserOptions['dateType'] = 'string'> = [
   [{ $ref: string }, RefSchemaNode],
   [{ allOf: ReadonlyArray<unknown>; properties: object }, IntersectionSchemaNode],
-  [{ allOf: readonly [unknown, unknown, ...unknown[]] }, IntersectionSchemaNode],
+  [{ allOf: readonly [unknown, unknown, ...Array<unknown>] }, IntersectionSchemaNode],
   [{ allOf: ReadonlyArray<unknown> }, SchemaNode],
   [{ oneOf: ReadonlyArray<unknown> }, UnionSchemaNode],
   [{ anyOf: ReadonlyArray<unknown> }, UnionSchemaNode],

package/src/nodes/base.ts

@@ -14,6 +14,8 @@ export type NodeKind =
   | 'Property'
   | 'Parameter'
   | 'Response'
+  | 'RequestBody'
+  | 'Content'
   | 'FunctionParameter'
   | 'ParameterGroup'
   | 'FunctionParameters'

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.
@@ -126,35 +126,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 +187,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.

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

@@ -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/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'
@@ -11,15 +12,16 @@ 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 { 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 { GenericOperationNode, HttpMethod, HttpOperationNode, OperationNode, OperationNodeBase, OperationProtocol, 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,
@@ -74,6 +76,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.
+ */
+export 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.
+ */
+export 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

package/src/nodes/response.ts

@@ -1,16 +1,20 @@
 import type { BaseNode } from './base.ts'
-import type { MediaType, StatusCode } from './http.ts'
-import type { SchemaNode } from './schema.ts'
+import type { ContentNode } from './content.ts'
+import type { StatusCode } from './http.ts'
 
 /**
  * AST node representing one operation response variant.
  *
+ * Mirrors {@link OperationNode.requestBody}: the response body schemas live exclusively inside
+ * the `content` array (one entry per content type), so the same schema is never duplicated at the
+ * node root and inside `content`.
+ *
  * @example
  * ```ts
  * const response: ResponseNode = {
  *   kind: 'Response',
  *   statusCode: '200',
- *   schema: createSchema({ type: 'string' }),
+ *   content: [{ contentType: 'application/json', schema: createSchema({ type: 'string' }) }],
  * }
  * ```
  */
@@ -28,16 +32,19 @@ export type ResponseNode = BaseNode & {
    */
   description?: string
   /**
-   * Response body schema.
-   */
-  schema: SchemaNode
-  /**
-   * 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.
+   * All available content type entries for this response.
+   *
+   * 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 a union of response types (e.g. `application/json` and `application/xml`).
+   * Body-less responses keep a single entry whose `schema` is the empty/`void` placeholder.
+   *
+   * @example
+   * ```ts
+   * // spec response declares both application/json and application/xml
+   * response.content[0].contentType // 'application/json'
+   * response.content[1].contentType // 'application/xml'
+   * ```
    */
-  keysToOmit?: Array<string>
+  content?: Array<ContentNode>
 }