@kubb/ast 5.0.0-beta.22 → 5.0.0-beta.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.22",
+  "version": "5.0.0-beta.24",
   "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",

package/src/factory.ts

@@ -33,10 +33,13 @@ import type {
 import { combineExports, combineImports, combineSources, extractStringsFromNodes } from './utils.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.
  */
 export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
   const nullable = schema.nullable ?? false

package/src/infer.ts

@@ -20,15 +20,25 @@ import type {
  */
 export 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'
   /**
@@ -36,7 +46,8 @@ export 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 & {})
 }

package/src/nodes/code.ts

@@ -36,21 +36,21 @@ export 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.
@@ -83,11 +83,11 @@ export 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.
@@ -126,35 +126,35 @@ export 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.
@@ -187,40 +187,40 @@ export 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.

package/src/nodes/file.ts

@@ -50,18 +50,18 @@ export 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
 }
 
 /**
@@ -94,7 +94,7 @@ export type ExportNode = BaseNode & {
    * @example ['useState']
    * @example 'React'
    */
-  name?: string | Array<string>
+  name?: string | Array<string> | null
   /**
    * Path for the export.
    * @example '@kubb/core'
@@ -106,14 +106,14 @@ export 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
 }
 
 /**
@@ -134,22 +134,22 @@ export 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.
@@ -180,8 +180,8 @@ export type SourceNode = BaseNode & {
 export 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
   /**

package/src/printer.ts

@@ -148,22 +148,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) => ({
@@ -172,7 +177,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} })`
  *     },
  *   },

package/src/utils.ts

@@ -556,15 +556,15 @@ function sourceKey(source: SourceNode): string {
   return `${nameKey}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`
 }
 
-function pathTypeKey(path: string, isTypeOnly: boolean | undefined): string {
+function pathTypeKey(path: string, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${isTypeOnly ?? false}`
 }
 
-function exportKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined, asAlias: boolean | undefined): string {
+function exportKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined, asAlias: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}:${asAlias ?? ''}`
 }
 
-function importKey(path: string, name: string | undefined, isTypeOnly: boolean | undefined): string {
+function importKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined): string {
   return `${path}:${name ?? ''}:${isTypeOnly ?? false}`
 }
 
@@ -572,7 +572,7 @@ function importKey(path: string, name: string | undefined, isTypeOnly: boolean |
  * Computes a multi-level sort key for exports and imports:
  * non-array names first (wildcards/namespace aliases); type-only before value; alphabetical path; unnamed before named.
  */
-function sortKey(node: { name?: string | Array<unknown>; isTypeOnly?: boolean; path: string }): string {
+function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boolean | null; path: string }): string {
   const isArray = Array.isArray(node.name) ? '1' : '0'
   const typeOnly = node.isTypeOnly ? '0' : '1'
   const hasName = node.name != null ? '1' : '0'

package/src/visitor.ts

@@ -115,25 +115,40 @@ export type VisitorContext<T extends Node = Node> = {
 }
 
 /**
- * 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 }
  *   },
  * }
  * ```
  */
 export 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
 }
 
 /**
@@ -154,13 +169,13 @@ type MaybePromise<T> = T | Promise<T>
  * ```
  */
 export 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>
 }
 
 /**
@@ -310,11 +325,14 @@ function* getChildren(node: Node, recurse: boolean): Generator<Node, void, undef
 }
 
 /**
- * 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) {
@@ -323,10 +341,9 @@ function* getChildren(node: Node, recurse: boolean): Generator<Node, void, undef
  * })
  * ```
  *
- * @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: () => {} })
  * ```
  */
 export async function walk(node: Node, options: WalkOptions): Promise<void> {
@@ -368,12 +385,13 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
 }
 
 /**
- * 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) {
@@ -382,10 +400,12 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
  * })
  * ```
  *
- * @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' } }),
+ * })
  * ```
  */
 export function transform(node: InputNode, options: TransformOptions): InputNode
@@ -485,23 +505,19 @@ export function transform(node: Node, options: TransformOptions): Node {
   return 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
  *   },
- * })
- * ```
- *
- * @example
- * ```ts
- * // Collect from only the current node
- * const values = collect(root, { depth: 'shallow', root: () => 'root' })
+ * })) {
+ *   ids.push(id)
+ * }
  * ```
  */
 export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generator<T, void, undefined> {
@@ -539,6 +555,19 @@ export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generat
   }
 }
 
+/**
+ * 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
+ *   },
+ * })
+ * ```
+ */
 export function collect<T>(node: Node, options: CollectOptions<T>): Array<T> {
   return Array.from(collectLazy(node, options))
 }