AST and node builders

ast

ast is kubb/kit's namespace for the entire AST surface, the same way TypeScript groups its node constructors under ts.factory. It carries the factory node builders, the transform and collect visitors, the guards, the ref and string helpers, and the macro engine.

import { ast } from 'kubb/kit'

const root = ast.factory.createInput({
  schemas: [ast.factory.createSchema({ name: 'Pet', type: 'object', properties: [] })],
  operations: [],
})

Node building goes through ast.factory. ast.factory.createFile, ast.factory.createSource, and ast.factory.createText build the FileNode tree a generator returns. See the factory table below.

For why the AST exists and how it fits the pipeline, see AST concepts.

Schema node types

A SchemaNode is discriminated by its type. The values fall into three families.

Structural types

Scalar types

Special types

Factory functions

Factories return defaulted, fully typed nodes for adapters and generator handlers. Never build AST literals by hand. Besides createInput, createSchema, and createOperation, the namespace provides constructors for source files and the TypeScript-level artifacts generators emit:

Visitors

Two visitor functions cover the common traversal patterns: transform rewrites the tree and collect gathers nodes. Visitor objects use lowercase, kind-style keys (input, output, operation, schema, property, parameter, response). To rewrite nodes inside a plugin, reach for macros, which add names, ordering, and composition on top of transform. For logging, validation, or statistics, collect the nodes you care about.

transform: synchronous, returns a new tree

import { ast } from 'kubb/kit'

const root = ast.factory.createInput({ schemas: [], operations: [] })

const enhanced = ast.transform(root, {
  schema(node) {
    if (node.type === 'object' && node.additionalProperties === undefined) {
      return { ...node, additionalProperties: false }
    }
    return node
  },
  operation(node) {
    return { ...node, tags: node.tags?.length ? node.tags : ['untagged'] }
  },
})

Use transform to change AST structure, normalize inconsistencies, or annotate nodes.

To apply a change and keep that guarantee, use the update factory instead of spreading by hand. It returns the same node when every field you pass already matches:

import { ast } from 'kubb/kit'

const node = ast.factory.createSchema({ name: 'Pet', type: 'object', properties: [] })

ast.factory.update(node, { name: 'Pet' }) // -> same `node` reference (no change)
ast.factory.update(node, { name: 'Animal' }) // -> new node with `name` replaced

collect: gather matching nodes

collect is a generator function, so it yields matches lazily and you consume it with for...of or spread it into an array. When you want the array up front, call collectSync, which is the eager counterpart and returns Array<T>.

import { ast } from 'kubb/kit'

const root = ast.factory.createInput({ schemas: [], operations: [] })

const mutations = ast.collectSync<ast.OperationNode>(root, {
  operation(node) {
    return node.method === 'POST' ? node : undefined
  },
})

const deprecated = ast.collectSync<ast.SchemaNode>(root, {
  schema(node) {
    return 'deprecated' in node && node.deprecated ? node : undefined
  },
})

console.log(`POST operations: ${mutations.length}`)
console.log(`Deprecated schemas: ${deprecated.length}`)

Use collect to stream matches as you find them, and collectSync to find specific nodes, filter by a criterion, or build a list for later processing.

Guards and narrowing

Kubb exports type guards and a narrowSchema helper for safe discrimination:

import { ast } from 'kubb/kit'

const root = ast.factory.createInput({ schemas: [], operations: [] })

for (const node of ast.collect<ast.SchemaNode>(root, { schema: (node) => node })) {
  const obj = ast.narrowSchema(node, 'object')
  if (obj) {
    console.log(`object with ${obj.properties.length} properties`)
  }

  if (node.type === 'ref') {
    console.log(`reference to: ${node.ref}`)
  }
}

for (const node of ast.collect<ast.OperationNode>(root, { operation: (node) => node })) {
  if (ast.isHttpOperationNode(node)) {
    console.log(`${node.method} ${node.path}`)
  }
}

Refs and naming helpers

The helpers split across two surfaces. resolveRefName ships on the ast namespace, like the guards and node types. extractRefName, childName, enumPropName, and syncSchemaRef are named exports of kubb/kit itself. The same split applies to containsCircularRef and the built-in macros below.

import { extractRefName } from 'kubb/kit'

const name = extractRefName('#/components/schemas/Pet')

Schema graph

Analyze how schemas reference each other, to prune unused schemas or wrap circular ones in a lazy construct. collectUsedSchemaNames and findCircularSchemas ship on the ast namespace.

Constants

Macros

A macro is a named, composable transform built on transform that rewrites nodes before printing, adding ordering, gating, and reuse a bare visitor doesn't give you. See Macros concepts.

Kubb also ships built-in macros for common schema normalizations that any adapter can compose with its own. macroDiscriminatorEnum, macroEnumName, and macroRenameSchema read options, so call them to build the macro. Plugins that import another plugin's output compute names from the nodes they see, so register a rename on every plugin that touches the schema, for example by passing one shared macros array to each plugin.

Macro options and callbacks

A macro carries the per-kind callbacks of a visitor, plus a name, an optional enforce order, and an optional match predicate.

type Macro = {
  name: string
  enforce?: 'pre' | 'post'
  match?: (node: Node) => boolean
  schema?(node: SchemaNode, context): SchemaNode | null | undefined
  operation?(node: OperationNode, context): OperationNode | null | undefined
  // input, output, property, parameter, response
}

Each callback returns a replacement node, or undefined or null to leave the node untouched. A macro that changes nothing returns the original reference, so an unchanged tree is reused, not rebuilt.

Printers

Lower-level helpers for parsers that turn the AST into source code:

createPrinter takes an overrides map to replace the handler for individual schema node types. Pass overrides through the overrides field rather than spreading them into nodes, otherwise this.base cannot find the original handler. The printer.nodes option on @kubb/plugin-ts, @kubb/plugin-zod, and @kubb/plugin-faker feeds this map. See Customize printers.

See Import a custom codec for a complete example and Parsers concepts for how parsers consume printers.

Printer handlers and context

The map is keyed by the schema type discriminant, such as 'string', 'integer', 'date', 'enum', or 'object'. Supply only the handlers you want to replace and the built-in ones fill in the rest.

type PrinterNodes = Partial<{
  [K in SchemaType]: (this: Context, node: SchemaNodeByType[K]) => Output | null
}>

Handlers run with a this context, so write them as regular functions rather than arrow functions. this.transform(node) recurses into a nested schema node through the full handler map, overrides included. this.base(node) runs the built-in handler your override replaced, so you can wrap its output instead of rebuilding it. this.options reads the resolved printer options, such as arrayType on @kubb/plugin-ts or direction on @kubb/plugin-zod. Inside a handler, this.import(ast.factory.createImport(...)) declares an import the printed code needs. The generator calls printer.drainImports() after printing to collect them.