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

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.
@@ -1826,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.
@@ -1880,7 +1914,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 +2157,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`.
  *
@@ -2901,6 +2975,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.
@@ -3170,6 +3245,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 +3270,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.
@@ -3371,55 +3440,7 @@ declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): st
  * ```
  */
 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 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 +3468,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