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

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

package/src/nodes/root.ts

@@ -3,32 +3,62 @@ import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
 
 /**
- * Basic metadata for an API document.
- * Adapters fill fields that exist in their source format.
+ * 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 API', version: '1.0.0' }
+ * 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 OAS/AsyncAPI).
+   * API title from `info.title` in the source document.
    */
   title?: string
   /**
-   * API description (from `info.description` in OAS/AsyncAPI).
+   * API description from `info.description` in the source document.
    */
   description?: string
   /**
-   * API version string (from `info.version` in OAS/AsyncAPI).
+   * API version string from `info.version` in the source document.
    */
   version?: string
   /**
-   * Resolved API base URL.
-   * For OpenAPI and AsyncAPI, this comes from the selected server URL.
+   * 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 — use this instead of calling
+   * `findCircularSchemas` per generator call.
+   *
+   * Convert to a `Set` once at the start of a generator, not per-schema,
+   * to keep lookup 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)) { ... }
+   * ```
    */
-  baseURL?: string
+  circularNames: ReadonlyArray<string>
+  /**
+   * Names of schemas whose type is `enum`.
+   * Computed once during the adapter pre-scan — use this instead of filtering
+   * schemas per generator call.
+   *
+   * Convert to a `Set` once at the start of a generator when you need repeated
+   * membership checks, rather than calling `.includes()` per schema.
+   *
+   * @example Check if a referenced schema is an enum
+   * `const enums = new Set(meta.enumNames)`
+   * `const isEnum = enums.has(schemaName)`
+   */
+  enumNames: ReadonlyArray<string>
 }
 
 /**
@@ -58,7 +88,39 @@ export type InputNode = BaseNode & {
    */
   operations: Array<OperationNode>
   /**
-   * Optional document metadata populated by the adapter.
+   * Document metadata populated by the adapter.
+   */
+  meta: InputMeta
+}
+
+/**
+ * Streaming variant of `InputNode` for memory-efficient processing of large API specs.
+ *
+ * `schemas` and `operations` are `AsyncIterable` rather than arrays — each `for await`
+ * loop creates a fresh parse pass from the cached in-memory document, so multiple
+ * consumers (plugins) can iterate independently without keeping all nodes in memory.
+ *
+ * @example
+ * ```ts
+ * for await (const schema of inputStreamNode.schemas) {
+ *   // only this one SchemaNode is live here; previous ones are GC-eligible
+ * }
+ * ```
+ */
+export type InputStreamNode = {
+  kind: 'Input'
+  /**
+   * Lazily parsed schema nodes. Each `for await` creates a fresh parse pass, so
+   * multiple plugins can iterate independently without sharing state.
+   */
+  schemas: AsyncIterable<SchemaNode>
+  /**
+   * Lazily parsed operation nodes. Each `for await` creates a fresh parse pass, so
+   * multiple plugins can iterate independently without sharing state.
+   */
+  operations: AsyncIterable<OperationNode>
+  /**
+   * Document metadata available immediately, before the first yielded node.
    */
   meta?: InputMeta
 }

package/src/nodes/schema.ts

@@ -154,6 +154,10 @@ type SchemaNodeBase = BaseNode & {
    * For example, this is `'string'` for a `uuid` schema.
    */
   primitive?: PrimitiveSchemaType
+  /**
+   * Schema `format` value.
+   */
+  format?: string
 }
 
 /**
@@ -364,8 +368,9 @@ export type RefSchemaNode = SchemaNodeBase & {
   type: 'ref'
   /**
    * Referenced schema name.
+   * `null` means Kubb has processed this and determined there is no applicable name.
    */
-  name?: string
+  name?: string | null
   /**
    * Original `$ref` path, for example, `#/components/schemas/Order`.
    * Used to resolve names later.
@@ -378,12 +383,13 @@ export type RefSchemaNode = SchemaNodeBase & {
   /**
    * The fully-parsed schema that this ref resolves to.
    * Populated during OAS parsing when the referenced definition can be resolved.
-   * `undefined` when the ref cannot be resolved or is part of a circular chain.
+   * `null` when the ref cannot be resolved or is part of a circular chain.
+   * `undefined` when resolution has not been attempted.
    *
    * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
    * without following the reference manually.
    */
-  schema?: SchemaNode
+  schema?: SchemaNode | null
 }
 
 /**