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

package/dist/index.d.ts

@@ -1830,32 +1830,62 @@ type OutputNode = BaseNode & {
 //#endregion
 //#region src/nodes/root.d.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: [] }
  * ```
  */
 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[];
 };
 /**
  * Input AST node that contains all schemas and operations for one API document.
@@ -1884,9 +1914,9 @@ type InputNode = BaseNode & {
    */
   operations: Array<OperationNode>;
   /**
-   * Optional document metadata populated by the adapter.
+   * Document metadata populated by the adapter.
    */
-  meta?: InputMeta;
+  meta: InputMeta;
 };
 /**
  * Streaming variant of `InputNode` for memory-efficient processing of large API specs.
@@ -1903,9 +1933,20 @@ type InputNode = BaseNode & {
  * ```
  */
 type InputStreamNode = {
-  kind: 'Input'; /** Lazily parsed schema nodes. Each `for await` creates a fresh parse pass. */
-  schemas: AsyncIterable<SchemaNode>; /** Lazily parsed operation nodes. Each `for await` creates a fresh parse pass. */
-  operations: AsyncIterable<OperationNode>; /** Document metadata — available immediately, before the first yield. */
+  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;
 };
 //#endregion

package/dist/index.js

@@ -265,6 +265,46 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/promise.ts
+/**
+* Wraps `factory` with a keyed cache backed by the provided store.
+*
+* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
+* collected) or a `Map` for primitive keys. For multi-argument functions,
+* nest two `memoize` calls — the outer keyed by the first argument, the
+* inner (created once per outer miss) keyed by the second.
+*
+* Because the cache is owned by the caller, it can be shared, inspected, or
+* cleared independently of the memoized function.
+*
+* @example Single WeakMap key
+* ```ts
+* const cache = new WeakMap<SchemaNode, Set<string>>()
+* const getRefs = memoize(cache, (node) => collectRefs(node))
+* ```
+*
+* @example Single Map key (primitive)
+* ```ts
+* const cache = new Map<string, Resolver>()
+* const getResolver = memoize(cache, (name) => buildResolver(name))
+* ```
+*
+* @example Two-level (object + primitive)
+* ```ts
+* const outer = new WeakMap<Params[], Map<string, Params[]>>()
+* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
+* fn(params)('camelcase')
+* ```
+*/
+function memoize(store, factory) {
+	return (key) => {
+		if (store.has(key)) return store.get(key);
+		const value = factory(key);
+		store.set(key, value);
+		return value;
+	};
+}
+//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * JavaScript and Java reserved words.
@@ -511,35 +551,39 @@ function createLimit(concurrency) {
 * ```
 */
 function* getChildren(node, recurse) {
-	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;
-			}
-			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;
+	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;
+		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;
 	}
 }
 /**
@@ -588,9 +632,6 @@ async function _walk(node, visitor, recurse, limit, parent) {
 		case "Response":
 			await limit(() => visitor.response?.(node, { parent }));
 			break;
-		case "FunctionParameter":
-		case "ParameterGroup":
-		case "FunctionParameters": break;
 	}
 	const children = getChildren(node, recurse);
 	for (const child of children) await _walk(child, visitor, recurse, limit, node);
@@ -598,96 +639,90 @@ async function _walk(node, visitor, recurse, limit, parent) {
 function transform(node, options) {
 	const { depth, parent, ...visitor } = options;
 	const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep;
-	switch (node.kind) {
-		case "Input": {
-			const input = visitor.input?.(node, { parent }) ?? 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": return visitor.output?.(node, { parent }) ?? node;
-		case "Operation": {
-			const op = visitor.operation?.(node, { parent }) ?? 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
-						}) : void 0
-					}))
-				} : void 0,
-				responses: op.responses.map((r) => transform(r, {
-					...options,
-					parent: op
+	if (node.kind === "Input") {
+		const input = visitor.input?.(node, { parent }) ?? node;
+		return {
+			...input,
+			schemas: input.schemas.map((s) => transform(s, {
+				...options,
+				parent: input
+			})),
+			operations: input.operations.map((op) => transform(op, {
+				...options,
+				parent: input
+			}))
+		};
+	}
+	if (node.kind === "Output") return visitor.output?.(node, { parent }) ?? node;
+	if (node.kind === "Operation") {
+		const op = visitor.operation?.(node, { parent }) ?? 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
+					}) : void 0
 				}))
-			};
-		}
-		case "Schema": {
-			const schema = visitor.schema?.(node, { parent }) ?? node;
-			const childOptions = {
+			} : void 0,
+			responses: op.responses.map((r) => transform(r, {
 				...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) } : {}
-			};
-		}
-		case "Property": {
-			const prop = visitor.property?.(node, { parent }) ?? node;
-			return createProperty({
-				...prop,
-				schema: transform(prop.schema, {
-					...options,
-					parent: prop
-				})
-			});
-		}
-		case "Parameter": {
-			const param = visitor.parameter?.(node, { parent }) ?? node;
-			return createParameter({
-				...param,
-				schema: transform(param.schema, {
-					...options,
-					parent: param
-				})
-			});
-		}
-		case "Response": {
-			const response = visitor.response?.(node, { parent }) ?? node;
-			return {
-				...response,
-				schema: transform(response.schema, {
-					...options,
-					parent: response
-				})
-			};
-		}
-		case "FunctionParameter":
-		case "ParameterGroup":
-		case "FunctionParameters":
-		case "Type": return node;
-		default: return node;
+				parent: op
+			}))
+		};
+	}
+	if (node.kind === "Schema") {
+		const schema = visitor.schema?.(node, { parent }) ?? 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) } : {}
+		};
+	}
+	if (node.kind === "Property") {
+		const prop = visitor.property?.(node, { parent }) ?? node;
+		return createProperty({
+			...prop,
+			schema: transform(prop.schema, {
+				...options,
+				parent: prop
+			})
+		});
 	}
+	if (node.kind === "Parameter") {
+		const param = visitor.parameter?.(node, { parent }) ?? node;
+		return createParameter({
+			...param,
+			schema: transform(param.schema, {
+				...options,
+				parent: param
+			})
+		});
+	}
+	if (node.kind === "Response") {
+		const response = visitor.response?.(node, { parent }) ?? node;
+		return {
+			...response,
+			schema: transform(response.schema, {
+				...options,
+				parent: response
+			})
+		};
+	}
+	return node;
 }
 /**
 * Runs a depth-first synchronous collection pass.
@@ -735,9 +770,6 @@ function* collectLazy(node, options) {
 		case "Response":
 			v = visitor.response?.(node, { parent });
 			break;
-		case "FunctionParameter":
-		case "ParameterGroup":
-		case "FunctionParameters": break;
 	}
 	if (v !== void 0) yield v;
 	for (const child of getChildren(node, recurse)) yield* collectLazy(child, {
@@ -800,25 +832,16 @@ function isStringType(node) {
 * 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 = /* @__PURE__ */ new WeakMap();
+const caseParamsMemo = memoize(/* @__PURE__ */ new WeakMap(), (params) => memoize(/* @__PURE__ */ new Map(), (casing) => params.map((param) => {
+	const transformed = casing === "camelcase" || !isValidVarName(param.name) ? camelCase(param.name) : param.name;
+	return {
+		...param,
+		name: transformed
+	};
+})));
 function caseParams(params, casing) {
 	if (!casing) return params;
-	let byParams = caseParamsCache.get(params);
-	if (!byParams) {
-		byParams = /* @__PURE__ */ 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);
 }
 /**
 * Creates a single-property object schema used as a discriminator literal.
@@ -1256,10 +1279,7 @@ function resolveRefName(node) {
 * }
 * ```
 */
-const schemaRefCache = /* @__PURE__ */ new WeakMap();
-function collectSchemaRefs(node) {
-	const cached = schemaRefCache.get(node);
-	if (cached) return cached;
+const collectSchemaRefs = memoize(/* @__PURE__ */ new WeakMap(), (node) => {
 	const refs = /* @__PURE__ */ new Set();
 	collect(node, { schema(child) {
 		if (child.type === "ref") {
@@ -1267,9 +1287,8 @@ function collectSchemaRefs(node) {
 			if (name) refs.add(name);
 		}
 	} });
-	schemaRefCache.set(node, refs);
 	return refs;
-}
+});
 function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	if (!node) return out;
 	for (const name of collectSchemaRefs(node)) out.add(name);
@@ -1288,10 +1307,10 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 *
 * @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
 * }
@@ -1299,19 +1318,12 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 *
 * @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 = /* @__PURE__ */ new WeakMap();
-function collectUsedSchemaNames(operations, schemas) {
-	let byOps = usedSchemaNamesCache.get(operations);
-	if (!byOps) {
-		byOps = /* @__PURE__ */ new WeakMap();
-		usedSchemaNamesCache.set(operations, byOps);
-	}
-	const cached = byOps.get(schemas);
-	if (cached) return cached;
+const collectUsedSchemaNamesMemo = memoize(/* @__PURE__ */ new WeakMap(), (ops) => memoize(/* @__PURE__ */ new WeakMap(), (schemas) => computeUsedSchemaNames(ops, schemas)));
+function computeUsedSchemaNames(operations, schemas) {
 	const schemaMap = /* @__PURE__ */ new Map();
 	for (const schema of schemas) if (schema.name) schemaMap.set(schema.name, schema);
 	const result = /* @__PURE__ */ new Set();
@@ -1327,24 +1339,13 @@ function collectUsedSchemaNames(operations, schemas) {
 		depth: "shallow",
 		schema: (node) => node
 	})) visitSchema(schema);
-	byOps.set(schemas, result);
 	return result;
 }
+function collectUsedSchemaNames(operations, schemas) {
+	return collectUsedSchemaNamesMemo(operations)(schemas);
+}
 const EMPTY_CIRCULAR_SET = /* @__PURE__ */ new Set();
-const circularSchemaCache = /* @__PURE__ */ new WeakMap();
-/**
-* 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.
-*/
-function findCircularSchemas(schemas) {
-	if (schemas.length === 0) return EMPTY_CIRCULAR_SET;
-	const cached = circularSchemaCache.get(schemas);
-	if (cached) return cached;
+const findCircularSchemasMemo = memoize(/* @__PURE__ */ new WeakMap(), (schemas) => {
 	const graph = /* @__PURE__ */ new Map();
 	for (const schema of schemas) {
 		if (!schema.name) continue;
@@ -1366,8 +1367,20 @@ function findCircularSchemas(schemas) {
 			if (next) for (const r of next) stack.push(r);
 		}
 	}
-	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.
+*/
+function findCircularSchemas(schemas) {
+	if (schemas.length === 0) return EMPTY_CIRCULAR_SET;
+	return findCircularSchemasMemo(schemas);
 }
 /**
 * Type guard returning `true` when a schema or anything nested within it contains a ref to a circular schema.
@@ -1421,6 +1434,10 @@ function createInput(overrides = {}) {
 	return {
 		schemas: [],
 		operations: [],
+		meta: {
+			circularNames: [],
+			enumNames: []
+		},
 		...overrides,
 		kind: "Input"
 	};