@kubb/ast 5.15.1 → 5.15.2

package/dist/index.d.cts

@@ -22,14 +22,6 @@ export declare const nodeKinds: {
   readonly break: 'Break';
   readonly jsx: 'Jsx';
 };
-/**
- * Traversal depth for AST visitor utilities.
- *
- * - `'shallow'` recurses through every node except nested `Schema` subtrees, which it treats as
- *   leaves: a schema node itself is visited, but its children are not.
- * - `'deep'` recursively visits all descendant nodes, including schema subtrees.
- */
-type VisitorDepth = 'shallow' | 'deep';
 /**
  * Schema type discriminators used by all AST schema nodes.
  *
@@ -143,6 +135,10 @@ export declare const schemaTypes: {
    */
   readonly never: 'never';
 };
+/**
+ * Union of the values of an object type, such as `ValueOf<typeof nodeKinds>` for an `as const` table.
+ */
+type ValueOf<T> = T[keyof T];
 /**
  * `kind` values used by AST nodes.
  *
@@ -151,7 +147,7 @@ export declare const schemaTypes: {
  * const kind: NodeKind = 'Schema'
  * ```
  */
-type NodeKind = 'Input' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Response' | 'RequestBody' | 'Content' | 'Type' | 'File' | 'Import' | 'Export' | 'Source' | 'Const' | 'Function' | 'ArrowFunction' | 'Text' | 'Break' | 'Jsx';
+type NodeKind = ValueOf<typeof nodeKinds>;
 /**
  * Base shape shared by all AST nodes.
  *
@@ -221,59 +217,10 @@ type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<Pro
  * ```
  */
 declare function createProperty(input: UserPropertyNode): PropertyNode;
-type PrimitiveSchemaType =
-/**
- * Text value.
- */
-'string' |
-/**
- * Floating-point number.
- */
-'number' |
 /**
- * Integer number.
+ * Subset of {@link SchemaType} covering the primitives plus `object`, `array`, and `date`; `schemaTypes` documents each.
  */
-'integer' |
-/**
- * Big integer number.
- */
-'bigint' |
-/**
- * Boolean value.
- */
-'boolean' |
-/**
- * Null value.
- */
-'null' |
-/**
- * Any value.
- */
-'any' |
-/**
- * Unknown value.
- */
-'unknown' |
-/**
- * No value (`void`).
- */
-'void' |
-/**
- * Never value.
- */
-'never' |
-/**
- * Object value.
- */
-'object' |
-/**
- * Array value.
- */
-'array' |
-/**
- * Date value.
- */
-'date';
+type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'never' | 'object' | 'array' | 'date';
 /**
  * All schema type strings, one per key of {@link SchemaNodeByType}.
  */
@@ -1853,9 +1800,6 @@ type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>, 'kind'
  * ```
  */
 declare function createFile<TMeta extends object = object>(input: UserFileNode<TMeta>): FileNode<TMeta>;
-/**
- * A server from the source document, with `{variable}` placeholders filled from their defaults.
- */
 /**
  * A variable declared by a server URL template.
  */
@@ -1864,6 +1808,9 @@ type InputServerVariable = {
   enum?: Array<string>;
   description?: string;
 };
+/**
+ * A server from the source document, with `{variable}` placeholders filled from their defaults.
+ */
 type InputServer = {
   url: string;
   description?: string;
@@ -1887,14 +1834,11 @@ type InputSecurityScheme = {
 };
 /**
  * Metadata for an API document, populated by the adapter and available to every generator.
- *
- * Computed fields (`circularNames`, `enumNames`) are sets, pre-calculated once during the adapter
- * pre-scan so generators never need to iterate the full schema list themselves. Every other field
- * is a plain JSON value.
+ * Every field is a plain JSON value.
  *
  * @example
  * ```ts
- * const meta: InputMeta = { title: 'Pet Store', version: '1.0.0', baseURL: 'https://api.example.com/v2', circularNames: new Set(), enumNames: new Set() }
+ * const meta: InputMeta = { title: 'Pet Store', version: '1.0.0', baseURL: 'https://api.example.com/v2' }
  * ```
  */
 type InputMeta = {
@@ -1920,28 +1864,6 @@ type InputMeta = {
    * Vendor extensions (`x-*` keys) from the document root, copied as-is. Absent when the root has none.
    */
   extensions?: Record<string, unknown>;
-  /**
-   * Names of schemas that participate in a circular reference chain.
-   * Computed once during the adapter pre-scan, so a generator never has to
-   * call `findCircularSchemas` itself.
-   *
-   * @example Wrap a circular schema in z.lazy()
-   * ```ts
-   * if (meta.circularNames.has(schema.name)) { ... }
-   * ```
-   */
-  circularNames: ReadonlySet<string>;
-  /**
-   * Names of schemas whose type is `enum`.
-   * Computed once during the adapter pre-scan, so a generator never has to
-   * filter the schema list itself.
-   *
-   * @example Check if a referenced schema is an enum
-   * ```ts
-   * const isEnum = meta.enumNames.has(schemaName)
-   * ```
-   */
-  enumNames: ReadonlySet<string>;
 };
 /**
  * Input AST node that contains all schemas and operations for one API document.
@@ -1953,7 +1875,7 @@ type InputMeta = {
  *   kind: 'Input',
  *   schemas: [],
  *   operations: [],
- *   meta: { circularNames: new Set(), enumNames: new Set() },
+ *   meta: {},
  * }
  * ```
  */
@@ -1976,8 +1898,8 @@ type InputNode = BaseNode & {
   meta: InputMeta;
 };
 /**
- * Creates an `InputNode`, defaulting `schemas`/`operations` to empty arrays and `meta` to empty
- * name lists. Every call allocates fresh defaults so no two inputs share them.
+ * Creates an `InputNode`, defaulting `schemas`/`operations` to empty arrays and `meta` to an empty
+ * object. Every call allocates fresh defaults so no two inputs share them.
  *
  * @example
  * ```ts
@@ -2008,54 +1930,30 @@ declare namespace index_d_exports$1 {
  */
 type Node = InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | RequestBodyNode | ContentNode | FileNode | ImportNode | ExportNode | SourceNode | ConstNode | TypeNode | FunctionNode | ArrowFunctionNode | TextNode | BreakNode | JsxNode;
 /**
- * Ordered mapping of `[NodeType, ParentType]` pairs.
- *
- * `ParentOf` uses this map to find parent types.
- */
-type ParentNodeMap = [[InputNode, undefined], [OperationNode, InputNode], [RequestBodyNode, OperationNode], [ContentNode, RequestBodyNode | ResponseNode], [SchemaNode, InputNode | ContentNode | SchemaNode | PropertyNode | ParameterNode], [PropertyNode, SchemaNode], [ParameterNode, OperationNode], [ResponseNode, OperationNode]];
-/**
- * Resolves the parent node type for a given AST node type.
- *
- * Visitor context relies on this so `ctx.parent` is typed for each callback.
- *
- * @example
- * ```ts
- * type InputParent = ParentOf<InputNode>
- * // undefined
- * ```
- *
- * @example
- * ```ts
- * type PropertyParent = ParentOf<PropertyNode>
- * // SchemaNode
- * ```
+ * Traversal depth for AST visitor utilities.
  *
- * @example
- * ```ts
- * type SchemaParent = ParentOf<SchemaNode>
- * // InputNode | ContentNode | SchemaNode | PropertyNode | ParameterNode
- * ```
+ * - `'shallow'` recurses through every node except nested `Schema` subtrees, which it treats as
+ *   leaves: a schema node itself is visited, but its children are not.
+ * - `'deep'` recursively visits all descendant nodes, including schema subtrees.
  */
-type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [infer TEntry extends [Node, unknown], ...infer TRest extends ReadonlyArray<[Node, unknown]>] ? T extends TEntry[0] ? TEntry[1] : ParentOf<T, TRest> : Node;
+type VisitorDepth = 'shallow' | 'deep';
 /**
  * Traversal context passed as the second argument to every visitor callback.
- * `parent` is typed from the current node type.
  *
  * @example
  * ```ts
  * const visitor: Visitor = {
  *   schema(node, { parent }) {
- *     // parent type is narrowed by node kind
+ *     // parent is the node that holds this schema, or undefined at the root
  *   },
  * }
  * ```
  */
-type VisitorContext<T extends Node = Node> = {
+type VisitorContext = {
   /**
-   * Parent node of the currently visited node.
-   * For `InputNode`, this is `undefined`.
+   * Parent node of the currently visited node. For the root node, this is `undefined`.
    */
-  parent?: ParentOf<T>;
+  parent?: Node;
 };
 /**
  * Synchronous visitor consumed by `transform`. Each optional callback runs
@@ -2084,12 +1982,12 @@ type VisitorContext<T extends Node = Node> = {
  * ```
  */
 type Visitor = {
-  input?(node: InputNode, context: VisitorContext<InputNode>): undefined | null | InputNode;
-  operation?(node: OperationNode, context: VisitorContext<OperationNode>): undefined | null | OperationNode;
-  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): undefined | null | SchemaNode;
-  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): undefined | null | PropertyNode;
-  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): undefined | null | ParameterNode;
-  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): undefined | null | ResponseNode;
+  input?(node: InputNode, context: VisitorContext): undefined | null | InputNode;
+  operation?(node: OperationNode, context: VisitorContext): undefined | null | OperationNode;
+  schema?(node: SchemaNode, context: VisitorContext): undefined | null | SchemaNode;
+  property?(node: PropertyNode, context: VisitorContext): undefined | null | PropertyNode;
+  parameter?(node: ParameterNode, context: VisitorContext): undefined | null | ParameterNode;
+  response?(node: ResponseNode, context: VisitorContext): undefined | null | ResponseNode;
 };
 /**
  * The callbacks of {@link Visitor} with every return type replaced by `TResult`. `collect` uses it
@@ -2140,28 +2038,6 @@ type TransformOptions = Visitor & TraversalOptions;
  * ```
  */
 type CollectOptions<T> = VisitorOf<T> & TraversalOptions;
-/**
- * Visits each direct child node in the AST's traversal order.
- *
- * @example
- * ```ts
- * forEachChild(operationNode, (child) => {
- *   console.log(child.kind)
- * })
- * ```
- */
-export declare function forEachChild(node: Node, visit: (child: Node) => void): void;
-/**
- * Visits each schema in a node's child tree in depth-first order. Includes `node` when it is a schema.
- *
- * @example
- * ```ts
- * forEachSchema(operationNode, (schema) => {
- *   console.log(schema.type)
- * })
- * ```
- */
-export declare function forEachSchema(node: Node, visit: (schema: SchemaNode) => void): void;
 /**
  * Finds the first schema that matches `predicate` in depth-first order. Set `followRefs` to include resolved ref targets.
  *
@@ -2237,6 +2113,14 @@ export declare function collectSync<T>(node: Node, options: CollectOptions<T>):
  * and `undefined` keeps declaration order.
  */
 type Enforce = 'pre' | 'post';
+/**
+ * Compares two `enforce` hints for `Array.prototype.sort`: `pre` first, unmarked next, `post`
+ * last. Equal hints compare as `0`, so a stable sort keeps authored order within a bucket.
+ *
+ * @example
+ * `plugins.sort((a, b) => compareEnforce(a.enforce, b.enforce))`
+ */
+export declare function compareEnforce(a?: Enforce, b?: Enforce): number;
 /**
  * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a
  * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an
@@ -2274,19 +2158,6 @@ type Macro = Visitor & {
  * ```
  */
 export declare function defineMacro(macro: Macro): Macro;
-/**
- * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin
- * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied
- * sequentially per node so later macros see earlier output. This differs from a plain visitor, which
- * has no names, ordering, or composition.
- *
- * @example
- * ```ts
- * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])
- * const next = transform(root, visitor)
- * ```
- */
-export declare function composeMacros(macros: ReadonlyArray<Macro>): Visitor;
 /**
  * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s
  * structural sharing, so an empty or no-op macro list returns the same reference. Pass
@@ -2508,14 +2379,9 @@ export declare function createPrinter<T extends PrinterFactoryOptions = PrinterF
 /**
  * Extracts all string content from a `CodeNode` tree recursively.
  *
- * Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
- * and nested node content. Used to build the full source string for import filtering.
+ * Collects the text fields and nested node content, to build the source string for import filtering.
  */
 export declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string;
-/**
- * Whether every source of `file` is inline. Other files absorb such a file, so it is never written.
- */
-export declare function isVirtualFile(file: FileNode): boolean;
 type InlineFilesResult = {
   /**
    * Files that imported an inline name, rewritten to hold its definition.
@@ -2553,7 +2419,7 @@ type InlineFilesOptions = {
   language: (file: FileNode) => InlineLanguage | undefined;
 };
 /**
- * Replaces every name a file imports from a virtual file (see {@link isVirtualFile}) with that name's
+ * Replaces every name a file imports from a virtual file (one whose sources are all inline, so it is never written) with that name's
  * `inline.expression`, until no inline names are left. The definitions' own imports move to the importing file.
  */
 export declare function inlineFiles(files: ReadonlyArray<FileNode>, { language }: InlineFilesOptions): InlineFilesResult;
@@ -2610,9 +2476,8 @@ export declare function mergeRefWithSchema(node: RefSchemaNode): SchemaNode;
 export declare function isBareRef(node: SchemaNode | null | undefined, keysToOmit?: Array<string> | null): boolean;
 /**
  * Collects the names of every schema a node's subtree references, resolved with `resolveRefName`.
- * Each ref contributes its name only, so the schema it points to is never traversed. The walk is
- * memoized by node identity, which lets `findCircularSchemas` and `containsCircularRef` share one
- * scan per schema.
+ * Each ref contributes its name only, so the schema it points to is never traversed. Memoized by
+ * node identity, which lets `findCircularSchemas` and `containsCircularRef` share one scan per schema.
  *
  * @example
  * ```ts
@@ -2620,12 +2485,11 @@ export declare function isBareRef(node: SchemaNode | null | undefined, keysToOmi
  * // Set { 'Category', 'Tag' }
  * ```
  */
-export declare const collectSchemaRefs: (key: SchemaNode) => ReadonlySet<string>;
+export declare function collectSchemaRefs(node: SchemaNode): ReadonlySet<string>;
 /**
  * Collects the de-duplicated target names of every pointer-carrying ref in a node's subtree, in
- * first-occurrence order. The walk is memoized by node identity, so the subtree is scanned once and
- * `resolver.imports` reads the same result across the ts, zod, and faker plugins instead of
- * re-scanning the same schema per plugin.
+ * first-occurrence order. Memoized by node identity, so `resolver.imports` reads the same result
+ * across the ts, zod, and faker plugins instead of re-scanning the same schema per plugin.
  *
  * Only refs that carry a `$ref` pointer count, so a synthesized ref pointing at a sibling in the
  * same file (a union member created by name) is left out. That leaves exactly the set
@@ -2637,7 +2501,7 @@ export declare const collectSchemaRefs: (key: SchemaNode) => ReadonlySet<string>
  * // ['Category', 'Tag']
  * ```
  */
-export declare const collectImportedRefNames: (key: SchemaNode) => readonly string[];
+export declare function collectImportedRefNames(node: SchemaNode): ReadonlyArray<string>;
 /**
  * Collects the names of all top-level schemas transitively used by a set of operations.
  *
@@ -2659,24 +2523,6 @@ export declare const collectImportedRefNames: (key: SchemaNode) => readonly stri
  * ```
  */
 export declare function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string>;
-/**
- * Finds every schema that takes part in a circular dependency chain in a schema dependency graph
- * that maps each schema name to the names it references directly.
- *
- * Use this when the graph was already collected during another pass (e.g. the adapter's convert
- * walk), so the schema nodes are not swept a second time. `findCircularSchemas` builds the graph
- * from schema nodes and delegates here.
- *
- * @example
- * ```ts
- * const graph = new Map([
- *   ['Pet', new Set(['Category'])],
- *   ['Category', new Set(['Pet'])],
- * ])
- * findCircularSchemasFromGraph(graph) // Set { 'Pet', 'Category' }
- * ```
- */
-export declare function findCircularSchemasFromGraph(graph: ReadonlyMap<string, ReadonlySet<string>>): Set<string>;
 /**
  * Finds every schema that takes part in a circular dependency chain, including direct self-loops.
  *
@@ -2805,7 +2651,7 @@ type ParserOptions = {
   enumSuffix: 'enum' | (string & {});
 };
 declare namespace index_d_exports {
-  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, isVirtualFile, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+  export { ArraySchemaNode, ArrowFunctionNode, BreakNode, CodeNode, ConstNode, ContentNode, DateOnlyTypeValue, DateSchemaNode, DateTimeTypeValue, DateTypeOptions, DatetimeSchemaNode, DistributiveOmit, EncodingNode, Enforce, EnumSchemaNode, ExportNode, FileNode, FunctionNode, GenericOperationNode, HttpMethod, HttpOperationNode, ImportNode, InlineLanguage, InputMeta, InputNode, InputSecurityScheme, InputServer, IntersectionSchemaNode, JSDocNode, JsxNode, Macro, Node, NodeKind, NotSchemaNode, NumberSchemaNode, ObjectSchemaNode, OperationNode, ParameterLocation, ParameterNode, ParameterStyle, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, RequestBodyNode, ResponseNode, ScalarSchemaNode, ScalarSchemaType, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, applyMacros, index_d_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, compareEnforce, createPrinter, defineMacro, extractStringsFromNodes, index_d_exports$1 as factory, findCircularSchemas, findSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 }
-export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParentOf, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
+export { type ArraySchemaNode, type ArrowFunctionNode, type BreakNode, type CodeNode, type ConstNode, type ContentNode, type DateOnlyTypeValue, type DateSchemaNode, type DateTimeTypeValue, type DateTypeOptions, type DatetimeSchemaNode, type DistributiveOmit, type EncodingNode, type Enforce, type EnumSchemaNode, type ExportNode, type FileNode, type FunctionNode, type GenericOperationNode, type HttpMethod, type HttpOperationNode, type ImportNode, type InlineLanguage, type InputMeta, type InputNode, type InputSecurityScheme, type InputServer, type IntersectionSchemaNode, type JSDocNode, type JsxNode, type Macro, type Node, type NodeKind, type NotSchemaNode, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, type ParameterLocation, type ParameterNode, type ParameterStyle, type ParserOptions, type PrimitiveSchemaType, type Printer, type PrinterFactoryOptions, type PrinterPartial, type PropertyNode, type RefSchemaNode, type RequestBodyNode, type ResponseNode, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, type UserFileNode, type Visitor, type VisitorContext, index_d_exports as ast, index_d_exports$1 as factory };
 //# sourceMappingURL=index.d.cts.map