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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.19",
+  "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",

package/src/factory.ts

@@ -86,6 +86,7 @@ export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): I
   return {
     schemas: [],
     operations: [],
+    meta: { circularNames: [], enumNames: [] },
     ...overrides,
     kind: 'Input',
   }

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,9 +88,9 @@ export type InputNode = BaseNode & {
    */
   operations: Array<OperationNode>
   /**
-   * Optional document metadata populated by the adapter.
+   * Document metadata populated by the adapter.
    */
-  meta?: InputMeta
+  meta: InputMeta
 }
 
 /**
@@ -79,10 +109,18 @@ export type InputNode = BaseNode & {
  */
 export type InputStreamNode = {
   kind: 'Input'
-  /** Lazily parsed schema nodes. Each `for await` creates a fresh parse pass. */
+  /**
+   * 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. */
+  /**
+   * 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 yield. */
+  /**
+   * Document metadata available immediately, before the first yielded node.
+   */
   meta?: InputMeta
 }

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'
@@ -74,26 +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.
  */
-const caseParamsCache = new WeakMap<Array<ParameterNode>, Map<string, Array<ParameterNode>>>()
+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 }
+    }),
+  ),
+)
 
 export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
   if (!casing) return params
-
-  let byParams = caseParamsCache.get(params)
-  if (!byParams) {
-    byParams = new Map()
-    caseParamsCache.set(params, byParams)
-  }
-  const cached = byParams.get(casing)
-  if (cached) return cached
-
-  const result = params.map((param) => {
-    const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
-    return { ...param, name: transformed }
-  })
-
-  byParams.set(casing, result)
-  return result
+  return caseParamsMemo(params)(casing)
 }
 
 /**
@@ -790,12 +782,7 @@ export function resolveRefName(node: SchemaNode | undefined): string | undefined
  * }
  * ```
  */
-const schemaRefCache = new WeakMap<SchemaNode, ReadonlySet<string>>()
-
-function collectSchemaRefs(node: SchemaNode): ReadonlySet<string> {
-  const cached = schemaRefCache.get(node)
-  if (cached) return cached
-
+const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
   const refs = new Set<string>()
   collect<void>(node, {
     schema(child) {
@@ -805,9 +792,8 @@ function collectSchemaRefs(node: SchemaNode): ReadonlySet<string> {
       }
     },
   })
-  schemaRefCache.set(node, refs)
   return refs
-}
+})
 
 export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
   if (!node) return out
@@ -828,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
  * }
@@ -839,21 +825,15 @@ 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
  * ```
  */
-const usedSchemaNamesCache = new WeakMap<ReadonlyArray<OperationNode>, WeakMap<ReadonlyArray<SchemaNode>, Set<string>>>()
-
-export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
-  let byOps = usedSchemaNamesCache.get(operations)
-  if (!byOps) {
-    byOps = new WeakMap()
-    usedSchemaNamesCache.set(operations, byOps)
-  }
-  const cached = byOps.get(schemas)
-  if (cached) return cached
+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)
@@ -878,28 +858,16 @@ export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>,
     }
   }
 
-  byOps.set(schemas, result)
   return result
 }
 
-const EMPTY_CIRCULAR_SET = new Set<string>()
-const circularSchemaCache = new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>()
-
-/**
- * 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
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  return collectUsedSchemaNamesMemo(operations)(schemas)
+}
 
-  const cached = circularSchemaCache.get(schemas)
-  if (cached) return cached
+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) {
@@ -925,8 +893,21 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
     }
   }
 
-  circularSchemaCache.set(schemas, circular)
   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)
 }
 
 /**

package/src/visitor.ts

@@ -266,39 +266,46 @@ export type CollectOptions<T> = CollectVisitor<T> & {
  * ```
  */
 function* getChildren(node: Node, recurse: boolean): Generator<Node, void, undefined> {
-  switch (node.kind) {
-    case 'Input':
-      yield* node.schemas
-      yield* node.operations
-      break
-    case 'Output':
-      break
-    case 'Operation':
-      yield* node.parameters
-      if (node.requestBody?.content) {
-        for (const c of node.requestBody.content) {
-          if (c.schema) yield c.schema
-        }
+  if (node.kind === 'Input') {
+    yield* node.schemas
+    yield* node.operations
+
+    return
+  }
+  if (node.kind === 'Output') return
+  if (node.kind === 'Operation') {
+    yield* node.parameters
+    if (node.requestBody?.content) {
+      for (const c of node.requestBody.content) {
+        if (c.schema) yield c.schema
       }
-      yield* node.responses
-      break
-    case 'Schema': {
-      if (!recurse) break
-      if ('properties' in node && node.properties.length > 0) yield* node.properties
-      if ('items' in node && node.items) yield* node.items
-      if ('members' in node && node.members) yield* node.members
-      if ('additionalProperties' in node && node.additionalProperties && node.additionalProperties !== true) yield node.additionalProperties
-      break
     }
-    case 'Property':
-      yield node.schema
-      break
-    case 'Parameter':
-      yield node.schema
-      break
-    case 'Response':
-      if (node.schema) yield node.schema
-      break
+    yield* node.responses
+
+    return
+  }
+  if (node.kind === 'Schema') {
+    if (!recurse) return
+    if ('properties' in node && node.properties.length > 0) yield* node.properties
+    if ('items' in node && node.items) yield* node.items
+    if ('members' in node && node.members) yield* node.members
+    if ('additionalProperties' in node && node.additionalProperties && node.additionalProperties !== true) yield node.additionalProperties
+
+    return
+  }
+  if (node.kind === 'Property') {
+    yield node.schema
+
+    return
+  }
+  if (node.kind === 'Parameter') {
+    yield node.schema
+
+    return
+  }
+  if (node.kind === 'Response') {
+    if (node.schema) yield node.schema
+    return
   }
 }
 
@@ -338,11 +345,7 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
       await limit(() => visitor.output?.(node, { parent: parent as ParentOf<OutputNode> }))
       break
     case 'Operation':
-      await limit(() =>
-        visitor.operation?.(node, {
-          parent: parent as ParentOf<OperationNode>,
-        }),
-      )
+      await limit(() => visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> }))
       break
     case 'Schema':
       await limit(() => visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> }))
@@ -351,19 +354,11 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
       await limit(() => visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> }))
       break
     case 'Parameter':
-      await limit(() =>
-        visitor.parameter?.(node, {
-          parent: parent as ParentOf<ParameterNode>,
-        }),
-      )
+      await limit(() => visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> }))
       break
     case 'Response':
       await limit(() => visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> }))
       break
-    case 'FunctionParameter':
-    case 'ParameterGroup':
-    case 'FunctionParameters':
-      break
   }
 
   const children = getChildren(node, recurse)
@@ -405,91 +400,89 @@ export function transform(node: Node, options: TransformOptions): Node {
   const { depth, parent, ...visitor } = options
   const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep
 
-  switch (node.kind) {
-    case 'Input': {
-      const input = visitor.input?.(node, { parent: parent as ParentOf<InputNode> }) ?? node
+  if (node.kind === 'Input') {
+    const input = visitor.input?.(node, { parent: parent as ParentOf<InputNode> }) ?? node
 
-      return {
-        ...input,
-        schemas: input.schemas.map((s) => transform(s, { ...options, parent: input })),
-        operations: input.operations.map((op) => transform(op, { ...options, parent: input })),
-      }
-    }
-    case 'Output': {
-      const output = visitor.output?.(node, { parent: parent as ParentOf<OutputNode> }) ?? node
-      return output
-    }
-    case 'Operation': {
-      const op = visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> }) ?? node
-
-      return {
-        ...op,
-        parameters: op.parameters.map((p) => transform(p, { ...options, parent: op })),
-        requestBody: op.requestBody
-          ? {
-              ...op.requestBody,
-              content: op.requestBody.content?.map((c) => ({
-                ...c,
-                schema: c.schema ? transform(c.schema, { ...options, parent: op }) : undefined,
-              })),
-            }
-          : undefined,
-        responses: op.responses.map((r) => transform(r, { ...options, parent: op })),
-      }
-    }
-    case 'Schema': {
-      const schema = visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> }) ?? node
-
-      const childOptions = { ...options, parent: schema }
-
-      return {
-        ...schema,
-        ...('properties' in schema && recurse
-          ? {
-              properties: schema.properties.map((p) => transform(p, childOptions)),
-            }
-          : {}),
-        ...('items' in schema && recurse ? { items: schema.items?.map((i) => transform(i, childOptions)) } : {}),
-        ...('members' in schema && recurse ? { members: schema.members?.map((m) => transform(m, childOptions)) } : {}),
-        ...('additionalProperties' in schema && recurse && schema.additionalProperties && schema.additionalProperties !== true
-          ? {
-              additionalProperties: transform(schema.additionalProperties, childOptions),
-            }
-          : {}),
-      } as SchemaNode
+    return {
+      ...input,
+      schemas: input.schemas.map((s) => transform(s, { ...options, parent: input })),
+      operations: input.operations.map((op) => transform(op, { ...options, parent: input })),
     }
-    case 'Property': {
-      const prop = visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> }) ?? node
+  }
 
-      return createProperty({
-        ...prop,
-        schema: transform(prop.schema, { ...options, parent: prop }),
-      })
-    }
-    case 'Parameter': {
-      const param = visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> }) ?? node
+  if (node.kind === 'Output') {
+    return visitor.output?.(node, { parent: parent as ParentOf<OutputNode> }) ?? node
+  }
 
-      return createParameter({
-        ...param,
-        schema: transform(param.schema, { ...options, parent: param }),
-      })
+  if (node.kind === 'Operation') {
+    const op = visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> }) ?? node
+
+    return {
+      ...op,
+      parameters: op.parameters.map((p) => transform(p, { ...options, parent: op })),
+      requestBody: op.requestBody
+        ? {
+            ...op.requestBody,
+            content: op.requestBody.content?.map((c) => ({
+              ...c,
+              schema: c.schema ? transform(c.schema, { ...options, parent: op }) : undefined,
+            })),
+          }
+        : undefined,
+      responses: op.responses.map((r) => transform(r, { ...options, parent: op })),
     }
-    case 'Response': {
-      const response = visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> }) ?? node
+  }
 
-      return {
-        ...response,
-        schema: transform(response.schema, { ...options, parent: response }),
-      }
+  if (node.kind === 'Schema') {
+    const schema = visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> }) ?? node
+
+    const childOptions = { ...options, parent: schema }
+
+    return {
+      ...schema,
+      ...('properties' in schema && recurse
+        ? {
+            properties: schema.properties.map((p) => transform(p, childOptions)),
+          }
+        : {}),
+      ...('items' in schema && recurse ? { items: schema.items?.map((i) => transform(i, childOptions)) } : {}),
+      ...('members' in schema && recurse ? { members: schema.members?.map((m) => transform(m, childOptions)) } : {}),
+      ...('additionalProperties' in schema && recurse && schema.additionalProperties && schema.additionalProperties !== true
+        ? {
+            additionalProperties: transform(schema.additionalProperties, childOptions),
+          }
+        : {}),
+    } as SchemaNode
+  }
+
+  if (node.kind === 'Property') {
+    const prop = visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> }) ?? node
+
+    return createProperty({
+      ...prop,
+      schema: transform(prop.schema, { ...options, parent: prop }),
+    })
+  }
+
+  if (node.kind === 'Parameter') {
+    const param = visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> }) ?? node
+
+    return createParameter({
+      ...param,
+      schema: transform(param.schema, { ...options, parent: param }),
+    })
+  }
+
+  if (node.kind === 'Response') {
+    const response = visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> }) ?? node
+
+    return {
+      ...response,
+      schema: transform(response.schema, { ...options, parent: response }),
     }
-    case 'FunctionParameter':
-    case 'ParameterGroup':
-    case 'FunctionParameters':
-    case 'Type':
-      return node
-    default:
-      return node
   }
+
+  return node
 }
 /**
  * Runs a depth-first synchronous collection pass.
@@ -524,31 +517,19 @@ export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generat
       v = visitor.output?.(node, { parent: parent as ParentOf<OutputNode> })
       break
     case 'Operation':
-      v = visitor.operation?.(node, {
-        parent: parent as ParentOf<OperationNode>,
-      })
+      v = visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> })
       break
     case 'Schema':
       v = visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> })
       break
     case 'Property':
-      v = visitor.property?.(node, {
-        parent: parent as ParentOf<PropertyNode>,
-      })
+      v = visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> })
       break
     case 'Parameter':
-      v = visitor.parameter?.(node, {
-        parent: parent as ParentOf<ParameterNode>,
-      })
+      v = visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> })
       break
     case 'Response':
-      v = visitor.response?.(node, {
-        parent: parent as ParentOf<ResponseNode>,
-      })
-      break
-    case 'FunctionParameter':
-    case 'ParameterGroup':
-    case 'FunctionParameters':
+      v = visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> })
       break
   }
   if (v !== undefined) yield v