@kubb/ast 4.33.5 → 4.35.0

package/src/nodes/schema.ts

@@ -20,7 +20,7 @@ export type ScalarSchemaType = Exclude<
 /**
  * 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.
@@ -48,7 +48,7 @@ interface SchemaNodeBase extends BaseNode {
 /**
  * Object schema with ordered property definitions.
  */
-export interface ObjectSchemaNode extends SchemaNodeBase {
+export type ObjectSchemaNode = SchemaNodeBase & {
   type: 'object'
   properties?: Array<PropertyNode>
   /**
@@ -61,7 +61,7 @@ export interface ObjectSchemaNode extends SchemaNodeBase {
 /**
  * Array or tuple schema.
  */
-export interface ArraySchemaNode extends SchemaNodeBase {
+export type ArraySchemaNode = SchemaNodeBase & {
   type: 'array' | 'tuple'
   items?: Array<SchemaNode>
   /**
@@ -76,14 +76,14 @@ export interface ArraySchemaNode extends SchemaNodeBase {
 /**
  * Shared base for union and intersection schemas.
  */
-interface CompositeSchemaNodeBase extends SchemaNodeBase {
+type CompositeSchemaNodeBase = SchemaNodeBase & {
   members?: Array<SchemaNode>
 }
 
 /**
  * Union schema (`oneOf` / `anyOf`).
  */
-export interface UnionSchemaNode extends CompositeSchemaNodeBase {
+export type UnionSchemaNode = CompositeSchemaNodeBase & {
   type: 'union'
   /**
    * Discriminator property from OAS `discriminator.propertyName`.
@@ -94,14 +94,14 @@ export interface UnionSchemaNode extends CompositeSchemaNodeBase {
 /**
  * Intersection schema (`allOf`).
  */
-export interface IntersectionSchemaNode extends CompositeSchemaNodeBase {
+export type IntersectionSchemaNode = CompositeSchemaNodeBase & {
   type: 'intersection'
 }
 
 /**
  * A named enum variant.
  */
-export interface EnumValueNode {
+export type EnumValueNode = {
   name: string
   value: string | number | boolean
   format: 'string' | 'number' | 'boolean'
@@ -110,7 +110,7 @@ export interface EnumValueNode {
 /**
  * Enum schema.
  */
-export interface EnumSchemaNode extends SchemaNodeBase {
+export type EnumSchemaNode = SchemaNodeBase & {
   type: 'enum'
   /**
    * Enum member type. Generators should use const assertions for `'number'` / `'boolean'`.
@@ -129,7 +129,7 @@ export interface EnumSchemaNode extends SchemaNodeBase {
 /**
  * Ref schema — pointer to another schema definition.
  */
-export interface RefSchemaNode extends SchemaNodeBase {
+export type RefSchemaNode = SchemaNodeBase & {
   type: 'ref'
   name?: string
   /**
@@ -145,7 +145,7 @@ export interface RefSchemaNode extends SchemaNodeBase {
 /**
  * Datetime schema.
  */
-export interface DatetimeSchemaNode extends SchemaNodeBase {
+export type DatetimeSchemaNode = SchemaNodeBase & {
   type: 'datetime'
   /**
    * Includes timezone offset (`dateType: 'stringOffset'`).
@@ -160,7 +160,7 @@ export interface DatetimeSchemaNode extends SchemaNodeBase {
 /**
  * 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.
@@ -181,7 +181,7 @@ export type TimeSchemaNode = TemporalSchemaNodeBase<'time'>
 /**
  * String schema.
  */
-export interface StringSchemaNode extends SchemaNodeBase {
+export type StringSchemaNode = SchemaNodeBase & {
   type: 'string'
   min?: number
   max?: number
@@ -191,7 +191,7 @@ export interface StringSchemaNode extends SchemaNodeBase {
 /**
  * Number, integer, or bigint schema.
  */
-export interface NumberSchemaNode extends SchemaNodeBase {
+export type NumberSchemaNode = SchemaNodeBase & {
   type: 'number' | 'integer' | 'bigint'
   min?: number
   max?: number
@@ -202,7 +202,7 @@ export interface NumberSchemaNode extends SchemaNodeBase {
 /**
  * Schema for scalar types with no additional constraints.
  */
-export interface ScalarSchemaNode extends SchemaNodeBase {
+export type ScalarSchemaNode = SchemaNodeBase & {
   type: ScalarSchemaType
 }
 

package/src/printer.ts

@@ -0,0 +1,127 @@
+import type { SchemaNode, SchemaNodeByType, SchemaType } from './nodes/index.ts'
+
+/**
+ * Handler context for `definePrinter` — mirrors `PluginContext` from `@kubb/core`.
+ * Available as `this` inside each node handler.
+ */
+export 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.
+ */
+export 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`)
+ */
+export 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`.
+ */
+export 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()'
+ * ```
+ */
+export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOptions>(build: PrinterBuilder<T>): (options?: T['options']) => Printer<T> {
+  return (options) => {
+    const { name, options: resolvedOptions, nodes } = build(options ?? ({} as T['options']))
+
+    function print(node: SchemaNode): T['output'] | null | undefined {
+      const type = node.type as SchemaType
+
+      const handler = nodes[type]
+      if (handler) {
+        const context: PrinterHandlerContext<T['output'], T['options']> = { print, options: resolvedOptions }
+        return (handler as PrinterHandler<T['output'], T['options']>).call(context, node as SchemaNodeByType[SchemaType])
+      }
+
+      return undefined
+    }
+
+    return { name, options: resolvedOptions, print, for: (nodes) => nodes.map(print) }
+  }
+}

package/src/types.ts

@@ -23,6 +23,7 @@ export type {
   PropertyNode,
   RefSchemaNode,
   ResponseNode,
+  RootMeta,
   RootNode,
   ScalarSchemaNode,
   ScalarSchemaType,
@@ -35,5 +36,6 @@ export type {
   TimeSchemaNode,
   UnionSchemaNode,
 } from './nodes/index.ts'
+export type { Printer } from './printer.ts'
 export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectVisitor, Visitor, VisitorOptions } from './visitor.ts'
+export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'

package/src/visitor.ts

@@ -1,18 +1,51 @@
 import type { VisitorDepth } from './constants.ts'
-import { visitorDepths } from './constants.ts'
+import { visitorDepths, WALK_CONCURRENCY } from './constants.ts'
 import type { Node, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
 
+function createLimit(concurrency: number) {
+  let active = 0
+  const queue: Array<() => void> = []
+
+  function next() {
+    if (active < concurrency && queue.length > 0) {
+      active++
+      queue.shift()!()
+    }
+  }
+
+  return function limit<T>(fn: () => Promise<T> | T): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      queue.push(() => {
+        Promise.resolve(fn())
+          .then(resolve, reject)
+          .finally(() => {
+            active--
+            next()
+          })
+      })
+      next()
+    })
+  }
+}
+
+type LimitFn = ReturnType<typeof createLimit>
+
 /**
  * Shared options for `walk`, `transform`, and `collect`.
  */
 export type VisitorOptions = {
   depth?: VisitorDepth
+  /**
+   * Maximum number of sibling nodes visited concurrently inside `walk`.
+   * @default 30
+   */
+  concurrency?: number
 }
 
 /**
  * Synchronous visitor for `transform` and `walk`.
  */
-export interface Visitor {
+export type Visitor = {
   root?(node: RootNode): void | RootNode
   operation?(node: OperationNode): void | OperationNode
   schema?(node: SchemaNode): void | SchemaNode
@@ -26,7 +59,7 @@ type MaybePromise<T> = T | Promise<T>
 /**
  * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
  */
-export interface AsyncVisitor {
+export type AsyncVisitor = {
   root?(node: RootNode): MaybePromise<void | RootNode>
   operation?(node: OperationNode): MaybePromise<void | OperationNode>
   schema?(node: SchemaNode): MaybePromise<void | SchemaNode>
@@ -38,7 +71,7 @@ export interface AsyncVisitor {
 /**
  * Visitor for `collect`.
  */
-export interface CollectVisitor<T> {
+export type CollectVisitor<T> = {
   root?(node: RootNode): T | undefined
   operation?(node: OperationNode): T | undefined
   schema?(node: SchemaNode): T | undefined
@@ -78,34 +111,38 @@ function getChildren(node: Node, recurse: boolean): Array<Node> {
 
 /**
  * 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).
  */
 export async function walk(node: Node, visitor: AsyncVisitor, options: VisitorOptions = {}): Promise<void> {
   const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep
+  const limit = createLimit(options.concurrency ?? WALK_CONCURRENCY)
+  return _walk(node, visitor, recurse, limit)
+}
 
+async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn): Promise<void> {
   switch (node.kind) {
     case 'Root':
-      await visitor.root?.(node)
+      await limit(() => visitor.root?.(node))
       break
     case 'Operation':
-      await visitor.operation?.(node)
+      await limit(() => visitor.operation?.(node))
       break
     case 'Schema':
-      await visitor.schema?.(node)
+      await limit(() => visitor.schema?.(node))
       break
     case 'Property':
-      await visitor.property?.(node)
+      await limit(() => visitor.property?.(node))
       break
     case 'Parameter':
-      await visitor.parameter?.(node)
+      await limit(() => visitor.parameter?.(node))
       break
     case 'Response':
-      await visitor.response?.(node)
+      await limit(() => visitor.response?.(node))
       break
   }
 
-  for (const child of getChildren(node, recurse)) {
-    await walk(child, visitor, options)
-  }
+  const children = getChildren(node, recurse)
+  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit)))
 }
 
 /**