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

package/dist/index.d.ts

@@ -1120,6 +1120,10 @@ type SchemaNodeBase = BaseNode & {
    * For example, this is `'string'` for a `uuid` schema.
    */
   primitive?: PrimitiveSchemaType;
+  /**
+   * Schema `format` value.
+   */
+  format?: string;
 };
 /**
  * Object schema with ordered properties.
@@ -1322,8 +1326,9 @@ 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.
@@ -1336,12 +1341,13 @@ 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;
 };
 /**
  * Datetime schema.
@@ -1689,7 +1695,7 @@ 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;
 };
 //#endregion
 //#region src/nodes/operation.d.ts
@@ -1790,7 +1796,7 @@ 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;
     }>;
   };
   /**
@@ -1826,32 +1832,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 | 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)) { ... }
+   * ```
+   */
+  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)`
    */
-  baseURL?: string;
+  enumNames: readonly string[];
 };
 /**
  * Input AST node that contains all schemas and operations for one API document.
@@ -1880,7 +1916,38 @@ 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
+ * }
+ * ```
+ */
+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;
 };
@@ -2092,6 +2159,15 @@ type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
  * ```
  */
 declare function createInput(overrides?: Partial<Omit<InputNode, 'kind'>>): InputNode;
+/**
+ * Creates an `InputStreamNode` from pre-built `AsyncIterable` sources.
+ *
+ * @example
+ * ```ts
+ * const node = createStreamInput(schemasIterable, operationsIterable, { title: 'My API' })
+ * ```
+ */
+declare function createStreamInput(schemas: AsyncIterable<SchemaNode>, operations: AsyncIterable<OperationNode>, meta?: InputMeta): InputStreamNode;
 /**
  * Creates an `OutputNode` with a stable default for `files`.
  *
@@ -2583,10 +2659,10 @@ declare function createJsx(value: string): JsxNode;
  * @example
  * ```ts
  * const schema = createSchema({ type: 'string' })
- * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | undefined
+ * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
  * ```
  */
-declare function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | undefined;
+declare function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null;
 /**
  * Returns `true` when the input is an `InputNode`.
  *
@@ -2651,7 +2727,7 @@ 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.
    */
@@ -2669,7 +2745,7 @@ type PrinterHandlerContext<TOutput, TOptions extends object> = {
  * }
  * ```
  */
-type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null | undefined;
+type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null;
 /**
  * Partial map of per-node-type handler overrides for a printer.
  *
@@ -2732,13 +2808,13 @@ 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;
 };
 /**
  * Builder function passed to `definePrinter`.
@@ -2811,22 +2887,22 @@ declare function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryO
  * )
  * ```
  */
-declare function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined): <T extends PrinterFactoryOptions>(build: (options: T["options"]) => {
+declare function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | null): <T extends PrinterFactoryOptions>(build: (options: T["options"]) => {
   name: T["name"];
   options: T["options"];
   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 }>;
+  }, node: TNodeByKey[K]) => 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;
+  }, node: TNode) => 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;
 };
 //#endregion
 //#region src/refs.d.ts
@@ -2860,7 +2936,7 @@ declare function collectImports<TImport>({
 }: {
   node: SchemaNode;
   nameMapping: Map<string, string>;
-  resolve: (schemaName: string) => TImport | undefined;
+  resolve: (schemaName: string) => TImport | null;
 }): Array<TImport>;
 //#endregion
 //#region src/transformers.d.ts
@@ -2901,6 +2977,7 @@ declare function setDiscriminatorEnum({
  * ])
  * ```
  */
+declare function mergeAdjacentObjectsLazy(members: Iterable<SchemaNode>): Generator<SchemaNode, void, undefined>;
 declare function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode>;
 /**
  * Removes enum members that are covered by broader scalar primitives in the same union.
@@ -3028,13 +3105,13 @@ type AsyncVisitor = {
  * ```
  */
 type CollectVisitor<T> = {
-  input?(node: InputNode, context: VisitorContext<InputNode>): T | undefined;
-  output?(node: OutputNode, context: VisitorContext<OutputNode>): T | undefined;
-  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | undefined;
-  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | undefined;
-  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | undefined;
-  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | undefined;
-  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | undefined;
+  input?(node: InputNode, context: VisitorContext<InputNode>): T | null | undefined;
+  output?(node: OutputNode, context: VisitorContext<OutputNode>): T | null | undefined;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | null | undefined;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | null | undefined;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | null | undefined;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | null | undefined;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | null | undefined;
 };
 /**
  * Options for `transform`.
@@ -3153,7 +3230,7 @@ declare function transform(node: Node, options: TransformOptions): Node;
 /**
  * Runs a depth-first synchronous collection pass.
  *
- * Non-`undefined` values returned by visitor callbacks are appended to the result.
+ * Non-`null` values returned by visitor callbacks are appended to the result.
  *
  * @example
  * ```ts
@@ -3170,6 +3247,7 @@ declare function transform(node: Node, options: TransformOptions): Node;
  * const values = collect(root, { depth: 'shallow', root: () => 'root' })
  * ```
  */
+declare function collectLazy<T>(node: Node, options: CollectOptions<T>): Generator<T, void, undefined>;
 declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
 //#endregion
 //#region src/utils.d.ts
@@ -3194,13 +3272,6 @@ declare function syncSchemaRef(node: SchemaNode): SchemaNode;
  * types, returns `true` only when `representation` is `'string'` rather than `'date'`.
  */
 declare function isStringType(node: SchemaNode): boolean;
-/**
- * Applies casing rules to parameter names and returns a new parameter array.
- *
- * Use this before passing parameters to schema builders so output property keys match
- * 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.
- */
 declare function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode>;
 /**
  * Creates a single-property object schema used as a discriminator literal.
@@ -3361,7 +3432,7 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
 /**
  * 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
@@ -3370,56 +3441,8 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
  * // => 'Pet'
  * ```
  */
-declare function resolveRefName(node: SchemaNode | undefined): string | undefined;
-/**
- * Collects every named schema referenced (transitively) from a node via ref edges.
- *
- * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
- * Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
- *
- * @example Collect refs from a single schema
- * ```ts
- * const names = collectReferencedSchemaNames(petSchema)
- * // → Set { 'Category', 'Tag' }
- * ```
- *
- * @example Accumulate refs from multiple schemas into one set
- * ```ts
- * const out = new Set<string>()
- * for (const schema of schemas) {
- *   collectReferencedSchemaNames(schema, out)
- * }
- * ```
- */
+declare function resolveRefName(node: SchemaNode | undefined): string | null;
 declare function collectReferencedSchemaNames(node: SchemaNode | undefined, out?: Set<string>): Set<string>;
-/**
- * Collects the names of all top-level schemas transitively used by a set of operations.
- *
- * An operation uses a schema when any of its parameters, request body content, or responses
- * reference it — directly or indirectly through other named schemas.
- * The walk is iterative and safe against reference cycles.
- *
- * Use this together with `include` filters to determine which schemas from `components/schemas`
- * are reachable from the allowed operations, so that schemas used only by excluded operations
- * are not generated.
- *
- * @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)
- *
- * for (const schema of inputNode.schemas) {
- *   if (schema.name && !allowed.has(schema.name)) continue
- *   // … generate schema
- * }
- * ```
- *
- * @example Check whether a specific schema is needed
- * ```ts
- * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
- * allowed.has('OrderStatus') // false when no included operation references OrderStatus
- * ```
- */
 declare function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string>;
 /**
  * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
@@ -3447,5 +3470,5 @@ declare function containsCircularRef(node: SchemaNode | undefined, {
   excludeName?: string;
 }): boolean;
 //#endregion
-export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
+export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type InputStreamNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectLazy, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createStreamInput, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, mergeAdjacentObjectsLazy, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
 //# sourceMappingURL=index.d.ts.map