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

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.3",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.30",
+  "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",
     "codegen",
     "kubb",
-    "openapi",
     "typescript"
   ],
   "license": "MIT",
@@ -40,7 +39,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^22.19.19",
     "@internals/utils": "0.0.0"
   },
   "engines": {

package/src/dialect.ts

@@ -0,0 +1,64 @@
+/**
+ * The spec-specific decisions a schema parser makes while converting a source
+ * document's schemas into Kubb AST nodes.
+ *
+ * Everything else in an adapter's schema pipeline is generic JSON Schema shared
+ * across specs; the dialect is the one seam where a spec differs — the
+ * "dialect layer" analogue of a database driver targeting Postgres vs MySQL.
+ * Pair it with {@link dispatch}: the rule table decides *which* converter runs,
+ * the dialect answers the spec-specific questions inside them.
+ *
+ * The guard methods (`isReference`, `isDiscriminator`) are type predicates so
+ * converters narrow the schema after a check; the type parameters carry those
+ * narrowed types through.
+ *
+ * Scope: this is the seam for the **JSON Schema family** — OpenAPI, AsyncAPI, and
+ * plain JSON Schema all share `$ref`, `allOf`/`oneOf`, `enum`, and `format`, and
+ * differ only in these few decisions. A spec built on a different type system
+ * (e.g. GraphQL, with non-null wrappers, interfaces, and named-type references
+ * instead of `$ref`) does not implement a `SchemaDialect`; it reuses the universal
+ * layer directly — the `Adapter` port, the AST factories, and {@link dispatch}
+ * with its own rule table — to emit the same nodes.
+ *
+ * @typeParam TSchema - The adapter's schema object type (e.g. an OpenAPI `SchemaObject`).
+ * @typeParam TRef - The narrowed `$ref` pointer type `isReference` proves.
+ * @typeParam TDiscriminated - The narrowed discriminated-schema type `isDiscriminator` proves.
+ * @typeParam TDocument - The source document `resolveRef` resolves against.
+ */
+export type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
+  /** Identifies the dialect in logs and while debugging dispatch. */
+  name: string
+  /** Whether a schema should be treated as nullable. */
+  isNullable: (schema?: TSchema) => boolean
+  /** Whether a value is a `$ref` pointer object. */
+  isReference: (value?: unknown) => value is TRef
+  /** Whether a schema carries a structured discriminator (polymorphism). */
+  isDiscriminator: (value?: unknown) => value is TDiscriminated
+  /** Whether a schema represents binary data (converted to a `blob` node). */
+  isBinary: (schema: TSchema) => boolean
+  /** Resolves a local `$ref` pointer against the document, or nullish when it cannot. */
+  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined
+}
+
+/**
+ * Identity helper that types a {@link SchemaDialect} for an adapter. Like
+ * `defineParser`, it adds no runtime behavior — it pins the dialect's type for
+ * inference and gives adapter authors a discoverable anchor.
+ *
+ * @example
+ * ```ts
+ * export const oasDialect = defineSchemaDialect({
+ *   name: 'oas',
+ *   isNullable,
+ *   isReference,
+ *   isDiscriminator,
+ *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+ *   resolveRef,
+ * })
+ * ```
+ */
+export function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(
+  dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>,
+): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument> {
+  return dialect
+}

package/src/dispatch.ts

@@ -0,0 +1,53 @@
+/**
+ * One entry in an ordered dispatch table: a predicate paired with a converter.
+ *
+ * @typeParam TContext - Per-input context handed to every rule. A spec adapter typically
+ *   pre-computes this once per node (the source spec node plus derived fields like a
+ *   normalized type or resolved options) so individual rules stay cheap predicates.
+ * @typeParam TNode - The node a rule produces, e.g. a Kubb AST `SchemaNode`.
+ */
+export type DispatchRule<TContext, TNode> = {
+  /** Identifies the rule when reading the table or debugging which branch ran. */
+  name: string
+  /** Returns `true` when this rule is responsible for the given context. */
+  match: (context: TContext) => boolean
+  /**
+   * Produces a node for the context, or `null` to fall through to the next rule.
+   *
+   * Returning `null` lets a broad `match` defer: e.g. "has a `format`" matches many schemas,
+   * but only some formats are convertible — the rest fall through to plain `type` handling.
+   */
+  convert: (context: TContext) => TNode | null
+}
+
+/**
+ * Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
+ *
+ * This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
+ * The contract an adapter follows is intentionally minimal:
+ *
+ *     context → [rule.match → rule.convert] → node
+ *
+ * An adapter derives a context from a source spec node, then declares an ordered table of
+ * rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
+ * context type and a new rules table — the traversal here is reused unchanged.
+ *
+ * Order is significant: earlier rules win, so list higher-precedence or more specific shapes
+ * first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
+ * may still `convert` to `null` to defer to later rules. When no rule produces a node this
+ * returns `null`, leaving the caller to apply its own fallback.
+ *
+ * @example
+ * ```ts
+ * const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
+ * ```
+ */
+export function dispatch<TContext, TNode>(rules: ReadonlyArray<DispatchRule<TContext, TNode>>, context: TContext): TNode | null {
+  for (const rule of rules) {
+    if (!rule.match(context)) continue
+    const node = rule.convert(context)
+    if (node !== null && node !== undefined) return node
+  }
+
+  return null
+}

package/src/factory.ts

@@ -6,14 +6,20 @@ import type {
   ArrowFunctionNode,
   BreakNode,
   ConstNode,
+  ContentNode,
   ExportNode,
   FileNode,
   FunctionNode,
   FunctionParameterNode,
   FunctionParametersNode,
+  GenericOperationNode,
+  HttpOperationNode,
   ImportNode,
+  InputMeta,
   InputNode,
+  InputStreamNode,
   JsxNode,
+  Node,
   ObjectSchemaNode,
   OperationNode,
   OutputNode,
@@ -22,6 +28,7 @@ import type {
   ParamsTypeNode,
   PrimitiveSchemaType,
   PropertyNode,
+  RequestBodyNode,
   ResponseNode,
   SchemaNode,
   SourceNode,
@@ -31,10 +38,13 @@ import type {
 import { combineExports, combineImports, combineSources, extractStringsFromNodes } from './utils.ts'
 
 /**
- * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+ * Updates a schema's `optional` and `nullish` flags from a parent's `required`
+ * value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
+ * object properties combine "required" and "nullable" into a single AST.
  *
- * - `optional` is set for non-required, non-nullable schemas.
- * - `nullish` is set for non-required, nullable schemas.
+ * - Non-required + non-nullable → `optional: true`.
+ * - Non-required + nullable → `nullish: true`.
+ * - Required → both flags cleared.
  */
 export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
   const nullable = schema.nullable ?? false
@@ -59,6 +69,32 @@ export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNo
  */
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
 
+/**
+ * Identity-preserving node update: returns `node` unchanged when every field in
+ * `changes` already equals (by reference) the current value, otherwise a new node
+ * with the changes applied.
+ *
+ * Mirrors the TypeScript compiler's `factory.updateX` contract — pair it with the
+ * structural sharing in {@link transform} so a no-op rewrite doesn't allocate and
+ * downstream passes can detect "nothing changed" by identity. Comparison is
+ * shallow: a structurally-equal but newly-allocated array/object counts as a change.
+ *
+ * @example
+ * ```ts
+ * update(node, { name: node.name })        // -> same `node` reference
+ * update(node, { name: 'renamed' })        // -> new node, `name` replaced
+ * ```
+ */
+export function update<T extends Node>(node: T, changes: Partial<T>): T {
+  for (const key in changes) {
+    if (changes[key] !== node[key as keyof T]) {
+      return { ...node, ...changes }
+    }
+  }
+
+  return node
+}
+
 type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & { properties?: Array<PropertyNode>; primitive?: 'object' }
 type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>
 type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
@@ -84,11 +120,24 @@ export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): I
   return {
     schemas: [],
     operations: [],
+    meta: { circularNames: [], enumNames: [] },
     ...overrides,
     kind: 'Input',
   }
 }
 
+/**
+ * Creates an `InputStreamNode` from pre-built `AsyncIterable` sources.
+ *
+ * @example
+ * ```ts
+ * const node = createStreamInput(schemasIterable, operationsIterable, { title: 'My API' })
+ * ```
+ */
+export function createStreamInput(schemas: AsyncIterable<SchemaNode>, operations: AsyncIterable<OperationNode>, meta?: InputMeta): InputStreamNode {
+  return { kind: 'Input', schemas, operations, meta }
+}
+
 /**
  * Creates an `OutputNode` with a stable default for `files`.
  *
@@ -134,16 +183,70 @@ export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}):
  * })
  * ```
  */
+/**
+ * Loosely-typed content entry accepted by the builders, normalized into a {@link ContentNode}.
+ */
+type UserContent = Omit<ContentNode, 'kind'>
+
+/**
+ * Creates a `ContentNode` for a single request-body or response content type.
+ */
+export function createContent(props: UserContent): ContentNode {
+  return {
+    ...props,
+    kind: 'Content',
+  }
+}
+
+/**
+ * Loosely-typed request body accepted by `createOperation`, normalized into a {@link RequestBodyNode}.
+ */
+type UserRequestBody = Omit<RequestBodyNode, 'kind' | 'content'> & {
+  content?: Array<UserContent>
+}
+
+/**
+ * Creates a `RequestBodyNode`, normalizing each content entry into a `ContentNode`.
+ */
+export function createRequestBody(props: UserRequestBody): RequestBodyNode {
+  return {
+    ...props,
+    kind: 'RequestBody',
+    content: props.content?.map(createContent),
+  }
+}
+
+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<OperationNode, 'operationId' | 'method' | 'path'> & Partial<Omit<OperationNode, 'kind' | 'operationId' | 'method' | 'path'>>,
-): OperationNode {
+  props: Pick<GenericOperationNode, 'operationId'> &
+    Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): GenericOperationNode
+export function createOperation(props: {
+  operationId: string
+  method?: HttpOperationNode['method']
+  path?: HttpOperationNode['path']
+  requestBody?: UserRequestBody
+  [key: string]: unknown
+}): OperationNode {
+  const { requestBody, ...rest } = props
+  const isHttp = rest.method !== undefined && rest.path !== undefined
+
   return {
     tags: [],
     parameters: [],
     responses: [],
-    ...props,
+    ...rest,
+    ...(isHttp ? { protocol: 'http' } : {}),
     kind: 'Operation',
-  }
+    requestBody: requestBody ? createRequestBody(requestBody) : undefined,
+  } as OperationNode
 }
 
 /**
@@ -304,21 +407,34 @@ export function createParameter(
 /**
  * Creates a `ResponseNode`.
  *
+ * Response body schemas live inside `content`. For convenience a single legacy `schema`
+ * (with optional `mediaType`/`keysToOmit`) is normalized into one `content` entry, so the same
+ * schema is never stored both at the node root and inside `content`.
+ *
  * @example
  * ```ts
  * const response = createResponse({
  *   statusCode: '200',
- *   description: 'Success',
- *   schema: createSchema({ type: 'object', properties: [] }),
+ *   content: [{ contentType: 'application/json', schema: createSchema({ type: 'object', properties: [] }) }],
  * })
  * ```
  */
 export function createResponse(
-  props: Pick<ResponseNode, 'statusCode' | 'schema'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'schema'>>,
+  props: Pick<ResponseNode, 'statusCode'> &
+    Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
+      content?: Array<UserContent>
+      schema?: SchemaNode
+      mediaType?: string | null
+      keysToOmit?: Array<string> | null
+    },
 ): ResponseNode {
+  const { schema, mediaType, keysToOmit, content, ...rest } = props
+  const entries = content ?? (schema ? [{ contentType: mediaType ?? 'application/json', schema, keysToOmit: keysToOmit ?? null }] : undefined)
+
   return {
-    ...props,
+    ...rest,
     kind: 'Response',
+    content: entries?.map(createContent),
   }
 }
 

package/src/guards.ts

@@ -1,6 +1,7 @@
 import type {
   FunctionParameterNode,
   FunctionParametersNode,
+  HttpOperationNode,
   InputNode,
   Node,
   NodeKind,
@@ -20,11 +21,11 @@ import type {
  * @example
  * ```ts
  * const schema = createSchema({ type: 'string' })
- * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
  * ```
  */
-export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined {
-  return node?.type === type ? (node as SchemaNodeByType[T]) : undefined
+export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null {
+  return node?.type === type ? (node as SchemaNodeByType[T]) : null
 }
 
 function isKind<T extends Node>(kind: NodeKind) {
@@ -67,6 +68,20 @@ export const isOutputNode = isKind<OutputNode>('Output')
  */
 export const isOperationNode = isKind<OperationNode>('Operation')
 
+/**
+ * Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
+ *
+ * @example
+ * ```ts
+ * if (isHttpOperationNode(node)) {
+ *   console.log(node.method, node.path)
+ * }
+ * ```
+ */
+export function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {
+  return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)
+}
+
 /**
  * Returns `true` when the input is a `SchemaNode`.
  *

package/src/index.ts

@@ -1,8 +1,11 @@
 export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
+export { defineSchemaDialect } from './dialect.ts'
+export { dispatch } from './dispatch.ts'
 export {
   createArrowFunction,
   createBreak,
   createConst,
+  createContent,
   createExport,
   createFile,
   createFunction,
@@ -10,6 +13,7 @@ export {
   createFunctionParameters,
   createImport,
   createInput,
+  createStreamInput,
   createJsx,
   createOperation,
   createOutput,
@@ -17,18 +21,20 @@ export {
   createParameterGroup,
   createParamsType,
   createProperty,
+  createRequestBody,
   createResponse,
   createSchema,
   createSource,
   createText,
   createType,
   syncOptionality,
+  update,
 } from './factory.ts'
-export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
+export { isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { extractRefName } from './refs.ts'
 export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
-export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
+export { mergeAdjacentObjects, mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type * from './types.ts'
 export {
   caseParams,
@@ -43,4 +49,4 @@ export {
   resolveRefName,
   syncSchemaRef,
 } from './utils.ts'
-export { collect, transform, walk } from './visitor.ts'
+export { collect, collectLazy, transform, walk } from './visitor.ts'

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
+}