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

package/src/nodes/input.ts

@@ -0,0 +1,140 @@
+import type { Streamable } from '@internals/utils'
+import { defineNode } from '../node.ts'
+import type { BaseNode } from './base.ts'
+import type { OperationNode } from './operation.ts'
+import type { SchemaNode } from './schema.ts'
+
+/**
+ * Metadata for an API document, populated by the adapter and available to every generator.
+ *
+ * All fields are plain JSON-serializable values, no `Set`, no `Map`, no class instances.
+ * Computed fields (`circularNames`, `enumNames`) are pre-calculated once during the adapter
+ * pre-scan so generators never need to iterate the full schema list themselves.
+ *
+ * @example
+ * ```ts
+ * const meta: InputMeta = { title: 'Pet Store', version: '1.0.0', baseURL: 'https://petstore.swagger.io/v2', circularNames: [], enumNames: [] }
+ * ```
+ */
+export type InputMeta = {
+  /**
+   * API title from `info.title` in the source document.
+   */
+  title?: string
+  /**
+   * API description from `info.description` in the source document.
+   */
+  description?: string
+  /**
+   * API version string from `info.version` in the source document.
+   */
+  version?: string
+  /**
+   * Resolved base URL from the first matching server entry in the source document.
+   */
+  baseURL?: string | null
+  /**
+   * Names of schemas that participate in a circular reference chain.
+   * Computed once during the adapter pre-scan, so a generator never has to
+   * call `findCircularSchemas` itself.
+   *
+   * Convert to a `Set` once at the start of a generator, not per-schema,
+   * so lookups stay O(1) without repeated allocations.
+   *
+   * @example Wrap a circular schema in z.lazy()
+   * ```ts
+   * const circular = new Set(meta.circularNames)
+   * if (circular.has(schema.name)) { ... }
+   * ```
+   */
+  circularNames: ReadonlyArray<string>
+  /**
+   * Names of schemas whose type is `enum`.
+   * Computed once during the adapter pre-scan, so a generator never has to
+   * filter the schema list itself.
+   *
+   * Convert to a `Set` once at the start of a generator when you need repeated
+   * membership checks, so each check stays O(1) instead of an array scan.
+   *
+   * @example Check if a referenced schema is an enum
+   * `const enums = new Set(meta.enumNames)`
+   * `const isEnum = enums.has(schemaName)`
+   */
+  enumNames: ReadonlyArray<string>
+}
+
+/**
+ * Input AST node that contains all schemas and operations for one API document.
+ * Produced by the adapter and consumed by all Kubb plugins.
+ *
+ * `Stream` switches `schemas` and `operations` between eager `Array`s (the default) and lazy
+ * `AsyncIterable`s. The streaming variant `InputNode<true>` yields nodes one at a time and makes
+ * `meta` optional, since the adapter can emit metadata before the first node is parsed.
+ *
+ * @example
+ * ```ts
+ * const input: InputNode = {
+ *   kind: 'Input',
+ *   schemas: [],
+ *   operations: [],
+ *   meta: { circularNames: [], enumNames: [] },
+ * }
+ * ```
+ *
+ * @example Streaming variant for large specs
+ * ```ts
+ * for await (const schema of inputNode.schemas) {
+ *   // only this one SchemaNode is live here. Previous ones are GC-eligible
+ * }
+ * ```
+ */
+export type InputNode<Stream extends boolean = false> = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Input'
+  /**
+   * All schema nodes in the document.
+   */
+  schemas: Streamable<SchemaNode, Stream>
+  /**
+   * All operation nodes in the document.
+   */
+  operations: Streamable<OperationNode, Stream>
+} & (Stream extends true ? { meta?: InputMeta } : { meta: InputMeta })
+
+/**
+ * Definition for the {@link InputNode}.
+ */
+export const inputDef = defineNode<InputNode, Partial<Omit<InputNode, 'kind'>>>({
+  kind: 'Input',
+  defaults: { schemas: [], operations: [], meta: { circularNames: [], enumNames: [] } },
+  children: ['schemas', 'operations'],
+  visitorKey: 'input',
+})
+
+/**
+ * Creates an `InputNode`. Pass `stream: true` for the streaming variant whose `schemas` and
+ * `operations` are `AsyncIterable` sources and whose `meta` is optional. Otherwise it builds the
+ * eager variant with array `schemas`/`operations` and the defaulted `meta`.
+ *
+ * @example Eager
+ * ```ts
+ * const input = createInput()
+ * // { kind: 'Input', schemas: [], operations: [] }
+ * ```
+ *
+ * @example Streaming
+ * ```ts
+ * const node = createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta: { title: 'My API' } })
+ * ```
+ */
+export function createInput<Stream extends boolean = false>(options: Partial<Omit<InputNode<Stream>, 'kind'>> & { stream?: Stream } = {}): InputNode<Stream> {
+  const { stream, ...overrides } = options
+  // Streaming inputs carry AsyncIterable sources, so skip the array/meta defaults that
+  // inputDef.create applies for the eager variant.
+  if (stream) {
+    return { kind: 'Input', ...overrides } as InputNode<Stream>
+  }
+  return inputDef.create(overrides as Partial<Omit<InputNode, 'kind'>>) as InputNode<Stream>
+}

package/src/nodes/operation.ts

@@ -1,27 +1,20 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { ParameterNode } from './parameter.ts'
+import { createRequestBody, type RequestBodyNode, type UserRequestBody } from './requestBody.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.
- *
- * @example
- * ```ts
- * const operation: OperationNode = {
- *   kind: 'Operation',
- *   operationId: 'listPets',
- *   method: 'GET',
- *   path: '/pets',
- *   tags: [],
- *   parameters: [],
- *   responses: [],
- * }
- * ```
+ * Transport an operation belongs to.
  */
-export type OperationNode = BaseNode & {
+type OperationProtocol = 'http'
+
+/**
+ * Fields shared by every operation, regardless of transport.
+ */
+type OperationNodeBase = BaseNode & {
   /**
    * Node kind.
    */
@@ -30,15 +23,6 @@ export type OperationNode = BaseNode & {
    * Operation identifier, usually from OpenAPI `operationId`.
    */
   operationId: string
-  /**
-   * HTTP Method like 'GET'
-   */
-  method: HttpMethod
-  /**
-   * 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`.
@@ -57,55 +41,125 @@ export type OperationNode = BaseNode & {
    */
   deprecated?: boolean
   /**
-   * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
+   * Query, path, header, and cookie parameters for the operation.
    */
   parameters: Array<ParameterNode>
   /**
-   * Request body metadata for the operation.
+   * Request body 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>
-    }>
-  }
+  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
+
+type OperationInput = {
+  operationId: string
+  method?: HttpOperationNode['method']
+  path?: HttpOperationNode['path']
+  requestBody?: UserRequestBody
+  [key: string]: unknown
+}
+
+/**
+ * Definition for the {@link OperationNode}. HTTP operations (those carrying both
+ * `method` and `path`) are tagged with `protocol: 'http'`, and the request body is
+ * normalized into a `RequestBodyNode`.
+ */
+export const operationDef = defineNode<OperationNode, OperationInput>({
+  kind: 'Operation',
+  build: (props) => {
+    const { requestBody, ...rest } = props
+    const isHttp = rest.method !== undefined && rest.path !== undefined
+
+    return {
+      tags: [],
+      parameters: [],
+      responses: [],
+      ...rest,
+      ...(isHttp ? { protocol: 'http' as const } : {}),
+      requestBody: requestBody ? createRequestBody(requestBody) : undefined,
+    }
+  },
+  children: ['parameters', 'requestBody', 'responses'],
+  visitorKey: 'operation',
+})
+
+/**
+ * Creates an `OperationNode` with default empty arrays for `tags`, `parameters`, and `responses`.
+ *
+ * @example
+ * ```ts
+ * const operation = createOperation({ operationId: 'getPetById', method: 'GET', path: '/pet/{petId}' })
+ * // tags, parameters, and responses are []
+ * ```
+ */
+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<GenericOperationNode, 'operationId'> &
+    Partial<Omit<GenericOperationNode, 'kind' | 'operationId' | 'requestBody'>> & {
+      requestBody?: UserRequestBody
+    },
+): GenericOperationNode
+export function createOperation(props: OperationInput): OperationNode {
+  return operationDef.create(props)
+}

package/src/nodes/output.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { FileNode } from './file.ts'
 
@@ -24,3 +25,25 @@ export type OutputNode = BaseNode & {
    */
   files: Array<FileNode>
 }
+
+/**
+ * Definition for the {@link OutputNode}.
+ */
+export const outputDef = defineNode<OutputNode, Partial<Omit<OutputNode, 'kind'>>>({
+  kind: 'Output',
+  defaults: { files: [] },
+  visitorKey: 'output',
+})
+
+/**
+ * Creates an `OutputNode` with a stable default for `files`.
+ *
+ * @example
+ * ```ts
+ * const output = createOutput()
+ * // { kind: 'Output', files: [] }
+ * ```
+ */
+export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}): OutputNode {
+  return outputDef.create(overrides)
+}

package/src/nodes/parameter.ts

@@ -1,3 +1,4 @@
+import { defineNode, syncOptionality } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -18,9 +19,6 @@ export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
  * ```
  */
 export type ParameterNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Parameter'
   /**
    * Parameter name.
@@ -39,3 +37,35 @@ export type ParameterNode = BaseNode & {
    */
   required: boolean
 }
+
+type UserParameterNode = Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>
+
+/**
+ * Definition for the {@link ParameterNode}. `required` defaults to `false` and the
+ * schema's `optional`/`nullish` flags are kept in sync with it.
+ */
+export const parameterDef = defineNode<ParameterNode, UserParameterNode>({
+  kind: 'Parameter',
+  build: (props) => {
+    const required = props.required ?? false
+    return { ...props, required, schema: syncOptionality(props.schema, required) }
+  },
+  children: ['schema'],
+  visitorKey: 'parameter',
+  rebuild: true,
+})
+
+/**
+ * Creates a `ParameterNode`.
+ *
+ * @example
+ * ```ts
+ * const param = createParameter({
+ *   name: 'petId',
+ *   in: 'path',
+ *   required: true,
+ *   schema: createSchema({ type: 'string' }),
+ * })
+ * ```
+ */
+export const createParameter = parameterDef.create

package/src/nodes/property.ts

@@ -1,3 +1,4 @@
+import { defineNode, syncOptionality } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { SchemaNode } from './schema.ts'
 
@@ -15,9 +16,6 @@ import type { SchemaNode } from './schema.ts'
  * ```
  */
 export type PropertyNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Property'
   /**
    * Property key.
@@ -32,3 +30,38 @@ export type PropertyNode = BaseNode & {
    */
   required: boolean
 }
+
+/**
+ * Loosely-typed property accepted by `createProperty`, with `required` optional.
+ */
+export type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>
+
+/**
+ * Definition for the {@link PropertyNode}. `required` defaults to `false` and the
+ * schema's `optional`/`nullish` flags are kept in sync with it.
+ */
+export const propertyDef = defineNode<PropertyNode, UserPropertyNode>({
+  kind: 'Property',
+  build: (props) => {
+    const required = props.required ?? false
+    return { ...props, required, schema: syncOptionality(props.schema, required) }
+  },
+  children: ['schema'],
+  visitorKey: 'property',
+  rebuild: true,
+})
+
+/**
+ * Creates a `PropertyNode`.
+ *
+ * @example
+ * ```ts
+ * const property = createProperty({
+ *   name: 'status',
+ *   required: true,
+ *   schema: createSchema({ type: 'string', nullable: true }),
+ * })
+ * // required=true, no optional/nullish
+ * ```
+ */
+export const createProperty = propertyDef.create

package/src/nodes/requestBody.ts

@@ -0,0 +1,61 @@
+import { defineNode } from '../node.ts'
+import type { BaseNode } from './base.ts'
+import { type ContentNode, createContent, type UserContent } from './content.ts'
+
+/**
+ * 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 requestBody: RequestBodyNode = {
+ *   kind: 'RequestBody',
+ *   required: true,
+ *   content: [{ kind: 'Content', contentType: 'application/json', schema: createSchema({ type: 'string' }) }],
+ * }
+ * ```
+ */
+export type RequestBodyNode = BaseNode & {
+  kind: 'RequestBody'
+  /**
+   * Request body description carried over from the spec.
+   */
+  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
+  /**
+   * 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 plugins can generate code for every variant (for example, separate hooks for
+   * `application/json` and `multipart/form-data`).
+   */
+  content?: Array<ContentNode>
+}
+
+/**
+ * Loosely-typed request body accepted by `createOperation`, normalized into a {@link RequestBodyNode}.
+ */
+export type UserRequestBody = Omit<RequestBodyNode, 'kind' | 'content'> & {
+  content?: Array<UserContent>
+}
+
+/**
+ * Definition for the {@link RequestBodyNode}, normalizing each content entry into a `ContentNode`.
+ */
+export const requestBodyDef = defineNode<RequestBodyNode, UserRequestBody>({
+  kind: 'RequestBody',
+  build: (props) => ({ ...props, content: props.content?.map(createContent) }),
+  children: ['content'],
+})
+
+/**
+ * Creates a `RequestBodyNode`, normalizing each content entry into a `ContentNode`.
+ */
+export const createRequestBody = requestBodyDef.create

package/src/nodes/response.ts

@@ -1,16 +1,22 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
-import type { MediaType, StatusCode } from './http.ts'
+import { type ContentNode, createContent, type UserContent } from './content.ts'
+import type { StatusCode } from './http.ts'
 import type { SchemaNode } from './schema.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 +34,55 @@ 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>
 }
+
+type ResponseInput = Pick<ResponseNode, 'statusCode'> &
+  Partial<Omit<ResponseNode, 'kind' | 'statusCode' | 'content'>> & {
+    content?: Array<UserContent>
+    schema?: SchemaNode
+    mediaType?: string | null
+    keysToOmit?: Array<string> | null
+  }
+
+/**
+ * Definition for the {@link ResponseNode}. A single legacy `schema` (with optional
+ * `mediaType`/`keysToOmit`) is normalized into one `content` entry.
+ */
+export const responseDef = defineNode<ResponseNode, ResponseInput>({
+  kind: 'Response',
+  build: (props) => {
+    const { schema, mediaType, keysToOmit, content, ...rest } = props
+    const entries = content ?? (schema ? [{ contentType: mediaType ?? 'application/json', schema, keysToOmit: keysToOmit ?? null }] : undefined)
+    return { ...rest, content: entries?.map(createContent) }
+  },
+  children: ['content'],
+  visitorKey: 'response',
+})
+
+/**
+ * Creates a `ResponseNode`.
+ *
+ * @example
+ * ```ts
+ * const response = createResponse({
+ *   statusCode: '200',
+ *   content: [{ contentType: 'application/json', schema: createSchema({ type: 'object', properties: [] }) }],
+ * })
+ * ```
+ */
+export const createResponse = responseDef.create