@kubb/ast 4.36.1 → 5.0.0-alpha.10

package/src/printer.ts

@@ -2,11 +2,12 @@ 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.
+ * Available as `this` inside each node handler and the optional root-level `print`.
+ * `this.print` always dispatches to the `nodes` handlers (node-level printer).
  */
 export type PrinterHandlerContext<TOutput, TOptions extends object> = {
   /**
-   * Recursively print a nested `SchemaNode`.
+   * Recursively print a nested `SchemaNode` using the node-level handlers.
    */
   print: (node: SchemaNode) => TOutput | null | undefined
   /**
@@ -28,19 +29,20 @@ export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaTyp
  * 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`)
+ * - `TName`        — unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions`     — options passed to and stored on the printer
+ * - `TOutput`      — the type emitted by node handlers
+ * - `TPrintOutput` — the type emitted by the public `print` override (defaults to `TOutput`)
  */
-export type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown> = {
+export type PrinterFactoryOptions<TName extends string = string, TOptions extends object = object, TOutput = unknown, TPrintOutput = TOutput> = {
   name: TName
   options: TOptions
   output: TOutput
+  printOutput: TPrintOutput
 }
 
 /**
  * The object returned by calling a `definePrinter` instance.
- * Mirrors the shape of `Adapter` from `@kubb/core`.
  */
 export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
   /**
@@ -52,15 +54,18 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    */
   options: T['options']
   /**
-   * Emits `TOutput` from a `SchemaNode`. Returns `null | undefined` when no handler matches.
+   * 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['output'] | null | undefined
-  /**
-   * Maps `print` over an array of `SchemaNode`s.
-   */
-  for: (nodes: Array<SchemaNode>) => Array<T['output'] | null | undefined>
+  print: (node: SchemaNode) => T['printOutput'] | null | undefined
 }
 
+/**
+ * Builder function passed to `definePrinter`. Receives the resolved options and returns the
+ * printer configuration: a unique `name`, the stored `options`, node-level `nodes` handlers,
+ * and an optional root-level `print` override.
+ */
 type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) => {
   name: T['name']
   /**
@@ -70,60 +75,114 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
   nodes: Partial<{
     [K in SchemaType]: PrinterHandler<T['output'], T['options'], K>
   }>
+  /**
+   * Optional root-level print override. When provided, becomes the public `printer.print`.
+   * `this.print(node)` inside this function calls the node-level dispatcher (`nodes` handlers),
+   * not the override itself — so recursion is safe.
+   */
+  print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null | undefined
 }
 
 /**
- * Creates a named printer factory. Mirrors the `definePlugin` / `defineAdapter` pattern
+ * Creates a named printer factory. Mirrors the `createPlugin` / `createAdapter` pattern
  * from `@kubb/core` — wraps a builder to make options optional and separates raw options
  * from resolved options.
  *
- * @example
+ * The builder receives resolved options and returns:
+ * - `name` — a unique identifier for the printer
+ * - `options` — options stored on the returned printer instance
+ * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
+ * - `print` _(optional)_ — a root-level override that becomes the public `printer.print`.
+ *   Inside it, `this.print(node)` still dispatches to the `nodes` map — safe recursion, no infinite loop.
+ *
+ * When no `print` override is provided, `printer.print` is the node-level dispatcher directly.
+ *
+ * @example Basic usage — Zod schema printer
  * ```ts
- * type ZodPrinter = PrinterFactoryOptions<'zod', { strict?: boolean }, { strict: boolean }, string>
+ * type ZodPrinter = PrinterFactoryOptions<'zod', { 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} })`
- *       },
+ * export const zodPrinter = definePrinter<ZodPrinter>((options) => ({
+ *   name: 'zod',
+ *   options: { strict: options.strict ?? true },
+ *   nodes: {
+ *     string: () => 'z.string()',
+ *     object(node) {
+ *       const props = node.properties.map(p => `${p.name}: ${this.print(p.schema)}`).join(', ')
+ *       return `z.object({ ${props} })`
  *     },
- *   }
- * })
+ *   },
+ * }))
+ * ```
  *
- * const printer = zodPrinter({ strict: false })
- * printer.name            // 'zod'
- * printer.options         // { strict: false }
- * printer.print(node)     // 'z.string()'
+ * @example With a root-level `print` override to wrap output in a full declaration
+ * ```ts
+ * type TsPrinter = PrinterFactoryOptions<'ts', { typeName?: string }, ts.TypeNode, ts.Node>
+ *
+ * export const printerTs = definePrinter<TsPrinter>((options) => ({
+ *   name: 'ts',
+ *   options,
+ *   nodes: { string: () => factory.keywordTypeNodes.string },
+ *   print(node) {
+ *     const type = this.print(node) // calls the node-level dispatcher
+ *     if (!type || !this.options.typeName) return type
+ *     return factory.createTypeAliasDeclaration(this.options.typeName, type)
+ *   },
+ * }))
  * ```
  */
 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']))
+  return createPrinterFactory<SchemaNode, SchemaType, SchemaNodeByType>((node) => node.type)(build) as (options?: T['options']) => Printer<T>
+}
 
-    const context: PrinterHandlerContext<T['output'], T['options']> = {
-      options: resolvedOptions,
-      print: (node: SchemaNode) => {
-        const type = node.type as SchemaType
-        const handler = nodes[type]
-        return handler ? (handler as PrinterHandler<T['output'], T['options']>).call(context, node as SchemaNodeByType[SchemaType]) : undefined
-      },
-    }
+/**
+ * Generic printer factory. Extracts the core dispatch + context logic so it can be reused
+ * for any node type — not just `SchemaNode`. `definePrinter` is built on top of this.
+ *
+ * @param getKey — derives the handler-map key from a node. Return `undefined` to skip.
+ *
+ * @example
+ * ```ts
+ * export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
+ *   (node) => kindToHandlerKey[node.kind],
+ * )
+ * ```
+ */
+export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined) {
+  return function <T extends PrinterFactoryOptions>(
+    build: (options: T['options']) => {
+      name: T['name']
+      options: T['options']
+      nodes: Partial<{
+        [K in TKey]: (
+          this: { print: (node: TNode) => T['output'] | null | undefined; options: T['options'] },
+          node: TNodeByKey[K],
+        ) => T['output'] | null | undefined
+      }>
+      print?: (this: { print: (node: TNode) => T['output'] | null | undefined; options: T['options'] }, node: TNode) => T['printOutput'] | null | undefined
+    },
+  ): (options?: T['options']) => { name: T['name']; options: T['options']; print: (node: TNode) => T['printOutput'] | null | undefined } {
+    return (options) => {
+      const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? ({} as T['options']))
+
+      const context = {
+        options: resolvedOptions,
+        print: (node: TNode): T['output'] | null | undefined => {
+          const key = getKey(node)
+          if (key === undefined) return undefined
+
+          const handler = nodes[key]
+
+          if (!handler) return undefined
+
+          return (handler as (this: typeof context, node: TNode) => T['output'] | null | undefined).call(context, node)
+        },
+      }
 
-    return {
-      name,
-      options: resolvedOptions,
-      print: context.print,
-      for: (nodes) => nodes.map(context.print),
+      return {
+        name,
+        options: resolvedOptions,
+        print: (printOverride ? printOverride.bind(context) : context.print) as (node: TNode) => T['printOutput'] | null | undefined,
+      }
     }
   }
 }

package/src/types.ts

@@ -8,6 +8,10 @@ export type {
   DatetimeSchemaNode,
   EnumSchemaNode,
   EnumValueNode,
+  FunctionNode,
+  FunctionNodeType,
+  FunctionParameterNode,
+  FunctionParametersNode,
   HttpMethod,
   HttpStatusCode,
   IntersectionSchemaNode,
@@ -15,6 +19,7 @@ export type {
   Node,
   NodeKind,
   NumberSchemaNode,
+  ObjectBindingParameterNode,
   ObjectSchemaNode,
   OperationNode,
   ParameterLocation,
@@ -35,7 +40,8 @@ export type {
   StringSchemaNode,
   TimeSchemaNode,
   UnionSchemaNode,
+  UrlSchemaNode,
 } from './nodes/index.ts'
-export type { Printer, PrinterFactoryOptions, PrinterHandler, PrinterHandlerContext } from './printer.ts'
+export type { Printer, PrinterFactoryOptions } from './printer.ts'
 export type { RefMap } from './refs.ts'
 export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'

package/src/utils.ts

@@ -0,0 +1,48 @@
+import { camelCase, isValidVarName } from '@internals/utils'
+
+import { narrowSchema } from './guards.ts'
+import type { ParameterNode, SchemaNode } from './nodes/index.ts'
+import type { SchemaType } from './nodes/schema.ts'
+
+const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
+
+/**
+ * Returns `true` when a schema node will be represented as a plain string in generated code.
+ *
+ * - `string`, `uuid`, `email`, `url`, `datetime` are always plain strings.
+ * - `date` and `time` are plain strings when their `representation` is `'string'` rather than `'date'`.
+ */
+export function isPlainStringType(node: SchemaNode): boolean {
+  if (plainStringTypes.has(node.type)) {
+    return true
+  }
+
+  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')
+  if (temporal) {
+    return temporal.representation !== 'date'
+  }
+
+  return false
+}
+
+/**
+ * Transforms the `name` field of each parameter node according to the given casing strategy.
+ *
+ * The original `params` array is never mutated — a new array of cloned nodes is returned.
+ * When no `casing` is provided the original array is returned as-is.
+ *
+ * Use this before passing parameters to schema builders so that property keys
+ * in the generated output match the desired casing while the original
+ * `OperationNode.parameters` array remains untouched for other consumers.
+ */
+export function applyParamsCasing(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
+  if (!casing) {
+    return params
+  }
+
+  return params.map((param) => {
+    const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
+
+    return { ...param, name: transformed }
+  })
+}

package/src/visitor.ts

@@ -2,6 +2,10 @@ import type { VisitorDepth } from './constants.ts'
 import { visitorDepths, WALK_CONCURRENCY } from './constants.ts'
 import type { Node, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
 
+/**
+ * Creates a concurrency-limiting wrapper. At most `concurrency` promises may be
+ * in-flight simultaneously; additional calls are queued and dispatched as slots free.
+ */
 function createLimit(concurrency: number) {
   let active = 0
   const queue: Array<() => void> = []
@@ -81,7 +85,10 @@ export type CollectVisitor<T> = {
 }
 
 /**
- * Traversable children of `node`, respecting `recurse` for schema nodes.
+ * Returns the immediate traversable children of `node`.
+ *
+ * For `Schema` nodes, children (properties, items, members) are only included
+ * when `recurse` is `true`; shallow traversal omits them entirely.
  */
 function getChildren(node: Node, recurse: boolean): Array<Node> {
   switch (node.kind) {
@@ -106,6 +113,10 @@ function getChildren(node: Node, recurse: boolean): Array<Node> {
       return [node.schema]
     case 'Response':
       return node.schema ? [node.schema] : []
+    case 'FunctionParameter':
+    case 'ObjectBindingParameter':
+    case 'FunctionParameters':
+      return []
   }
 }
 
@@ -119,6 +130,9 @@ export async function walk(node: Node, visitor: AsyncVisitor, options: VisitorOp
   return _walk(node, visitor, recurse, limit)
 }
 
+/**
+ * Internal recursive walk implementation — calls visitor then recurses into children.
+ */
 async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn): Promise<void> {
   switch (node.kind) {
     case 'Root':
@@ -139,6 +153,10 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
     case 'Response':
       await limit(() => visitor.response?.(node))
       break
+    case 'FunctionParameter':
+    case 'ObjectBindingParameter':
+    case 'FunctionParameters':
+      break
   }
 
   const children = getChildren(node, recurse)
@@ -221,9 +239,13 @@ export function transform(node: Node, visitor: Visitor, options: VisitorOptions
 
       return {
         ...response,
-        schema: response.schema ? transform(response.schema, visitor, options) : undefined,
+        schema: transform(response.schema, visitor, options),
       }
     }
+    case 'FunctionParameter':
+    case 'ObjectBindingParameter':
+    case 'FunctionParameters':
+      return node
   }
 }
 
@@ -254,6 +276,10 @@ export function collect<T>(node: Node, visitor: CollectVisitor<T>, options: Visi
     case 'Response':
       v = visitor.response?.(node)
       break
+    case 'FunctionParameter':
+    case 'ObjectBindingParameter':
+    case 'FunctionParameters':
+      break
   }
   if (v !== undefined) results.push(v)