@kubb/ast 4.33.5 → 4.35.0

package/dist/{visitor-D9_Eb8I1.d.ts → visitor-8N3AiSUr.d.ts}

@@ -87,20 +87,20 @@ type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter' | 'Re
 /**
  * Common base for all AST nodes.
  */
-interface BaseNode {
+type BaseNode = {
   kind: NodeKind;
-}
+};
 //#endregion
 //#region src/nodes/property.d.ts
 /**
  * A named property within an object schema.
  */
-interface PropertyNode extends BaseNode {
+type PropertyNode = BaseNode & {
   kind: 'Property';
   name: string;
   schema: SchemaNode;
   required: boolean;
-}
+};
 //#endregion
 //#region src/nodes/schema.d.ts
 type PrimitiveSchemaType = 'string' | 'number' | 'integer' | 'bigint' | 'boolean' | 'null' | 'any' | 'unknown' | 'void' | 'object' | 'array' | 'date';
@@ -114,7 +114,7 @@ type ScalarSchemaType = Exclude<SchemaType, 'object' | 'array' | 'tuple' | 'unio
 /**
  * Base fields shared by every schema variant. Does not include spec-specific fields.
  */
-interface SchemaNodeBase extends BaseNode {
+type SchemaNodeBase = BaseNode & {
   kind: 'Schema';
   /**
    * Named schema identifier (e.g. `"Pet"` from `#/components/schemas/Pet`). `undefined` for inline schemas.
@@ -137,11 +137,11 @@ interface SchemaNodeBase extends BaseNode {
    * Underlying primitive before format/semantic promotion (e.g. `'string'` for a `uuid` node).
    */
   primitive?: PrimitiveSchemaType;
-}
+};
 /**
  * Object schema with ordered property definitions.
  */
-interface ObjectSchemaNode extends SchemaNodeBase {
+type ObjectSchemaNode = SchemaNodeBase & {
   type: 'object';
   properties?: Array<PropertyNode>;
   /**
@@ -149,11 +149,11 @@ interface ObjectSchemaNode extends SchemaNodeBase {
    */
   additionalProperties?: SchemaNode | true;
   patternProperties?: Record<string, SchemaNode>;
-}
+};
 /**
  * Array or tuple schema.
  */
-interface ArraySchemaNode extends SchemaNodeBase {
+type ArraySchemaNode = SchemaNodeBase & {
   type: 'array' | 'tuple';
   items?: Array<SchemaNode>;
   /**
@@ -163,41 +163,41 @@ interface ArraySchemaNode extends SchemaNodeBase {
   min?: number;
   max?: number;
   unique?: boolean;
-}
+};
 /**
  * Shared base for union and intersection schemas.
  */
-interface CompositeSchemaNodeBase extends SchemaNodeBase {
+type CompositeSchemaNodeBase = SchemaNodeBase & {
   members?: Array<SchemaNode>;
-}
+};
 /**
  * Union schema (`oneOf` / `anyOf`).
  */
-interface UnionSchemaNode extends CompositeSchemaNodeBase {
+type UnionSchemaNode = CompositeSchemaNodeBase & {
   type: 'union';
   /**
    * Discriminator property from OAS `discriminator.propertyName`.
    */
   discriminatorPropertyName?: string;
-}
+};
 /**
  * Intersection schema (`allOf`).
  */
-interface IntersectionSchemaNode extends CompositeSchemaNodeBase {
+type IntersectionSchemaNode = CompositeSchemaNodeBase & {
   type: 'intersection';
-}
+};
 /**
  * A named enum variant.
  */
-interface EnumValueNode {
+type EnumValueNode = {
   name: string;
   value: string | number | boolean;
   format: 'string' | 'number' | 'boolean';
-}
+};
 /**
  * Enum schema.
  */
-interface EnumSchemaNode extends SchemaNodeBase {
+type EnumSchemaNode = SchemaNodeBase & {
   type: 'enum';
   /**
    * Enum member type. Generators should use const assertions for `'number'` / `'boolean'`.
@@ -211,11 +211,11 @@ interface EnumSchemaNode extends SchemaNodeBase {
    * Named variants (rich form). Takes priority over `enumValues` when present.
    */
   namedEnumValues?: Array<EnumValueNode>;
-}
+};
 /**
  * Ref schema — pointer to another schema definition.
  */
-interface RefSchemaNode extends SchemaNodeBase {
+type RefSchemaNode = SchemaNodeBase & {
   type: 'ref';
   name?: string;
   /**
@@ -226,11 +226,11 @@ interface RefSchemaNode extends SchemaNodeBase {
    * Pattern constraint propagated from a sibling `pattern` field next to the `$ref`.
    */
   pattern?: string;
-}
+};
 /**
  * Datetime schema.
  */
-interface DatetimeSchemaNode extends SchemaNodeBase {
+type DatetimeSchemaNode = SchemaNodeBase & {
   type: 'datetime';
   /**
    * Includes timezone offset (`dateType: 'stringOffset'`).
@@ -240,17 +240,17 @@ interface DatetimeSchemaNode extends SchemaNodeBase {
    * Local datetime without timezone (`dateType: 'stringLocal'`).
    */
   local?: boolean;
-}
+};
 /**
  * Base for `date` and `time` schemas.
  */
-interface TemporalSchemaNodeBase<T extends 'date' | 'time'> extends SchemaNodeBase {
+type TemporalSchemaNodeBase<T extends 'date' | 'time'> = SchemaNodeBase & {
   type: T;
   /**
    * Representation in generated code: native `Date` or plain string.
    */
   representation: 'date' | 'string';
-}
+};
 /**
  * Date schema.
  */
@@ -262,28 +262,28 @@ type TimeSchemaNode = TemporalSchemaNodeBase<'time'>;
 /**
  * String schema.
  */
-interface StringSchemaNode extends SchemaNodeBase {
+type StringSchemaNode = SchemaNodeBase & {
   type: 'string';
   min?: number;
   max?: number;
   pattern?: string;
-}
+};
 /**
  * Number, integer, or bigint schema.
  */
-interface NumberSchemaNode extends SchemaNodeBase {
+type NumberSchemaNode = SchemaNodeBase & {
   type: 'number' | 'integer' | 'bigint';
   min?: number;
   max?: number;
   exclusiveMinimum?: number;
   exclusiveMaximum?: number;
-}
+};
 /**
  * Schema for scalar types with no additional constraints.
  */
-interface ScalarSchemaNode extends SchemaNodeBase {
+type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType;
-}
+};
 /**
  * Maps each schema type string to its `SchemaNode` variant. Used by `narrowSchema`.
  */
@@ -322,13 +322,13 @@ type ParameterLocation = 'path' | 'query' | 'header' | 'cookie';
 /**
  * A single input parameter for an operation.
  */
-interface ParameterNode extends BaseNode {
+type ParameterNode = BaseNode & {
   kind: 'Parameter';
   name: string;
   in: ParameterLocation;
   schema: SchemaNode;
   required: boolean;
-}
+};
 //#endregion
 //#region src/nodes/http.d.ts
 /**
@@ -350,7 +350,7 @@ type MediaType = 'application/json' | 'application/xml' | 'application/x-www-for
 /**
  * A single response variant for an operation.
  */
-interface ResponseNode extends BaseNode {
+type ResponseNode = BaseNode & {
   kind: 'Response';
   /**
    * HTTP status code or `'default'` for a fallback response.
@@ -359,14 +359,14 @@ interface ResponseNode extends BaseNode {
   description?: string;
   schema?: SchemaNode;
   mediaType?: MediaType;
-}
+};
 //#endregion
 //#region src/nodes/operation.d.ts
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE';
 /**
  * A spec-agnostic representation of a single API operation.
  */
-interface OperationNode extends BaseNode {
+type OperationNode = BaseNode & {
   kind: 'Operation';
   /**
    * Unique operation identifier (maps to `operationId` in OAS).
@@ -384,17 +384,33 @@ interface OperationNode extends BaseNode {
    */
   requestBody?: SchemaNode;
   responses: Array<ResponseNode>;
-}
+};
 //#endregion
 //#region src/nodes/root.d.ts
+/**
+ * Format-agnostic metadata about the API document.
+ * Adapters populate whichever fields are available in their source format.
+ */
+type RootMeta = {
+  /** API title (from `info.title` in OAS/AsyncAPI). */title?: string; /** API version string (from `info.version` in OAS/AsyncAPI). */
+  version?: string;
+  /**
+   * Resolved base URL for the API.
+   * OAS: derived from `servers[serverIndex].url` with variable substitution.
+   * AsyncAPI: derived from `servers[serverIndex].url`.
+   * Drizzle / schema-only formats: not set.
+   */
+  baseURL?: string;
+};
 /**
  * Top-level container for all schemas and operations in a single API document.
  */
-interface RootNode extends BaseNode {
+type RootNode = BaseNode & {
   kind: 'Root';
   schemas: Array<SchemaNode>;
-  operations: Array<OperationNode>;
-}
+  operations: Array<OperationNode>; /** Format-agnostic document metadata populated by the adapter. */
+  meta?: RootMeta;
+};
 //#endregion
 //#region src/nodes/index.d.ts
 /**
@@ -438,6 +454,105 @@ declare function createParameter(props: Pick<ParameterNode, 'name' | 'in' | 'sch
  */
 declare function createResponse(props: Pick<ResponseNode, 'statusCode'> & Partial<Omit<ResponseNode, 'kind' | 'statusCode'>>): ResponseNode;
 //#endregion
+//#region src/printer.d.ts
+/**
+ * Handler context for `definePrinter` — mirrors `PluginContext` from `@kubb/core`.
+ * Available as `this` inside each node handler.
+ */
+type PrinterHandlerContext<TOutput, TOptions extends object> = {
+  /**
+   * Recursively print a nested `SchemaNode`.
+   */
+  print: (node: SchemaNode) => TOutput | null | undefined;
+  /**
+   * Options for this printer instance.
+   */
+  options: TOptions;
+};
+/**
+ * Handler for a specific `SchemaNode` variant identified by `SchemaType` key `T`.
+ * Use a regular function (not an arrow function) so that `this` is available.
+ */
+type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (this: PrinterHandlerContext<TOutput, TOptions>, node: SchemaNodeByType[T]) => TOutput | null | undefined;
+/**
+ * Shape of the type parameter passed to `definePrinter`.
+ * Mirrors `AdapterFactoryOptions` / `PluginFactoryOptions` from `@kubb/core`.
+ *
+ * - `TName` — unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions` — options passed to and stored on the printer
+ * - `TOutput` — the type emitted by `print` (typically `string`)
+ */
+type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown> = {
+  name: TName;
+  options: TOptions;
+  output: TOutput;
+};
+/**
+ * The object returned by calling a `definePrinter` instance.
+ * Mirrors the shape of `Adapter` from `@kubb/core`.
+ */
+type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
+  /**
+   * Unique identifier supplied at creation time.
+   */
+  name: T['name'];
+  /**
+   * Options for this printer instance.
+   */
+  options: T['options'];
+  /**
+   * Emits `TOutput` from a `SchemaNode`. Returns `null | undefined` when no handler matches.
+   */
+  print: (node: SchemaNode) => T['output'] | null | undefined;
+  /**
+   * Maps `print` over an array of `SchemaNode`s.
+   */
+  for: (nodes: Array<SchemaNode>) => Array<T['output'] | null | undefined>;
+};
+type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) => {
+  name: T['name'];
+  /**
+   * Options to store on the printer.
+   */
+  options: T['options'];
+  nodes: Partial<{ [K in SchemaType]: PrinterHandler<T['output'], T['options'], K> }>;
+};
+/**
+ * Creates a named printer factory. Mirrors the `definePlugin` / `defineAdapter` pattern
+ * from `@kubb/core` — wraps a builder to make options optional and separates raw options
+ * from resolved options.
+ *
+ * @example
+ * ```ts
+ * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, { strict: boolean }, string>
+ *
+ * export const zodPrinter = definePrinter<ZodPrinter>((options) => {
+ *   const { strict = true } = options
+ *   return {
+ *     name: 'zod',
+ *     options: { strict },
+ *     nodes: {
+ *       string(node) {
+ *         return `z.string()`
+ *       },
+ *       object(node) {
+ *         const props = node.properties
+ *           ?.map(p => `${p.name}: ${this.print(p)}`)
+ *           .join(', ') ?? ''
+ *         return `z.object({ ${props} })`
+ *       },
+ *     },
+ *   }
+ * })
+ *
+ * const printer = zodPrinter({ strict: false })
+ * printer.name            // 'zod'
+ * printer.options         // { strict: false }
+ * printer.print(node)     // 'z.string()'
+ * ```
+ */
+declare function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T>;
+//#endregion
 //#region src/refs.d.ts
 /**
  * Schema name to `SchemaNode` mapping.
@@ -462,43 +577,49 @@ declare function refMapToObject(refMap: RefMap): Record<string, SchemaNode>;
  */
 type VisitorOptions = {
   depth?: VisitorDepth;
+  /**
+   * Maximum number of sibling nodes visited concurrently inside `walk`.
+   * @default 30
+   */
+  concurrency?: number;
 };
 /**
  * Synchronous visitor for `transform` and `walk`.
  */
-interface Visitor {
+type Visitor = {
   root?(node: RootNode): void | RootNode;
   operation?(node: OperationNode): void | OperationNode;
   schema?(node: SchemaNode): void | SchemaNode;
   property?(node: PropertyNode): void | PropertyNode;
   parameter?(node: ParameterNode): void | ParameterNode;
   response?(node: ResponseNode): void | ResponseNode;
-}
+};
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
  */
-interface AsyncVisitor {
+type AsyncVisitor = {
   root?(node: RootNode): MaybePromise<void | RootNode>;
   operation?(node: OperationNode): MaybePromise<void | OperationNode>;
   schema?(node: SchemaNode): MaybePromise<void | SchemaNode>;
   property?(node: PropertyNode): MaybePromise<void | PropertyNode>;
   parameter?(node: ParameterNode): MaybePromise<void | ParameterNode>;
   response?(node: ResponseNode): MaybePromise<void | ResponseNode>;
-}
+};
 /**
  * Visitor for `collect`.
  */
-interface CollectVisitor<T> {
+type CollectVisitor<T> = {
   root?(node: RootNode): T | undefined;
   operation?(node: OperationNode): T | undefined;
   schema?(node: SchemaNode): T | undefined;
   property?(node: PropertyNode): T | undefined;
   parameter?(node: ParameterNode): T | undefined;
   response?(node: ResponseNode): T | undefined;
-}
+};
 /**
  * Depth-first traversal for side effects. Visitor return values are ignored.
+ * Sibling nodes at each level are visited concurrently up to `options.concurrency` (default: 30).
  */
 declare function walk(node: Node, visitor: AsyncVisitor, options?: VisitorOptions): Promise<void>;
 /**
@@ -516,5 +637,5 @@ declare function transform(node: Node, visitor: Visitor, options?: VisitorOption
  */
 declare function collect<T>(node: Node, visitor: CollectVisitor<T>, options?: VisitorOptions): Array<T>;
 //#endregion
-export { httpMethods as $, ComplexSchemaType as A, ScalarSchemaNode as B, ResponseNode as C, ParameterLocation as D, StatusCode as E, IntersectionSchemaNode as F, SpecialSchemaType as G, SchemaNode as H, NumberSchemaNode as I, UnionSchemaNode as J, StringSchemaNode as K, ObjectSchemaNode as L, DatetimeSchemaNode as M, EnumSchemaNode as N, ParameterNode as O, EnumValueNode as P, VisitorDepth as Q, PrimitiveSchemaType as R, OperationNode as S, MediaType as T, SchemaNodeByType as U, ScalarSchemaType as V, SchemaType as W, BaseNode as X, PropertyNode as Y, NodeKind as Z, createRoot as _, collect as a, RootNode as b, RefMap as c, resolveRef as d, mediaTypes as et, DistributiveOmit as f, createResponse as g, createProperty as h, VisitorOptions as i, DateSchemaNode as j, ArraySchemaNode as k, buildRefMap as l, createParameter as m, CollectVisitor as n, schemaTypes as nt, transform as o, createOperation as p, TimeSchemaNode as q, Visitor as r, walk as s, AsyncVisitor as t, nodeKinds as tt, refMapToObject as u, createSchema as v, HttpStatusCode as w, HttpMethod as x, Node as y, RefSchemaNode as z };
-//# sourceMappingURL=visitor-D9_Eb8I1.d.ts.map
+export { NodeKind as $, ParameterNode as A, PrimitiveSchemaType as B, HttpMethod as C, MediaType as D, HttpStatusCode as E, EnumSchemaNode as F, SchemaNodeByType as G, ScalarSchemaNode as H, EnumValueNode as I, StringSchemaNode as J, SchemaType as K, IntersectionSchemaNode as L, ComplexSchemaType as M, DateSchemaNode as N, StatusCode as O, DatetimeSchemaNode as P, BaseNode as Q, NumberSchemaNode as R, RootNode as S, ResponseNode as T, ScalarSchemaType as U, RefSchemaNode as V, SchemaNode as W, UnionSchemaNode as X, TimeSchemaNode as Y, PropertyNode as Z, createResponse as _, transform as a, Node as b, buildRefMap as c, Printer as d, VisitorDepth as et, definePrinter as f, createProperty as g, createParameter as h, collect as i, schemaTypes as it, ArraySchemaNode as j, ParameterLocation as k, refMapToObject as l, createOperation as m, CollectVisitor as n, mediaTypes as nt, walk as o, DistributiveOmit as p, SpecialSchemaType as q, Visitor as r, nodeKinds as rt, RefMap as s, AsyncVisitor as t, httpMethods as tt, resolveRef as u, createRoot as v, OperationNode as w, RootMeta as x, createSchema as y, ObjectSchemaNode as z };
+//# sourceMappingURL=visitor-8N3AiSUr.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "4.33.5",
+  "version": "4.35.0",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",

package/src/constants.ts

@@ -76,6 +76,11 @@ export const parameterLocations = {
   cookie: 'cookie',
 } as const satisfies Record<ParameterLocation, ParameterLocation>
 
+/**
+ * Default max concurrent visitor calls in `walk`.
+ */
+export const WALK_CONCURRENCY = 30
+
 /**
  * Fallback status code string for API spec responses.
  */

package/src/guards.ts

@@ -8,7 +8,7 @@ export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | un
 }
 
 function isKind<T extends Node>(kind: NodeKind) {
-  return (node: Node): node is T => node.kind === kind
+  return (node: unknown): node is T => (node as Node).kind === kind
 }
 
 /**

package/src/index.ts

@@ -1,5 +1,6 @@
 export { httpMethods, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
 export { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
 export { isOperationNode, isParameterNode, isPropertyNode, isResponseNode, isRootNode, isSchemaNode, narrowSchema } from './guards.ts'
+export { definePrinter } from './printer.ts'
 export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/nodes/base.ts

@@ -6,7 +6,7 @@ export type NodeKind = 'Root' | 'Operation' | 'Schema' | 'Property' | 'Parameter
 /**
  * Common base for all AST nodes.
  */
-export interface BaseNode {
+export type BaseNode = {
   kind: NodeKind
 }
 

package/src/nodes/index.ts

@@ -11,7 +11,7 @@ export type { HttpMethod, OperationNode } from './operation.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
 export type { PropertyNode } from './property.ts'
 export type { ResponseNode } from './response.ts'
-export type { RootNode } from './root.ts'
+export type { RootMeta, RootNode } from './root.ts'
 export type {
   ArraySchemaNode,
   ComplexSchemaType,

package/src/nodes/operation.ts

@@ -8,7 +8,7 @@ export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' |
 /**
  * A spec-agnostic representation of a single API operation.
  */
-export interface OperationNode extends BaseNode {
+export type OperationNode = BaseNode & {
   kind: 'Operation'
   /**
    * Unique operation identifier (maps to `operationId` in OAS).

package/src/nodes/parameter.ts

@@ -6,7 +6,7 @@ export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
 /**
  * A single input parameter for an operation.
  */
-export interface ParameterNode extends BaseNode {
+export type ParameterNode = BaseNode & {
   kind: 'Parameter'
   name: string
   in: ParameterLocation

package/src/nodes/property.ts

@@ -4,7 +4,7 @@ import type { SchemaNode } from './schema.ts'
 /**
  * A named property within an object schema.
  */
-export interface PropertyNode extends BaseNode {
+export type PropertyNode = BaseNode & {
   kind: 'Property'
   name: string
   schema: SchemaNode

package/src/nodes/response.ts

@@ -5,7 +5,7 @@ import type { SchemaNode } from './schema.ts'
 /**
  * A single response variant for an operation.
  */
-export interface ResponseNode extends BaseNode {
+export type ResponseNode = BaseNode & {
   kind: 'Response'
   /**
    * HTTP status code or `'default'` for a fallback response.

package/src/nodes/root.ts

@@ -2,11 +2,31 @@ import type { BaseNode } from './base.ts'
 import type { OperationNode } from './operation.ts'
 import type { SchemaNode } from './schema.ts'
 
+/**
+ * Format-agnostic metadata about the API document.
+ * Adapters populate whichever fields are available in their source format.
+ */
+export type RootMeta = {
+  /** API title (from `info.title` in OAS/AsyncAPI). */
+  title?: string
+  /** API version string (from `info.version` in OAS/AsyncAPI). */
+  version?: string
+  /**
+   * Resolved base URL for the API.
+   * OAS: derived from `servers[serverIndex].url` with variable substitution.
+   * AsyncAPI: derived from `servers[serverIndex].url`.
+   * Drizzle / schema-only formats: not set.
+   */
+  baseURL?: string
+}
+
 /**
  * Top-level container for all schemas and operations in a single API document.
  */
-export interface RootNode extends BaseNode {
+export type RootNode = BaseNode & {
   kind: 'Root'
   schemas: Array<SchemaNode>
   operations: Array<OperationNode>
+  /** Format-agnostic document metadata populated by the adapter. */
+  meta?: RootMeta
 }