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

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,24 +147,28 @@ 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.
- *
- * This function wraps a builder and makes options optional at call sites.
+ * Defines a schema printer: a function that takes a `SchemaNode` and emits
+ * code in your target language. Each plugin that produces code from schemas
+ * (TypeScript types, Zod schemas, Faker factories) ships a printer built
+ * with this helper.
  *
  * The builder receives resolved options and returns:
- * - `name` — a unique identifier for the printer
- * - `options` — options stored on the returned printer instance
- * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
- * - `print` _(optional)_ — top-level override exposed as `printer.print`
- *   - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
- *   - This keeps recursion safe and avoids self-calls
  *
- * When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
+ * - `name` — unique identifier for the printer.
+ * - `options` — stored on the returned printer instance.
+ * - `nodes` — map of `SchemaType` → handler. Handlers return the rendered
+ *   output (a string, a TypeScript AST node, ...) for that schema type.
+ * - `print` (optional) — top-level override exposed as `printer.print`.
+ *   Use `this.transform(node)` inside it to dispatch to `nodes` recursively.
  *
- * @example Basic usage — Zod schema printer
+ * Without a `print` override, `printer.print` falls back to `printer.transform`
+ * (the node-level dispatcher).
+ *
+ * @example Tiny Zod printer
  * ```ts
+ * import { definePrinter, type PrinterFactoryOptions } from '@kubb/ast'
+ *
  * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
  *
  * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
@@ -173,7 +177,9 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
  *   nodes: {
  *     string: () => 'z.string()',
  *     object(node) {
- *       const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
+ *       const props = node.properties
+ *         .map((p) => `${p.name}: ${this.transform(p.schema)}`)
+ *         .join(', ')
  *       return `z.object({ ${props} })`
  *     },
  *   },
@@ -194,7 +200,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 +208,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 +249,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

@@ -1,4 +1,6 @@
 export type { VisitorDepth } from './constants.ts'
+export type { SchemaDialect } from './dialect.ts'
+export type { DispatchRule } from './dispatch.ts'
 export type { DistributiveOmit } from './factory.ts'
 export type { InferSchema, InferSchemaNode, ParserOptions } from './infer.ts'
 export type {
@@ -21,11 +23,14 @@ export type {
   FunctionParameterNode,
   FunctionParametersNode,
   FunctionParamNode,
+  GenericOperationNode,
   HttpMethod,
+  HttpOperationNode,
   HttpStatusCode,
   ImportNode,
   InputMeta,
   InputNode,
+  InputStreamNode,
   IntersectionSchemaNode,
   Ipv4SchemaNode,
   Ipv6SchemaNode,
@@ -37,6 +42,8 @@ export type {
   NumberSchemaNode,
   ObjectSchemaNode,
   OperationNode,
+  OperationNodeBase,
+  OperationProtocol,
   OutputNode,
   ParameterGroupNode,
   ParameterLocation,

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)
 }
 
 /**
@@ -392,7 +394,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
   } else {
     if (pathParams.length) {
       if (pathParamsType === 'inlineSpread') {
-        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!) ?? undefined
+        const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!)
         params.push(
           createFunctionParameter({
             name: pathName,
@@ -474,7 +476,7 @@ function buildGroupParam({
   name: string
   node: OperationNode
   params: Array<ParameterNode>
-  groupType: ParamGroupType | undefined
+  groupType: ParamGroupType | null | undefined
   resolver: OperationParamsResolver | undefined
   wrapType: (type: string) => ParamsTypeNode
 }): Array<FunctionParameterNode> {
@@ -496,7 +498,7 @@ function buildGroupParam({
 
 /**
  * Derives a {@link ParamGroupType} from the resolver's group method.
- * Returns `undefined` when the group name equals the individual param name (no real group).
+ * Returns `null` when the group name equals the individual param name (no real group).
  */
 function resolveGroupType({
   node,
@@ -508,14 +510,14 @@ function resolveGroupType({
   params: Array<ParameterNode>
   groupMethod: (_node: OperationNode, _param: ParameterNode) => string
   resolver: OperationParamsResolver
-}): ParamGroupType | undefined {
+}): ParamGroupType | null {
   if (!params.length) {
-    return undefined
+    return null
   }
   const firstParam = params[0]!
   const groupName = groupMethod.call(resolver, node, firstParam)
   if (groupName === resolver.resolveParamName(node, firstParam)) {
-    return undefined
+    return null
   }
   const allOptional = params.every((p) => !p.required)
   return {
@@ -554,15 +556,15 @@ function sourceKey(source: SourceNode): string {
   return `${nameKey}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`
 }
 
-function pathTypeKey(path: string, isTypeOnly: boolean | undefined): string {
+function pathTypeKey(path: string, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${isTypeOnly ?? false}`
 }
 
-function exportKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined, asAlias: boolean | undefined): string {
+function exportKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined, asAlias: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}:${asAlias ?? ''}`
 }
 
-function importKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined): string {
+function importKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}`
 }
 
@@ -570,7 +572,7 @@ function importKey(path: string, name: string | undefined, isTypeOnly: boolean |
  * Computes a multi-level sort key for exports and imports:
  * non-array names first (wildcards/namespace aliases); type-only before value; alphabetical path; unnamed before named.
  */
-function sortKey(node: { name?: string | Array<unknown>; isTypeOnly?: boolean; path: string }): string {
+function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boolean | null; path: string }): string {
   const isArray = Array.isArray(node.name) ? '1' : '0'
   const typeOnly = node.isTypeOnly ? '0' : '1'
   const hasName = node.name != null ? '1' : '0'
@@ -592,6 +594,17 @@ export function combineSources(sources: Array<SourceNode>): Array<SourceNode> {
   return [...seen.values()]
 }
 
+/**
+ * Merges `incoming` names into `existing`, preserving order and dropping duplicates.
+ *
+ * Shared by `combineExports` and `combineImports` for the same-path name-merge case.
+ */
+function mergeNameArrays<TName>(existing: Array<TName>, incoming: Array<TName>): Array<TName> {
+  const merged = new Set(existing)
+  for (const name of incoming) merged.add(name)
+  return [...merged]
+}
+
 /**
  * Deduplicates and merges `ExportNode` objects by path and type.
  *
@@ -619,9 +632,7 @@ export function combineExports(exports: Array<ExportNode>): Array<ExportNode> {
       const existing = namedByPath.get(key)
 
       if (existing && Array.isArray(existing.name)) {
-        const merged = new Set(existing.name)
-        for (const n of name) merged.add(n)
-        existing.name = [...merged]
+        existing.name = mergeNameArrays(existing.name, name)
       } else {
         const newItem: ExportNode = { ...curr, name: [...new Set(name)] }
         result.push(newItem)
@@ -662,6 +673,17 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
     return importNameMemo.get(key)!
   }
 
+  // Paths that keep at least one used named import. A default import from such a path is retained
+  // even when its binding can't be found in `source` — e.g. a generated `client` default import
+  // alongside `import type { Client } from <same path>`, where merged grouped output omits the body.
+  const pathsWithUsedNamedImport = new Set<string>()
+  for (const node of imports) {
+    if (!Array.isArray(node.name)) continue
+    if (node.name.some((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))) {
+      pathsWithUsedNamedImport.add(node.path)
+    }
+  }
+
   const result: Array<ImportNode> = []
   // Accumulates array-named imports keyed by `path:isTypeOnly` for name-merging
   const namedByPath = new Map<string, ImportNode>()
@@ -686,16 +708,14 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
       const existing = namedByPath.get(key)
 
       if (existing && Array.isArray(existing.name)) {
-        const merged = new Set(existing.name)
-        for (const n of name) merged.add(n)
-        existing.name = [...merged]
+        existing.name = mergeNameArrays(existing.name, name)
       } else {
         const newItem: ImportNode = { ...curr, name }
         result.push(newItem)
         namedByPath.set(key, newItem)
       }
     } else {
-      if (name && !isUsed(name)) continue
+      if (name && !isUsed(name) && !pathsWithUsedNamedImport.has(path)) continue
 
       const key = importKey(path, name, isTypeOnly)
       if (!seen.has(key)) {
@@ -723,13 +743,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[] = []
+
+      const parts: Array<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)
@@ -739,7 +764,7 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
 /**
  * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
  *
- * Returns `undefined` for non-ref nodes or when no name can be resolved. Use this to get a schema's
+ * Returns `null` for non-ref nodes or when no name can be resolved. Use this to get a schema's
  * identifier for type definitions or error messages.
  *
  * @example
@@ -748,11 +773,11 @@ export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): str
  * // => 'Pet'
  * ```
  */
-export function resolveRefName(node: SchemaNode | undefined): string | undefined {
-  if (!node || node.type !== 'ref') return undefined
-  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? undefined
+export function resolveRefName(node: SchemaNode | undefined): string | null {
+  if (!node || node.type !== 'ref') return null
+  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null
 
-  return node.name ?? node.schema?.name ?? undefined
+  return node.name ?? node.schema?.name ?? null
 }
 
 /**
@@ -775,18 +800,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
 }
 
@@ -803,10 +832,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
  * }
@@ -814,16 +843,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>()
@@ -834,15 +865,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)
     }
   }
@@ -850,16 +879,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) {
@@ -870,7 +896,7 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
   const circular = new Set<string>()
   for (const start of graph.keys()) {
     const visited = new Set<string>()
-    const stack: string[] = [...(graph.get(start) ?? [])]
+    const stack: Array<string> = [...(graph.get(start) ?? [])]
     while (stack.length > 0) {
       const node = stack.pop()!
       if (node === start) {
@@ -886,6 +912,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)
 }
 
 /**
@@ -902,14 +942,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
+      if (child.type !== 'ref') return null
       const name = resolveRefName(child)
-
-      return name && name !== excludeName && circularSchemas.has(name) ? true : undefined
+      return name && name !== excludeName && circularSchemas.has(name) ? true : null
     },
-  })
+  })) {
+    return true
+  }
 
-  return matches.length > 0
+  return false
 }