@kubb/ast 5.0.0-beta.21 → 5.0.0-beta.23

package/dist/index.d.ts

@@ -251,21 +251,21 @@ type ConstNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean;
+  export?: boolean | null;
   /**
    * Optional explicit type annotation.
    * @example 'Pet'
    */
-  type?: string;
+  type?: string | null;
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode;
+  JSDoc?: JSDocNode | null;
   /**
    * Whether to append `as const` to the declaration.
    * @default false
    */
-  asConst?: boolean;
+  asConst?: boolean | null;
   /**
    * Child nodes representing the value of the constant (children of the `Const` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -297,11 +297,11 @@ type TypeNode = BaseNode & {
    * Whether the declaration should be exported.
    * @default false
    */
-  export?: boolean;
+  export?: boolean | null;
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode;
+  JSDoc?: JSDocNode | null;
   /**
    * Child nodes representing the type body (children of the `Type` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -338,35 +338,35 @@ type FunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean;
+  default?: boolean | null;
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string;
+  params?: string | null;
   /**
    * Whether the function should be exported.
    * @default false
    */
-  export?: boolean;
+  export?: boolean | null;
   /**
    * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean;
+  async?: boolean | null;
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[];
+  generics?: string | string[] | null;
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string;
+  returnType?: string | null;
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode;
+  JSDoc?: JSDocNode | null;
   /**
    * Child nodes representing the function body (children of the `Function` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -398,40 +398,40 @@ type ArrowFunctionNode = BaseNode & {
    * Whether the function is a default export.
    * @default false
    */
-  default?: boolean;
+  default?: boolean | null;
   /**
    * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
    */
-  params?: string;
+  params?: string | null;
   /**
    * Whether the arrow function should be exported.
    * @default false
    */
-  export?: boolean;
+  export?: boolean | null;
   /**
    * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
    * @default false
    */
-  async?: boolean;
+  async?: boolean | null;
   /**
    * TypeScript generic type parameters.
    * @example ['T', 'U extends string']
    */
-  generics?: string | string[];
+  generics?: string | string[] | null;
   /**
    * Return type annotation.
    * @example 'Pet'
    */
-  returnType?: string;
+  returnType?: string | null;
   /**
    * JSDoc documentation metadata.
    */
-  JSDoc?: JSDocNode;
+  JSDoc?: JSDocNode | null;
   /**
    * Render the arrow function body as a single-line expression.
    * @default false
    */
-  singleLine?: boolean;
+  singleLine?: boolean | null;
   /**
    * Child nodes representing the function body (children of the `Function.Arrow` component).
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -561,18 +561,18 @@ type ImportNode = BaseNode & {
    * - `false` generates `import { Type } from './path'`
    * @default false
    */
-  isTypeOnly?: boolean;
+  isTypeOnly?: boolean | null;
   /**
    * Import entire module as namespace.
    * - `true` generates `import * as Name from './path'`
    * - `false` generates standard import
    * @default false
    */
-  isNameSpace?: boolean;
+  isNameSpace?: boolean | null;
   /**
    * When set, the import path is resolved relative to this root.
    */
-  root?: string;
+  root?: string | null;
 };
 /**
  * Represents a language-agnostic export/public API declaration.
@@ -604,7 +604,7 @@ type ExportNode = BaseNode & {
    * @example ['useState']
    * @example 'React'
    */
-  name?: string | Array<string>;
+  name?: string | Array<string> | null;
   /**
    * Path for the export.
    * @example '@kubb/core'
@@ -616,14 +616,14 @@ type ExportNode = BaseNode & {
    * - `false` generates `export { Type } from './path'`
    * @default false
    */
-  isTypeOnly?: boolean;
+  isTypeOnly?: boolean | null;
   /**
    * Export as an aliased namespace.
    * - `true` generates `export * as aliasName from './path'`
    * - `false` generates a standard export
    * @default false
    */
-  asAlias?: boolean;
+  asAlias?: boolean | null;
 };
 /**
  * Represents a fragment of source code within a file.
@@ -643,22 +643,22 @@ type SourceNode = BaseNode & {
   /**
    * Optional name identifying this source (used for deduplication and barrel generation).
    */
-  name?: string;
+  name?: string | null;
   /**
    * Mark this source as a type-only export.
    * @default false
    */
-  isTypeOnly?: boolean;
+  isTypeOnly?: boolean | null;
   /**
    * Include `export` keyword in the generated source.
    * @default false
    */
-  isExportable?: boolean;
+  isExportable?: boolean | null;
   /**
    * Include this source in barrel/index file generation.
    * @default false
    */
-  isIndexable?: boolean;
+  isIndexable?: boolean | null;
   /**
    * Structured child nodes representing the content of this source fragment, in DOM order.
    * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
@@ -688,8 +688,8 @@ type SourceNode = BaseNode & {
 type FileNode<TMeta extends object = object> = BaseNode & {
   kind: 'File';
   /**
-   * Unique identifier derived from a SHA256 hash of the file path.
-   * @default hash
+   * Unique identifier derived from a SHA256 hash of the file path. Computed
+   * by `createFile`; callers do not need to provide it.
    */
   id: string;
   /**
@@ -729,12 +729,14 @@ type FileNode<TMeta extends object = object> = BaseNode & {
   meta?: TMeta;
   /**
    * Optional banner prepended to the generated file content.
+   * Accepts `null` so `resolver.resolveBanner()` results can be passed directly.
    */
-  banner?: string;
+  banner?: string | null;
   /**
    * Optional footer appended to the generated file content.
+   * Accepts `null` so `resolver.resolveFooter()` results can be passed directly.
    */
-  footer?: string;
+  footer?: string | null;
 };
 //#endregion
 //#region src/nodes/function.d.ts
@@ -1980,15 +1982,25 @@ type Node = InputNode | OutputNode | OperationNode | SchemaNode | PropertyNode |
  */
 type ParserOptions = {
   /**
-   * How `format: 'date-time'` schemas are represented. `false` falls through to a plain string.
+   * How `format: 'date-time'` schemas are represented downstream.
+   * - `false` falls through to a plain `string` (no validation).
+   * - `'string'` emits a datetime string node.
+   * - `'stringOffset'` emits a datetime node with timezone offset.
+   * - `'stringLocal'` emits a local datetime node.
+   * - `'date'` emits a `date` node (JavaScript `Date` object).
    */
   dateType: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
   /**
-   * Whether `type: 'integer'` and `format: 'int64'` produce `number` or `bigint` nodes.
+   * How `type: 'integer'` (and `format: 'int64'`) maps to TypeScript.
+   * - `'number'` fits most JSON APIs; loses precision above `Number.MAX_SAFE_INTEGER`.
+   * - `'bigint'` is exact for 64-bit IDs, but does not round-trip through JSON.
+   *
+   * @default 'number'
    */
   integerType?: 'number' | 'bigint';
   /**
-   * AST type used when no schema type can be inferred.
+   * AST type used when a schema's type cannot be inferred from the spec
+   * (`additionalProperties: true`, missing `type`, ...).
    */
   unknownType: 'any' | 'unknown' | 'void';
   /**
@@ -1996,7 +2008,8 @@ type ParserOptions = {
    */
   emptySchemaType: 'any' | 'unknown' | 'void';
   /**
-   * Suffix appended to derived enum names when building property schema names.
+   * Suffix appended to derived enum names when Kubb has to invent one
+   * (typically for inline enums on object properties).
    */
   enumSuffix: 'enum' | (string & {});
 };
@@ -2117,10 +2130,13 @@ type InferSchema<TSchema extends object, TDateType extends ParserOptions['dateTy
 //#endregion
 //#region src/factory.d.ts
 /**
- * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+ * Updates a schema's `optional` and `nullish` flags from a parent's `required`
+ * value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
+ * object properties combine "required" and "nullable" into a single AST.
  *
- * - `optional` is set for non-required, non-nullable schemas.
- * - `nullish` is set for non-required, nullable schemas.
+ * - Non-required + non-nullable → `optional: true`.
+ * - Non-required + nullable → `nullish: true`.
+ * - Required → both flags cleared.
  */
 declare function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode;
 /**
@@ -2845,22 +2861,27 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
   print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null;
 };
 /**
- * Creates a schema printer factory.
- *
- * This function wraps a builder and makes options optional at call sites.
+ * Defines a schema printer: a function that takes a `SchemaNode` and emits
+ * code in your target language. Each plugin that produces code from schemas
+ * (TypeScript types, Zod schemas, Faker factories) ships a printer built
+ * with this helper.
  *
  * 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)_ — top-level override exposed as `printer.print`
- *   - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
- *   - This keeps recursion safe and avoids self-calls
  *
- * When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
+ * - `name` — unique identifier for the printer.
+ * - `options` — stored on the returned printer instance.
+ * - `nodes` — map of `SchemaType` → handler. Handlers return the rendered
+ *   output (a string, a TypeScript AST node, ...) for that schema type.
+ * - `print` (optional) — top-level override exposed as `printer.print`.
+ *   Use `this.transform(node)` inside it to dispatch to `nodes` recursively.
+ *
+ * Without a `print` override, `printer.print` falls back to `printer.transform`
+ * (the node-level dispatcher).
  *
- * @example Basic usage — Zod schema printer
+ * @example Tiny Zod printer
  * ```ts
+ * import { definePrinter, type PrinterFactoryOptions } from '@kubb/ast'
+ *
  * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
  *
  * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
@@ -2869,7 +2890,9 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
  *   nodes: {
  *     string: () => 'z.string()',
  *     object(node) {
- *       const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
+ *       const props = node.properties
+ *         .map((p) => `${p.name}: ${this.transform(p.schema)}`)
+ *         .join(', ')
  *       return `z.object({ ${props} })`
  *     },
  *   },
@@ -3047,25 +3070,40 @@ type VisitorContext<T extends Node = Node> = {
   parent?: ParentOf<T>;
 };
 /**
- * Synchronous visitor used by `transform`.
+ * Synchronous visitor consumed by `transform`. Each optional callback runs
+ * for the matching node type. Return a new node to replace it, or `undefined`
+ * to leave it untouched.
  *
- * @example
+ * Plugins typically expose `transformer` so users can supply a `Visitor` that
+ * rewrites operation IDs, drops descriptions, or otherwise tweaks the AST
+ * before printing.
+ *
+ * @example Prefix every operationId
  * ```ts
  * const visitor: Visitor = {
  *   operation(node) {
- *     return { ...node, operationId: `x_${node.operationId}` }
+ *     return { ...node, operationId: `api_${node.operationId}` }
+ *   },
+ * }
+ * ```
+ *
+ * @example Strip schema descriptions
+ * ```ts
+ * const visitor: Visitor = {
+ *   schema(node) {
+ *     return { ...node, description: undefined }
  *   },
  * }
  * ```
  */
 type Visitor = {
-  input?(node: InputNode, context: VisitorContext<InputNode>): void | InputNode;
-  output?(node: OutputNode, context: VisitorContext<OutputNode>): void | OutputNode;
-  operation?(node: OperationNode, context: VisitorContext<OperationNode>): void | OperationNode;
-  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): void | SchemaNode;
-  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): void | PropertyNode;
-  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): void | ParameterNode;
-  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): void | ResponseNode;
+  input?(node: InputNode, context: VisitorContext<InputNode>): undefined | null | InputNode;
+  output?(node: OutputNode, context: VisitorContext<OutputNode>): undefined | null | OutputNode;
+  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;
 };
 /**
  * Utility type for values that can be returned directly or asynchronously.
@@ -3084,13 +3122,13 @@ type MaybePromise<T> = T | Promise<T>;
  * ```
  */
 type AsyncVisitor = {
-  input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<void | InputNode>;
-  output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<void | OutputNode>;
-  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<void | OperationNode>;
-  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<void | SchemaNode>;
-  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<void | PropertyNode>;
-  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<void | ParameterNode>;
-  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<void | ResponseNode>;
+  input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<undefined | null | InputNode>;
+  output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<undefined | null | OutputNode>;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<undefined | null | OperationNode>;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<undefined | null | SchemaNode>;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<undefined | null | PropertyNode>;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<undefined | null | ParameterNode>;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<undefined | null | ResponseNode>;
 };
 /**
  * Visitor used by `collect`.
@@ -3178,11 +3216,14 @@ type CollectOptions<T> = CollectVisitor<T> & {
   parent?: 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: `WALK_CONCURRENCY`).
+ * Async depth-first traversal for side effects. Visitor return values are
+ * ignored. Use `transform` when you want to rewrite nodes.
  *
- * @example
+ * Sibling nodes at each depth run concurrently up to `options.concurrency`
+ * (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor
+ * work; lower values reduce memory pressure.
+ *
+ * @example Log every operation
  * ```ts
  * await walk(root, {
  *   operation(node) {
@@ -3191,20 +3232,20 @@ type CollectOptions<T> = CollectVisitor<T> & {
  * })
  * ```
  *
- * @example
+ * @example Only visit the root node
  * ```ts
- * // Visit only the current node
- * await walk(root, { depth: 'shallow', root: () => {} })
+ * await walk(root, { depth: 'shallow', input: () => {} })
  * ```
  */
 declare function walk(node: Node, options: WalkOptions): Promise<void>;
 /**
- * Runs a depth-first immutable transform.
+ * Synchronous depth-first transform. Each visitor callback gets a chance to
+ * return a replacement node; `undefined` keeps the original.
  *
- * If a visitor returns a node, it replaces the current node.
- * If it returns `undefined`, the current node stays the same.
+ * The transform is immutable. The original tree is not mutated; a new tree
+ * is returned. Use `depth: 'shallow'` to skip recursion into children.
  *
- * @example
+ * @example Prefix every operationId
  * ```ts
  * const next = transform(root, {
  *   operation(node) {
@@ -3213,10 +3254,12 @@ declare function walk(node: Node, options: WalkOptions): Promise<void>;
  * })
  * ```
  *
- * @example
+ * @example Replace only the root node
  * ```ts
- * // Shallow mode: only transform the input node
- * const next = transform(root, { depth: 'shallow', root: (node) => node })
+ * const next = transform(root, {
+ *   depth: 'shallow',
+ *   input: (node) => ({ ...node, meta: { ...node.meta, title: 'Rewritten' } }),
+ * })
  * ```
  */
 declare function transform(node: InputNode, options: TransformOptions): InputNode;
@@ -3228,26 +3271,35 @@ declare function transform(node: ParameterNode, options: TransformOptions): Para
 declare function transform(node: ResponseNode, options: TransformOptions): ResponseNode;
 declare function transform(node: Node, options: TransformOptions): Node;
 /**
- * Runs a depth-first synchronous collection pass.
- *
- * Non-`null` values returned by visitor callbacks are appended to the result.
+ * Lazy depth-first collection pass. Yields every non-null value returned by
+ * the visitor callbacks. Use `collect` for the eager array form.
  *
- * @example
+ * @example Collect every operationId
  * ```ts
- * const ids = collect(root, {
+ * const ids: string[] = []
+ * for (const id of collectLazy<string>(root, {
  *   operation(node) {
  *     return node.operationId
  *   },
- * })
+ * })) {
+ *   ids.push(id)
+ * }
  * ```
+ */
+declare function collectLazy<T>(node: Node, options: CollectOptions<T>): Generator<T, void, undefined>;
+/**
+ * Eager depth-first collection pass. Returns an array of every non-null value
+ * the visitor callbacks return.
  *
- * @example
+ * @example Collect every operationId
  * ```ts
- * // Collect from only the current node
- * const values = collect(root, { depth: 'shallow', root: () => 'root' })
+ * const ids = collect<string>(root, {
+ *   operation(node) {
+ *     return node.operationId
+ *   },
+ * })
  * ```
  */
-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

package/dist/index.js

@@ -587,11 +587,14 @@ function* getChildren(node, recurse) {
 	}
 }
 /**
-* Depth-first traversal for side effects. Visitor return values are ignored.
-* Sibling nodes at each level are visited concurrently up to `options.concurrency`
-* (default: `WALK_CONCURRENCY`).
+* Async depth-first traversal for side effects. Visitor return values are
+* ignored. Use `transform` when you want to rewrite nodes.
 *
-* @example
+* Sibling nodes at each depth run concurrently up to `options.concurrency`
+* (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor
+* work; lower values reduce memory pressure.
+*
+* @example Log every operation
 * ```ts
 * await walk(root, {
 *   operation(node) {
@@ -600,10 +603,9 @@ function* getChildren(node, recurse) {
 * })
 * ```
 *
-* @example
+* @example Only visit the root node
 * ```ts
-* // Visit only the current node
-* await walk(root, { depth: 'shallow', root: () => {} })
+* await walk(root, { depth: 'shallow', input: () => {} })
 * ```
 */
 async function walk(node, options) {
@@ -725,23 +727,19 @@ function transform(node, options) {
 	return node;
 }
 /**
-* Runs a depth-first synchronous collection pass.
+* Lazy depth-first collection pass. Yields every non-null value returned by
+* the visitor callbacks. Use `collect` for the eager array form.
 *
-* Non-`null` values returned by visitor callbacks are appended to the result.
-*
-* @example
+* @example Collect every operationId
 * ```ts
-* const ids = collect(root, {
+* const ids: string[] = []
+* for (const id of collectLazy<string>(root, {
 *   operation(node) {
 *     return node.operationId
 *   },
-* })
-* ```
-*
-* @example
-* ```ts
-* // Collect from only the current node
-* const values = collect(root, { depth: 'shallow', root: () => 'root' })
+* })) {
+*   ids.push(id)
+* }
 * ```
 */
 function* collectLazy(node, options) {
@@ -777,6 +775,19 @@ function* collectLazy(node, options) {
 		parent: node
 	});
 }
+/**
+* Eager depth-first collection pass. Returns an array of every non-null value
+* the visitor callbacks return.
+*
+* @example Collect every operationId
+* ```ts
+* const ids = collect<string>(root, {
+*   operation(node) {
+*     return node.operationId
+*   },
+* })
+* ```
+*/
 function collect(node, options) {
 	return Array.from(collectLazy(node, options));
 }
@@ -1402,10 +1413,13 @@ function containsCircularRef(node, { circularSchemas, excludeName }) {
 //#endregion
 //#region src/factory.ts
 /**
-* Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
+* Updates a schema's `optional` and `nullish` flags from a parent's `required`
+* value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
+* object properties combine "required" and "nullable" into a single AST.
 *
-* - `optional` is set for non-required, non-nullable schemas.
-* - `nullish` is set for non-required, nullable schemas.
+* - Non-required + non-nullable → `optional: true`.
+* - Non-required + nullable → `nullish: true`.
+* - Required → both flags cleared.
 */
 function syncOptionality(schema, required) {
 	const nullable = schema.nullable ?? false;
@@ -2045,22 +2059,27 @@ function createJsx(value) {
 //#endregion
 //#region src/printer.ts
 /**
-* Creates a schema printer factory.
-*
-* This function wraps a builder and makes options optional at call sites.
+* Defines a schema printer: a function that takes a `SchemaNode` and emits
+* code in your target language. Each plugin that produces code from schemas
+* (TypeScript types, Zod schemas, Faker factories) ships a printer built
+* with this helper.
 *
 * 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)_ — top-level override exposed as `printer.print`
-*   - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
-*   - This keeps recursion safe and avoids self-calls
 *
-* When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
+* - `name` — unique identifier for the printer.
+* - `options` — stored on the returned printer instance.
+* - `nodes` — map of `SchemaType` → handler. Handlers return the rendered
+*   output (a string, a TypeScript AST node, ...) for that schema type.
+* - `print` (optional) — top-level override exposed as `printer.print`.
+*   Use `this.transform(node)` inside it to dispatch to `nodes` recursively.
 *
-* @example Basic usage — Zod schema printer
+* Without a `print` override, `printer.print` falls back to `printer.transform`
+* (the node-level dispatcher).
+*
+* @example Tiny Zod printer
 * ```ts
+* import { definePrinter, type PrinterFactoryOptions } from '@kubb/ast'
+*
 * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
 *
 * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
@@ -2069,7 +2088,9 @@ function createJsx(value) {
 *   nodes: {
 *     string: () => 'z.string()',
 *     object(node) {
-*       const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
+*       const props = node.properties
+*         .map((p) => `${p.name}: ${this.transform(p.schema)}`)
+*         .join(', ')
 *       return `z.object({ ${props} })`
 *     },
 *   },