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

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.20",
+  "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/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/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
+  /**
+   * 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)) { ... }
+   * ```
+   */
+  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
 }
 
 /**

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)]
 }
 
 /**

package/src/types.ts

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

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { camelCase, isValidVarName } from '@internals/utils'
+import { camelCase, isValidVarName, memoize } from '@internals/utils'
 
 import { createFunctionParameter, createFunctionParameters, createParameterGroup, createParamsType, createProperty, createSchema } from './factory.ts'
 import { narrowSchema } from './guards.ts'
@@ -17,7 +17,7 @@ import type {
 } from './nodes/index.ts'
 import type { SchemaType } from './nodes/schema.ts'
 import { extractRefName } from './refs.ts'
-import { collect } from './visitor.ts'
+import { collect, collectLazy } from './visitor.ts'
 
 const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
 
@@ -74,16 +74,18 @@ export function isStringType(node: SchemaNode): boolean {
  * the desired casing while preserving `OperationNode.parameters` for other consumers.
  * The input array is not mutated. When `casing` is not set, the original array is returned unchanged.
  */
-export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
-  if (!casing) {
-    return params
-  }
+const caseParamsMemo = memoize(new WeakMap<Array<ParameterNode>, (casing: string) => Array<ParameterNode>>(), (params) =>
+  memoize(new Map<string, Array<ParameterNode>>(), (casing: string) =>
+    params.map((param) => {
+      const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
+      return { ...param, name: transformed }
+    }),
+  ),
+)
 
-  return params.map((param) => {
-    const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
-
-    return { ...param, name: transformed }
-  })
+export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
+  if (!casing) return params
+  return caseParamsMemo(params)(casing)
 }
 
 /**
@@ -652,6 +654,16 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   const exportedNames = new Set(exports.flatMap((e) => (Array.isArray(e.name) ? e.name : e.name ? [e.name] : [])))
   const isUsed = (importName: string): boolean => !source || source.includes(importName) || exportedNames.has(importName)
 
+  // Memoize object import names so the same logical (propertyName, name) pair always
+  // reuses the same object reference — Set-based deduplication then works correctly.
+  const importNameMemo = new Map<string, { propertyName: string; name?: string }>()
+  const canonicalizeName = (n: string | { propertyName: string; name?: string }): string | { propertyName: string; name?: string } => {
+    if (typeof n === 'string') return n
+    const key = `${n.propertyName}:${n.name ?? ''}`
+    if (!importNameMemo.has(key)) importNameMemo.set(key, n)
+    return importNameMemo.get(key)!
+  }
+
   const result: Array<ImportNode> = []
   // Accumulates array-named imports keyed by `path:isTypeOnly` for name-merging
   const namedByPath = new Map<string, ImportNode>()
@@ -669,7 +681,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
     let { name } = curr
 
     if (Array.isArray(name)) {
-      name = [...new Set(name)].filter((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))
+      name = [...new Set(name.map(canonicalizeName))].filter((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))
       if (!name.length) continue
 
       const key = pathTypeKey(path, isTypeOnly)
@@ -713,13 +725,18 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
       if (node.kind === 'Text') return node.value
       if (node.kind === 'Break') return ''
       if (node.kind === 'Jsx') return node.value
+
       const parts: string[] = []
+
       if ('params' in node && node.params) parts.push(node.params)
       if ('generics' in node && node.generics) parts.push(Array.isArray(node.generics) ? node.generics.join(', ') : node.generics)
       if ('returnType' in node && node.returnType) parts.push(node.returnType)
       if ('type' in node && typeof node.type === 'string') parts.push(node.type)
+
       const nested = extractStringsFromNodes(node.nodes)
+
       if (nested) parts.push(nested)
+
       return parts.join('\n')
     })
     .filter(Boolean)
@@ -765,18 +782,22 @@ export function resolveRefName(node: SchemaNode | undefined): string | undefined
  * }
  * ```
  */
-export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
-  if (!node) return out
+const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
+  const refs = new Set<string>()
   collect<void>(node, {
     schema(child) {
       if (child.type === 'ref') {
         const name = resolveRefName(child)
-
-        if (name) out.add(name)
+        if (name) refs.add(name)
       }
-      return undefined
     },
   })
+  return refs
+})
+
+export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
+  if (!node) return out
+  for (const name of collectSchemaRefs(node)) out.add(name)
   return out
 }
 
@@ -793,10 +814,10 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
  *
  * @example Only generate schemas referenced by included operations
  * ```ts
- * const includedOps = inputNode.operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
- * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ * const includedOps = operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
  *
- * for (const schema of inputNode.schemas) {
+ * for (const schema of schemas) {
  *   if (schema.name && !allowed.has(schema.name)) continue
  *   // … generate schema
  * }
@@ -804,16 +825,18 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
  *
  * @example Check whether a specific schema is needed
  * ```ts
- * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
  * allowed.has('OrderStatus') // false when no included operation references OrderStatus
  * ```
  */
-export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+const collectUsedSchemaNamesMemo = memoize(new WeakMap<ReadonlyArray<OperationNode>, (schemas: ReadonlyArray<SchemaNode>) => Set<string>>(), (ops) =>
+  memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas) => computeUsedSchemaNames(ops, schemas)),
+)
+
+function computeUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
   const schemaMap = new Map<string, SchemaNode>()
   for (const schema of schemas) {
-    if (schema.name) {
-      schemaMap.set(schema.name, schema)
-    }
+    if (schema.name) schemaMap.set(schema.name, schema)
   }
 
   const result = new Set<string>()
@@ -824,15 +847,13 @@ export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>,
       if (!result.has(name)) {
         result.add(name)
         const namedSchema = schemaMap.get(name)
-        if (namedSchema) {
-          visitSchema(namedSchema)
-        }
+        if (namedSchema) visitSchema(namedSchema)
       }
     }
   }
 
   for (const op of operations) {
-    for (const schema of collect<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
+    for (const schema of collectLazy<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
       visitSchema(schema)
     }
   }
@@ -840,16 +861,13 @@ export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>,
   return result
 }
 
-/**
- * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
- *
- * Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
- * in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
- * Refs are followed by name only, keeping the algorithm linear in the schema graph size.
- *
- * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
- */
-export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  return collectUsedSchemaNamesMemo(operations)(schemas)
+}
+
+const EMPTY_CIRCULAR_SET = new Set<string>()
+
+const findCircularSchemasMemo = memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas: ReadonlyArray<SchemaNode>): Set<string> => {
   const graph = new Map<string, Set<string>>()
 
   for (const schema of schemas) {
@@ -876,6 +894,20 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
   }
 
   return circular
+})
+
+/**
+ * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
+ *
+ * Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
+ * in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
+ * Refs are followed by name only, keeping the algorithm linear in the schema graph size.
+ *
+ * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
+ */
+export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  if (schemas.length === 0) return EMPTY_CIRCULAR_SET
+  return findCircularSchemasMemo(schemas)
 }
 
 /**
@@ -892,14 +924,15 @@ export function containsCircularRef(
 ): boolean {
   if (!node || circularSchemas.size === 0) return false
 
-  const matches = collect<true>(node, {
+  for (const _ of collectLazy<true>(node, {
     schema(child) {
       if (child.type !== 'ref') return undefined
       const name = resolveRefName(child)
-
       return name && name !== excludeName && circularSchemas.has(name) ? true : undefined
     },
-  })
+  })) {
+    return true
+  }
 
-  return matches.length > 0
+  return false
 }