@kubb/ast 5.0.0-beta.57 → 5.0.0-beta.59

package/src/nodes/input.ts

@@ -35,11 +35,11 @@ export type InputMeta = {
   baseURL?: string | null
   /**
    * Names of schemas that participate in a circular reference chain.
-   * Computed once during the adapter pre-scan, use this instead of calling
-   * `findCircularSchemas` per generator call.
+   * Computed once during the adapter pre-scan, so a generator never has to
+   * call `findCircularSchemas` itself.
    *
    * Convert to a `Set` once at the start of a generator, not per-schema,
-   * to keep lookup O(1) without repeated allocations.
+   * so lookups stay O(1) without repeated allocations.
    *
    * @example Wrap a circular schema in z.lazy()
    * ```ts
@@ -50,11 +50,11 @@ export type InputMeta = {
   circularNames: ReadonlyArray<string>
   /**
    * Names of schemas whose type is `enum`.
-   * Computed once during the adapter pre-scan, use this instead of filtering
-   * schemas per generator call.
+   * Computed once during the adapter pre-scan, so a generator never has to
+   * filter the schema list itself.
    *
    * Convert to a `Set` once at the start of a generator when you need repeated
-   * membership checks, rather than calling `.includes()` per schema.
+   * membership checks, so each check stays O(1) instead of an array scan.
    *
    * @example Check if a referenced schema is an enum
    * `const enums = new Set(meta.enumNames)`
@@ -114,26 +114,27 @@ export const inputDef = defineNode<InputNode, Partial<Omit<InputNode, 'kind'>>>(
 })
 
 /**
- * Creates an `InputNode` with stable defaults for `schemas` and `operations`.
+ * Creates an `InputNode`. Pass `stream: true` for the streaming variant whose `schemas` and
+ * `operations` are `AsyncIterable` sources and whose `meta` is optional. Otherwise it builds the
+ * eager variant with array `schemas`/`operations` and the defaulted `meta`.
  *
- * @example
+ * @example Eager
  * ```ts
  * const input = createInput()
  * // { kind: 'Input', schemas: [], operations: [] }
  * ```
- */
-export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): InputNode {
-  return inputDef.create(overrides)
-}
-
-/**
- * Creates a streaming `InputNode<true>` from pre-built `AsyncIterable` sources.
  *
- * @example
+ * @example Streaming
  * ```ts
- * const node = createStreamInput(schemasIterable, operationsIterable, { title: 'My API' })
+ * const node = createInput({ stream: true, schemas: schemasIterable, operations: operationsIterable, meta: { title: 'My API' } })
  * ```
  */
-export function createStreamInput(schemas: AsyncIterable<SchemaNode>, operations: AsyncIterable<OperationNode>, meta?: InputMeta): InputNode<true> {
-  return { kind: 'Input', schemas, operations, meta }
+export function createInput<Stream extends boolean = false>(options: Partial<Omit<InputNode<Stream>, 'kind'>> & { stream?: Stream } = {}): InputNode<Stream> {
+  const { stream, ...overrides } = options
+  // Streaming inputs carry AsyncIterable sources, so skip the array/meta defaults that
+  // inputDef.create applies for the eager variant.
+  if (stream) {
+    return { kind: 'Input', ...overrides } as InputNode<Stream>
+  }
+  return inputDef.create(overrides as Partial<Omit<InputNode, 'kind'>>) as InputNode<Stream>
 }

package/src/nodes/operation.ts

@@ -41,7 +41,7 @@ type OperationNodeBase = BaseNode & {
    */
   deprecated?: boolean
   /**
-   * Parameters that could be used, we have QueryParams, PathParams, HeaderParams and CookieParams
+   * Query, path, header, and cookie parameters for the operation.
    */
   parameters: Array<ParameterNode>
   /**

package/src/nodes/parameter.ts

@@ -19,9 +19,6 @@ export type ParameterLocation = 'path' | 'query' | 'header' | 'cookie'
  * ```
  */
 export type ParameterNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Parameter'
   /**
    * Parameter name.

package/src/nodes/property.ts

@@ -16,9 +16,6 @@ import type { SchemaNode } from './schema.ts'
  * ```
  */
 export type PropertyNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Property'
   /**
    * Property key.

package/src/nodes/requestBody.ts

@@ -18,12 +18,9 @@ import { type ContentNode, createContent, type UserContent } from './content.ts'
  * ```
  */
 export type RequestBodyNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'RequestBody'
   /**
-   * Human-readable request body description.
+   * Request body description carried over from the spec.
    */
   description?: string
   /**
@@ -32,11 +29,11 @@ export type RequestBodyNode = BaseNode & {
    */
   required?: boolean
   /**
-   * All available content type entries for this request body.
+   * Content type entries for this request body.
    *
    * When the adapter `contentType` option is set, this array contains exactly one entry for
    * that content type. Otherwise it contains one entry per content type declared in the spec,
-   * so that plugins can generate code for every variant (e.g. separate hooks for
+   * so plugins can generate code for every variant (for example, separate hooks for
    * `application/json` and `multipart/form-data`).
    */
   content?: Array<ContentNode>

package/src/nodes/schema.ts

@@ -280,8 +280,9 @@ export type UnionSchemaNode = CompositeSchemaNodeBase & {
    */
   discriminatorPropertyName?: string
   /**
-   * Logical strategy applied to union members: 'one' means exactly one member must be valid (from `oneOf`),
-   * 'any' means any number of members can be valid (from `anyOf`).
+   * How many union members must be valid.
+   * - `'one'`: exactly one member, from `oneOf`
+   * - `'any'`: any number of members, from `anyOf`
    */
   strategy?: 'one' | 'any'
 }

package/src/printer.ts

@@ -106,7 +106,7 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
   /**
    * Node-level dispatcher, converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
    * Always dispatches through the `nodes` map. Never calls the `print` override.
-   * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
+   * Reach for it when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
   transform: (node: SchemaNode) => T['output'] | null
   /**
@@ -192,11 +192,11 @@ export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOp
 
 /**
  * Generic printer-factory function used by `definePrinter` and `defineFunctionPrinter`.
- **
+ *
  * @example
  * ```ts
- * export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
- *   (node) => kindToHandlerKey[node.kind],
+ * export const defineFunctionPrinter = createPrinterFactory<FunctionParamNode, FunctionParamKind, Partial<Record<FunctionParamKind, FunctionParamNode>>>(
+ *   (node) => node.kind,
  * )
  * ```
  */

package/src/registry.ts

@@ -3,7 +3,6 @@ import { arrowFunctionDef, breakDef, constDef, functionDef, jsxDef, textDef, typ
 import { contentDef } from './nodes/content.ts'
 import { exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'
 import { functionParameterDef, functionParametersDef, indexedAccessTypeDef, objectBindingPatternDef, typeLiteralDef } from './nodes/function.ts'
-import type { Node, NodeKind } from './nodes/index.ts'
 import { inputDef } from './nodes/input.ts'
 import { operationDef } from './nodes/operation.ts'
 import { outputDef } from './nodes/output.ts'
@@ -13,9 +12,39 @@ import { requestBodyDef } from './nodes/requestBody.ts'
 import { responseDef } from './nodes/response.ts'
 import { schemaDef } from './nodes/schema.ts'
 
+// Surface every def from one place so the package barrel re-exports them with `export * from './registry.ts'`.
+// Adding a node means adding its `defineNode` to a `nodes/*.ts` file and listing it in `nodeDefs` below, nothing else.
+export {
+  arrowFunctionDef,
+  breakDef,
+  constDef,
+  contentDef,
+  exportDef,
+  fileDef,
+  functionDef,
+  functionParameterDef,
+  functionParametersDef,
+  importDef,
+  indexedAccessTypeDef,
+  inputDef,
+  jsxDef,
+  objectBindingPatternDef,
+  operationDef,
+  outputDef,
+  parameterDef,
+  propertyDef,
+  requestBodyDef,
+  responseDef,
+  schemaDef,
+  sourceDef,
+  textDef,
+  typeDef,
+  typeLiteralDef,
+}
+
 /**
  * Every node definition. Adding a node means adding its `defineNode` to one
- * `nodes/*.ts` file and listing it here. The visitor tables below derive from it.
+ * `nodes/*.ts` file and listing it here. The visitor tables in `visitor.ts` derive from it.
  */
 export const nodeDefs = [
   inputDef,
@@ -44,27 +73,3 @@ export const nodeDefs = [
   sourceDef,
   fileDef,
 ] satisfies ReadonlyArray<NodeDef>
-
-/**
- * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).
- * Derived from each definition's `children`.
- */
-export const VISITOR_KEYS = Object.fromEntries(nodeDefs.flatMap((def) => (def.children ? [[def.kind, def.children] as const] : []))) as Partial<
-  Record<NodeKind, ReadonlyArray<string>>
->
-
-/**
- * Maps a node kind to the matching visitor callback name. Derived from each
- * definition's `visitorKey`.
- */
-export const VISITOR_KEY_BY_KIND = Object.fromEntries(nodeDefs.flatMap((def) => (def.visitorKey ? [[def.kind, def.visitorKey] as const] : []))) as Partial<
-  Record<NodeKind, NonNullable<NodeDef['visitorKey']>>
->
-
-/**
- * Per-kind builders rerun after children are rebuilt. Derived from each
- * definition's `rebuild` flag.
- */
-export const nodeRebuilders = Object.fromEntries(
-  nodeDefs.flatMap((def) => (def.rebuild ? [[def.kind, def.create as unknown as (node: Node) => Node] as const] : [])),
-) as Partial<Record<NodeKind, (node: Node) => Node>>

package/src/signature.ts

@@ -170,9 +170,9 @@ function describeShape(node: SchemaNode): string {
 }
 
 /**
- * Node → digest cache, keyed by identity. A `WeakMap` so entries die with the node, and so a tree
- * hashed during dedupe planning is not walked again when it is rewritten during streaming. Reuse
- * is safe because a signature depends only on content, and nodes are immutable once created.
+ * Caches the digest per node, keyed by identity. A `WeakMap` so entries die with the node, and so
+ * a tree hashed during dedupe planning is not walked again when it is rewritten during streaming.
+ * Reuse is safe because a signature depends only on content, and nodes are immutable once created.
  */
 const signatureCache = new WeakMap<SchemaNode, string>()
 

package/src/transformers.ts

@@ -2,7 +2,7 @@ import { isScalarPrimitive } from './constants.ts'
 import { narrowSchema } from './guards.ts'
 import { createProperty } from './nodes/property.ts'
 import { createSchema, type SchemaNode } from './nodes/schema.ts'
-import { enumPropName } from './utils/index.ts'
+import { enumPropName } from './utils/refs.ts'
 
 /**
  * Replaces a discriminator property's schema with a string enum of allowed values.
@@ -162,3 +162,30 @@ export function setEnumName(propNode: SchemaNode, parentName: string | null | un
 
   return propNode
 }
+
+/**
+ * Merges a ref node with its resolved schema, giving usage-site fields precedence.
+ *
+ * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node override
+ * the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * // Ref with description override
+ * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+ * const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
+ * ```
+ */
+export function syncSchemaRef(node: SchemaNode): SchemaNode {
+  const ref = narrowSchema(node, 'ref')
+
+  if (!ref) return node
+  if (!ref.schema) return node
+
+  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref
+
+  // Filter out undefined override values so they don't shadow the resolved schema's fields.
+  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
+
+  return createSchema({ ...ref.schema, ...definedOverrides })
+}

package/src/types.ts

@@ -2,59 +2,8 @@ export type { DedupeCanonical, DedupeLookups, DedupePlan } from './dedupe.ts'
 export type { SchemaDialect } from './dialect.ts'
 export type { DistributiveOmit } from './node.ts'
 export type { InferSchemaNode, ParserOptions } from './infer.ts'
-export type {
-  ArraySchemaNode,
-  ArrowFunctionNode,
-  CodeNode,
-  ConstNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  ExportNode,
-  FileNode,
-  FunctionNode,
-  FunctionNodeType,
-  FunctionParameterNode,
-  FunctionParametersNode,
-  FunctionParamNode,
-  HttpMethod,
-  HttpOperationNode,
-  ImportNode,
-  IndexedAccessTypeNode,
-  InputMeta,
-  InputNode,
-  IntersectionSchemaNode,
-  JSDocNode,
-  JsxNode,
-  Node,
-  NodeKind,
-  NumberSchemaNode,
-  ObjectBindingPatternNode,
-  ObjectSchemaNode,
-  OperationNode,
-  OutputNode,
-  ParameterLocation,
-  ParameterNode,
-  PrimitiveSchemaType,
-  PropertyNode,
-  RefSchemaNode,
-  ResponseNode,
-  ScalarSchemaType,
-  SchemaNode,
-  SchemaNodeByType,
-  SchemaType,
-  SourceNode,
-  StatusCode,
-  StringSchemaNode,
-  TextNode,
-  TimeSchemaNode,
-  TypeExpression,
-  TypeLiteralNode,
-  TypeNode,
-  UnionSchemaNode,
-  UrlSchemaNode,
-} from './nodes/index.ts'
+export type * from './nodes/index.ts'
 export type { ParentOf, Visitor, VisitorContext } from './visitor.ts'
 export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
-export type { OperationParamsResolver } from './utils/ast.ts'
+export type { OperationParamsResolver } from './utils/operationParams.ts'
 export type { UserFileNode } from './factory.ts'

package/src/utils/codegen.ts

@@ -0,0 +1,104 @@
+import { isIdentifier, singleQuote } from '@internals/utils'
+import { INDENT } from '../constants.ts'
+
+/**
+ * Builds a JSDoc comment block from an array of lines, returning `fallback` when there are no
+ * comments so callers always get a usable string.
+ *
+ * @example
+ * ```ts
+ * buildJSDoc(['@type string', '@example hello'])
+ * // '/**\n   * @type string\n   * @example hello\n   *\/\n  '
+ * ```
+ */
+export function buildJSDoc(
+  comments: Array<string>,
+  options: {
+    /**
+     * String used to indent each comment line.
+     * @default '   * '
+     */
+    indent?: string
+    /**
+     * String appended after the closing tag.
+     * @default '\n  '
+     */
+    suffix?: string
+    /**
+     * Returned as-is when `comments` is empty.
+     * @default '  '
+     */
+    fallback?: string
+  } = {},
+): string {
+  const { indent = '   * ', suffix = '\n  ', fallback = '  ' } = options
+
+  if (comments.length === 0) return fallback
+
+  return `/**\n${comments.map((c) => `${indent}${c}`).join('\n')}\n   */${suffix}`
+}
+
+/**
+ * Indents every non-empty line of `text` by one indent level, leaving blank lines empty.
+ */
+function indentLines(text: string): string {
+  if (!text) return ''
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? `${INDENT}${line}` : ''))
+    .join('\n')
+}
+
+/**
+ * Renders an object key, quoting it with single quotes only when it is not a valid identifier.
+ * Reserved words and globals (`name`, `class`, …) are valid bare keys and stay unquoted.
+ *
+ * @example
+ * ```ts
+ * objectKey('name')    // 'name'
+ * objectKey('x-total') // "'x-total'"
+ * ```
+ */
+export function objectKey(name: string): string {
+  return isIdentifier(name) ? name : singleQuote(name)
+}
+
+/**
+ * Assembles a multi-line object literal from already-rendered `entries`, indenting each entry one
+ * level and closing the brace at column zero. Nested objects built the same way indent cumulatively,
+ * so callers never re-parse the generated code. A trailing comma is added per entry to match the
+ * formatter's multi-line style.
+ *
+ * @example
+ * ```ts
+ * buildObject(['id: z.number()', 'name: z.string()'])
+ * // '{\n  id: z.number(),\n  name: z.string(),\n}'
+ * ```
+ */
+export function buildObject(entries: Array<string>): string {
+  if (entries.length === 0) return '{}'
+  const body = entries.map((entry) => `${indentLines(entry)},`).join('\n')
+
+  return `{\n${body}\n}`
+}
+
+/**
+ * Assembles a bracketed list (array by default) from already-rendered `items`. Keeps everything on
+ * one line when no item spans multiple lines, and otherwise puts each item on its own line, indented
+ * one level with a trailing comma and the closing bracket at column zero. Use it for `z.union([…])`,
+ * `z.array([…])`, and similar member lists so objects inside them nest correctly.
+ *
+ * @example
+ * ```ts
+ * buildList(['z.string()', 'z.number()'])
+ * // '[z.string(), z.number()]'
+ * ```
+ */
+export function buildList(items: Array<string>, brackets: [open: string, close: string] = ['[', ']']): string {
+  const [open, close] = brackets
+  if (items.length === 0) return `${open}${close}`
+  if (!items.some((item) => item.includes('\n'))) return `${open}${items.join(', ')}${close}`
+  const body = items.map((item) => `${indentLines(item)},`).join('\n')
+
+  return `${open}\n${body}\n${close}`
+}

package/src/utils/extractStringsFromNodes.ts

@@ -0,0 +1,34 @@
+import type { CodeNode } from '../nodes/code.ts'
+
+/**
+ * Extracts all string content from a `CodeNode` tree recursively.
+ *
+ * Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
+ * and nested node content. Used to build the full source string for import filtering.
+ */
+export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string {
+  if (!nodes?.length) return ''
+  return nodes
+    .map((node) => {
+      // Backward-compat: compiled plugins may still pass bare strings at runtime
+      if (typeof node === 'string') return node as string
+      if (node.kind === 'Text') return node.value
+      if (node.kind === 'Break') return ''
+      if (node.kind === 'Jsx') return node.value
+
+      const parts: Array<string> = []
+
+      if ('params' in node && node.params) parts.push(node.params)
+      if ('generics' in node && node.generics) parts.push(Array.isArray(node.generics) ? node.generics.join(', ') : node.generics)
+      if ('returnType' in node && node.returnType) parts.push(node.returnType)
+      if ('type' in node && typeof node.type === 'string') parts.push(node.type)
+
+      const nested = extractStringsFromNodes(node.nodes)
+
+      if (nested) parts.push(nested)
+
+      return parts.join('\n')
+    })
+    .filter(Boolean)
+    .join('\n')
+}