@kubb/ast 5.0.0-beta.2 → 5.0.0-beta.21

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.2",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.21",
+  "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/factory.ts

@@ -12,7 +12,9 @@ import type {
   FunctionParameterNode,
   FunctionParametersNode,
   ImportNode,
+  InputMeta,
   InputNode,
+  InputStreamNode,
   JsxNode,
   ObjectSchemaNode,
   OperationNode,
@@ -84,11 +86,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`.
  *

package/src/guards.ts

@@ -20,11 +20,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) {

package/src/index.ts

@@ -10,6 +10,7 @@ export {
   createFunctionParameters,
   createImport,
   createInput,
+  createStreamInput,
   createJsx,
   createOperation,
   createOutput,
@@ -28,7 +29,7 @@ export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema
 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 +44,4 @@ export {
   resolveRefName,
   syncSchemaRef,
 } from './utils.ts'
-export { collect, transform, walk } from './visitor.ts'
+export { collect, collectLazy, transform, walk } from './visitor.ts'

package/src/nodes/index.ts

@@ -19,7 +19,7 @@ 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,

package/src/nodes/operation.ts

@@ -101,7 +101,7 @@ export type OperationNode = BaseNode & {
        * 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>
+      keysToOmit?: Array<string> | null
     }>
   }
   /**

package/src/nodes/response.ts

@@ -39,5 +39,5 @@ export type ResponseNode = BaseNode & {
    * 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.
    */
-  keysToOmit?: Array<string>
+  keysToOmit?: Array<string> | null
 }

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: readonly 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: readonly 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
 }
 
 /**

package/src/printer.ts

@@ -18,7 +18,7 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
    * Recursively transform a nested `SchemaNode` to `TOutput` using the node-level handlers.
    * Use `this.transform` inside `nodes` handlers and inside the `print` override.
    */
-  transform: (node: SchemaNode) => TOutput | null | undefined
+  transform: (node: SchemaNode) => TOutput | null
   /**
    * Options for this printer instance.
    */
@@ -40,7 +40,7 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
 export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (
   this: PrinterHandlerContext<TOutput, TOptions>,
   node: SchemaNodeByType[T],
-) => TOutput | null | undefined
+) => TOutput | null
 
 /**
  * Partial map of per-node-type handler overrides for a printer.
@@ -108,13 +108,13 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    * Always dispatches through the `nodes` map; never calls the `print` override.
    * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
-  transform: (node: SchemaNode) => T['output'] | null | undefined
+  transform: (node: SchemaNode) => T['output'] | null
   /**
    * Public printer. If the builder provides a root-level `print`, this calls that
    * higher-level function (which may produce full declarations).
    * Otherwise, falls back to the node-level dispatcher.
    */
-  print: (node: SchemaNode) => T['printOutput'] | null | undefined
+  print: (node: SchemaNode) => T['printOutput'] | null
 }
 
 /**
@@ -147,7 +147,6 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
    */
   print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null
 }
-
 /**
  * Creates a schema printer factory.
  *
@@ -194,7 +193,7 @@ export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOp
  * )
  * ```
  */
-export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined) {
+export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | null) {
   return function <T extends PrinterFactoryOptions>(
     build: (options: T['options']) => {
       name: T['name']
@@ -202,40 +201,40 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
       nodes: Partial<{
         [K in TKey]: (
           this: {
-            transform: (node: TNode) => T['output'] | null | undefined
+            transform: (node: TNode) => T['output'] | null
             options: T['options']
           },
           node: TNodeByKey[K],
-        ) => T['output'] | null | undefined
+        ) => T['output'] | null
       }>
       print?: (
         this: {
-          transform: (node: TNode) => T['output'] | null | undefined
+          transform: (node: TNode) => T['output'] | null
           options: T['options']
         },
         node: TNode,
-      ) => T['printOutput'] | null | undefined
+      ) => T['printOutput'] | null
     },
   ): (options?: T['options']) => {
     name: T['name']
     options: T['options']
-    transform: (node: TNode) => T['output'] | null | undefined
-    print: (node: TNode) => T['printOutput'] | null | undefined
+    transform: (node: TNode) => T['output'] | null
+    print: (node: TNode) => T['printOutput'] | null
   } {
     return (options) => {
       const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? ({} as T['options']))
 
       const context = {
         options: resolvedOptions,
-        transform: (node: TNode): T['output'] | null | undefined => {
+        transform: (node: TNode): T['output'] | null => {
           const key = getKey(node)
-          if (key === undefined) return null
+          if (key === null) return null
 
           const handler = nodes[key]
 
           if (!handler) return null
 
-          return (handler as (this: typeof context, node: TNode) => T['output'] | null | undefined).call(context, node)
+          return (handler as (this: typeof context, node: TNode) => T['output'] | null).call(context, node)
         },
       }
 
@@ -243,7 +242,7 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
         name,
         options: resolvedOptions,
         transform: context.transform,
-        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null | undefined,
+        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null,
       }
     }
   }

package/src/refs.ts

@@ -45,13 +45,15 @@ export function buildRefMap(input: InputNode): RefMap {
 /**
  * Resolves a schema by name from a `RefMap`.
  *
+ * Returns `null` when the ref is not found.
+ *
  * @example
  * ```ts
  * const petSchema = resolveRef(refMap, 'Pet')
  * ```
  */
-export function resolveRef(refMap: RefMap, ref: string): SchemaNode | undefined {
-  return refMap.get(ref)
+export function resolveRef(refMap: RefMap, ref: string): SchemaNode | null {
+  return refMap.get(ref) ?? null
 }
 
 /**

package/src/resolvers.ts

@@ -27,17 +27,17 @@ export function collectImports<TImport>({
 }: {
   node: SchemaNode
   nameMapping: Map<string, string>
-  resolve: (schemaName: string) => TImport | undefined
+  resolve: (schemaName: string) => TImport | null
 }): Array<TImport> {
   return collect<TImport>(node, {
-    schema(schemaNode): TImport | undefined {
+    schema(schemaNode): TImport | null {
       const schemaRef = narrowSchema(schemaNode, 'ref')
-      if (!schemaRef?.ref) return
+      if (!schemaRef?.ref) return null
 
       const rawName = extractRefName(schemaRef.ref)
       const schemaName = nameMapping.get(rawName) ?? rawName
       const result = resolve(schemaName)
-      if (!result) return
+      if (!result) return null
 
       return result
     },

package/src/transformers.ts

@@ -73,25 +73,30 @@ export function setDiscriminatorEnum({
  * ])
  * ```
  */
-export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
-  return members.reduce<Array<SchemaNode>>((acc, member) => {
+export function* mergeAdjacentObjectsLazy(members: Iterable<SchemaNode>): Generator<SchemaNode, void, undefined> {
+  let acc: SchemaNode | undefined
+
+  for (const member of members) {
     const objectMember = narrowSchema(member, 'object')
-    if (objectMember && !objectMember.name) {
-      const previous = acc.at(-1)
-      const previousObject = previous ? narrowSchema(previous, 'object') : undefined
-
-      if (previousObject && !previousObject.name) {
-        acc[acc.length - 1] = createSchema({
-          ...previousObject,
-          properties: [...(previousObject.properties ?? []), ...(objectMember.properties ?? [])],
+    if (objectMember && !objectMember.name && acc !== undefined) {
+      const accObject = narrowSchema(acc, 'object')
+      if (accObject && !accObject.name) {
+        acc = createSchema({
+          ...accObject,
+          properties: [...(accObject.properties ?? []), ...(objectMember.properties ?? [])],
         })
-        return acc
+        continue
       }
     }
+    if (acc !== undefined) yield acc
+    acc = member
+  }
 
-    acc.push(member)
-    return acc
-  }, [])
+  if (acc !== undefined) yield acc
+}
+
+export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
+  return [...mergeAdjacentObjectsLazy(members)]
 }
 
 /**
@@ -145,7 +150,7 @@ export function setEnumName(propNode: SchemaNode, parentName: string | null | un
   const enumNode = narrowSchema(propNode, 'enum')
 
   if (enumNode?.primitive === 'boolean') {
-    return { ...propNode, name: undefined }
+    return { ...propNode, name: null }
   }
 
   if (enumNode) {

package/src/types.ts

@@ -26,6 +26,7 @@ export type {
   ImportNode,
   InputMeta,
   InputNode,
+  InputStreamNode,
   IntersectionSchemaNode,
   Ipv4SchemaNode,
   Ipv6SchemaNode,