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

package/src/constants.ts

@@ -17,9 +17,8 @@ export const visitorDepths = {
 /**
  * Schema type discriminators used by all AST schema nodes.
  *
- * These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
- * Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
- * and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
+ * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).
+ * Call `isScalarPrimitive()` to check for the scalar types.
  */
 export const schemaTypes = {
   /**
@@ -39,7 +38,7 @@ export const schemaTypes = {
    */
   bigint: 'bigint',
   /**
-   * Boolean value
+   * Boolean value.
    */
   boolean: 'boolean',
   /**
@@ -132,15 +131,12 @@ export type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'bool
 
 /**
  * Scalar primitive schema types used for union simplification and type narrowing.
- *
- * Use `isScalarPrimitive()` to safely check whether a type is a scalar primitive.
  */
 const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
 
 /**
- * Type guard that returns `true` when `type` is a scalar primitive schema type.
- *
- * Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
+ * Returns `true` when `type` is a scalar primitive that can be assigned without wrapping
+ * (for example `string | number | boolean`).
  */
 export function isScalarPrimitive(type: string): type is ScalarPrimitive {
   return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
@@ -148,8 +144,6 @@ export function isScalarPrimitive(type: string): type is ScalarPrimitive {
 
 /**
  * HTTP method identifiers used by operation nodes.
- *
- * Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
  */
 export const httpMethods = {
   get: 'GET',
@@ -163,10 +157,10 @@ export const httpMethods = {
 } as const satisfies Record<Lowercase<HttpMethod>, HttpMethod>
 
 /**
- * Default concurrency limit for `walk()` traversal utility.
+ * Default concurrency limit for the `walk()` traversal utility.
  *
- * Set to 30 to balance I/O-bound resolver parallelism against event loop pressure and memory usage during large spec traversals.
- * Use `WALK_CONCURRENCY` when calling `walk()` or override for different hardware constraints.
+ * Set to 30 to balance I/O-bound resolver parallelism against event-loop and memory pressure
+ * during large spec traversals. Override it for different hardware constraints.
  *
  * @example
  * ```ts

package/src/dedupe.ts

@@ -1,3 +1,11 @@
+/**
+ * Schema-shape deduplication. `buildDedupePlan` finds top-level and inline schemas that share a
+ * structural signature, picks one canonical definition, and `applyDedupe` repoints every duplicate
+ * at it. This works on `SchemaNode` content, not on files.
+ *
+ * For merging a file's imports, exports, and source nodes, see `utils/fileMerge.ts`. Same idea of
+ * collapsing duplicates, but a different domain.
+ */
 import type { Node, OperationNode, SchemaNode } from './nodes/index.ts'
 import { createSchema } from './nodes/schema.ts'
 import { signatureOf } from './signature.ts'

package/src/factory.ts

@@ -2,7 +2,24 @@ import { hash } from 'node:crypto'
 import path from 'node:path'
 import { trimExtName } from '@internals/utils'
 import type { FileNode, Node } from './nodes/index.ts'
-import { combineExports, combineImports, combineSources, extractStringsFromNodes } from './utils/ast.ts'
+import { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
+import { combineExports, combineImports, combineSources } from './utils/fileMerge.ts'
+
+// Node constructors, grouped under the `factory` namespace the way the TypeScript compiler exposes
+// `ts.factory.createX`. Aggregating them here lets `export * as factory from './factory.ts'` in the
+// barrel surface every `createX` alongside the `createFile`/`update` helpers from a single module.
+export { createArrowFunction, createBreak, createConst, createFunction, createJsx, createText, createType } from './nodes/code.ts'
+export { createContent } from './nodes/content.ts'
+export { createExport, createImport, createSource } from './nodes/file.ts'
+export { createFunctionParameter, createFunctionParameters, createIndexedAccessType, createObjectBindingPattern, createTypeLiteral } from './nodes/function.ts'
+export { createInput } from './nodes/input.ts'
+export { createOperation } from './nodes/operation.ts'
+export { createOutput } from './nodes/output.ts'
+export { createParameter } from './nodes/parameter.ts'
+export { createProperty } from './nodes/property.ts'
+export { createRequestBody } from './nodes/requestBody.ts'
+export { createResponse } from './nodes/response.ts'
+export { createSchema } from './nodes/schema.ts'
 
 /**
  * Identity-preserving node update: returns `node` unchanged when every field in

package/src/guards.ts

@@ -14,7 +14,7 @@ export function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | un
 }
 
 /**
- * Narrows an `OperationNode` to an `HttpOperationNode`, guaranteeing `method` and `path`.
+ * Narrows an `OperationNode` to an `HttpOperationNode` so `method` and `path` are present.
  *
  * @example
  * ```ts

package/src/index.ts

@@ -1,62 +1,19 @@
 export { httpMethods, schemaTypes } from './constants.ts'
 export { applyDedupe, buildDedupePlan } from './dedupe.ts'
 export { defineSchemaDialect } from './dialect.ts'
-export { createFile, update } from './factory.ts'
+// Node constructors, also published as the `@kubb/ast/factory` subpath, mirroring `ts.factory.createX`.
+export * as factory from './factory.ts'
 export { isHttpOperationNode, narrowSchema } from './guards.ts'
 export { defineNode } from './node.ts'
 export type { NodeDef } from './node.ts'
 export { syncOptionality } from './node.ts'
-export {
-  arrowFunctionDef,
-  breakDef,
-  constDef,
-  createArrowFunction,
-  createBreak,
-  createConst,
-  createFunction,
-  createJsx,
-  createText,
-  createType,
-  functionDef,
-  jsxDef,
-  textDef,
-  typeDef,
-} from './nodes/code.ts'
-export { contentDef } from './nodes/content.ts'
-export { createExport, createImport, createSource, exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'
-export {
-  createFunctionParameter,
-  createFunctionParameters,
-  createIndexedAccessType,
-  createObjectBindingPattern,
-  createTypeLiteral,
-  functionParameterDef,
-  functionParametersDef,
-  indexedAccessTypeDef,
-  objectBindingPatternDef,
-  typeLiteralDef,
-} from './nodes/function.ts'
-export { createInput, createStreamInput, inputDef } from './nodes/input.ts'
-export { createOperation, operationDef } from './nodes/operation.ts'
-export { createOutput, outputDef } from './nodes/output.ts'
-export { createParameter, parameterDef } from './nodes/parameter.ts'
-export { createProperty, propertyDef } from './nodes/property.ts'
-export { requestBodyDef } from './nodes/requestBody.ts'
-export { createResponse, responseDef } from './nodes/response.ts'
-export { createSchema, schemaDef } from './nodes/schema.ts'
+// Every node def plus `nodeDefs` in one line, so adding a node never edits this barrel. The visitor
+// tables derived from `nodeDefs` stay internal to `visitor.ts`.
+export * from './registry.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { signatureOf } from './signature.ts'
 export { mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type * from './types.ts'
-export {
-  caseParams,
-  collectUsedSchemaNames,
-  containsCircularRef,
-  createDiscriminantNode,
-  createOperationParams,
-  extractStringsFromNodes,
-  findCircularSchemas,
-  isStringType,
-  syncSchemaRef,
-} from './utils/ast.ts'
+// The node/AST helpers in ./utils/ live on the `@kubb/ast/utils` subpath, not the root barrel.
+export { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
 export { collect, transform, walk } from './visitor.ts'

package/src/node.ts

@@ -23,7 +23,7 @@ export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omi
 /**
  * Builds a type guard that matches nodes of the given `kind`.
  */
-export function isKind<T extends BaseNode>(kind: NodeKind) {
+function isKind<T extends BaseNode>(kind: NodeKind) {
   return (node: unknown): node is T => (node as BaseNode).kind === kind
 }
 

package/src/nodes/base.ts

@@ -47,13 +47,3 @@ export type BaseNode = {
    */
   kind: NodeKind
 }
-
-/**
- * Minimal node type when only `kind` is needed.
- *
- * @example
- * ```ts
- * const node: Node = { kind: 'Operation' }
- * ```
- */
-export type Node = BaseNode

package/src/nodes/code.ts

@@ -7,7 +7,11 @@ import type { BaseNode } from './base.ts'
 export type JSDocNode = {
   /**
    * JSDoc comment lines. `undefined` entries are filtered out during rendering.
-   * @example ['@description A pet resource', '@deprecated']
+   *
+   * @example
+   * ```ts
+   * ['@description A pet resource', '@deprecated']
+   * ```
    */
   comments?: Array<string | undefined>
 }
@@ -25,9 +29,6 @@ export type JSDocNode = {
  * ```
  */
 export type ConstNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Const'
   /**
    * Name of the constant declaration.
@@ -35,12 +36,13 @@ export type ConstNode = BaseNode & {
   name: string
   /**
    * Whether the declaration should be exported.
-   * @default false
    */
   export?: boolean | null
   /**
-   * Optional explicit type annotation.
-   * @example 'Pet'
+   * Explicit type annotation.
+   *
+   * @example Type reference
+   * `'Pet'`
    */
   type?: string | null
   /**
@@ -49,12 +51,11 @@ export type ConstNode = BaseNode & {
   JSDoc?: JSDocNode | null
   /**
    * Whether to append `as const` to the declaration.
-   * @default false
    */
   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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -72,9 +73,6 @@ export type ConstNode = BaseNode & {
  * ```
  */
 export type TypeNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Type'
   /**
    * Name of the type alias.
@@ -82,7 +80,6 @@ export type TypeNode = BaseNode & {
   name: string
   /**
    * Whether the declaration should be exported.
-   * @default false
    */
   export?: boolean | null
   /**
@@ -91,7 +88,7 @@ export type TypeNode = BaseNode & {
   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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -109,9 +106,6 @@ export type TypeNode = BaseNode & {
  * ```
  */
 export type FunctionNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Function'
   /**
    * Name of the function.
@@ -119,7 +113,6 @@ export type FunctionNode = BaseNode & {
   name: string
   /**
    * Whether the function is a default export.
-   * @default false
    */
   default?: boolean | null
   /**
@@ -128,22 +121,24 @@ export type FunctionNode = BaseNode & {
   params?: string | null
   /**
    * Whether the function should be exported.
-   * @default false
    */
   export?: boolean | null
   /**
    * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
-   * @default false
    */
   async?: boolean | null
   /**
    * TypeScript generic type parameters.
-   * @example ['T', 'U extends string']
+   *
+   * @example Constrained generics
+   * `['T', 'U extends string']`
    */
   generics?: string | Array<string> | null
   /**
    * Return type annotation.
-   * @example 'Pet'
+   *
+   * @example Type reference
+   * `'Pet'`
    */
   returnType?: string | null
   /**
@@ -152,7 +147,7 @@ export type FunctionNode = BaseNode & {
   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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -170,9 +165,6 @@ export type FunctionNode = BaseNode & {
  * ```
  */
 export type ArrowFunctionNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'ArrowFunction'
   /**
    * Name of the arrow function (used as the `const` variable name).
@@ -180,7 +172,6 @@ export type ArrowFunctionNode = BaseNode & {
   name: string
   /**
    * Whether the function is a default export.
-   * @default false
    */
   default?: boolean | null
   /**
@@ -189,22 +180,24 @@ export type ArrowFunctionNode = BaseNode & {
   params?: string | null
   /**
    * Whether the arrow function should be exported.
-   * @default false
    */
   export?: boolean | null
   /**
    * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
-   * @default false
    */
   async?: boolean | null
   /**
    * TypeScript generic type parameters.
-   * @example ['T', 'U extends string']
+   *
+   * @example Constrained generics
+   * `['T', 'U extends string']`
    */
   generics?: string | Array<string> | null
   /**
    * Return type annotation.
-   * @example 'Pet'
+   *
+   * @example Type reference
+   * `'Pet'`
    */
   returnType?: string | null
   /**
@@ -213,12 +206,11 @@ export type ArrowFunctionNode = BaseNode & {
   JSDoc?: JSDocNode | null
   /**
    * Render the arrow function body as a single-line expression.
-   * @default false
    */
   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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -236,9 +228,6 @@ export type ArrowFunctionNode = BaseNode & {
  * ```
  */
 export type TextNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Text'
   /**
    * The raw string content.
@@ -249,9 +238,8 @@ export type TextNode = BaseNode & {
 /**
  * AST node representing a line break in the source output.
  *
- * Corresponds to `<br/>` in JSX components. When printed, produces an empty
- * string that, joined with `\n` by `printNodes` creates a blank line
- * between surrounding code nodes.
+ * Corresponds to `<br/>` in JSX components. When printed it produces an empty string,
+ * so joining nodes with `\n` in `printNodes` leaves a blank line between the surrounding code.
  *
  * @example
  * ```ts
@@ -261,17 +249,14 @@ export type TextNode = BaseNode & {
  * ```
  */
 export type BreakNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Break'
 }
 
 /**
  * AST node representing a raw JSX fragment in the source output.
  *
- * Mirrors the `Jsx` component from `@kubb/renderer-jsx`. Use this to embed raw
- * JSX/TSX markup (including fragments `<>…</>`) directly in generated code.
+ * Mirrors the `Jsx` component from `@kubb/renderer-jsx`. Embeds raw JSX/TSX markup
+ * (including fragments `<>…</>`) directly in generated code.
  *
  * @example
  * ```ts
@@ -280,9 +265,6 @@ export type BreakNode = BaseNode & {
  * ```
  */
 export type JsxNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Jsx'
   /**
    * The raw JSX string content.

package/src/nodes/content.ts

@@ -5,8 +5,8 @@ import type { SchemaNode } from './schema.ts'
 /**
  * AST node representing one content-type entry of a request body or response.
  *
- * One entry per content type declared in the spec (e.g. `application/json`,
- * `multipart/form-data`), each carrying its own body schema.
+ * There is one entry per content type declared in the spec (e.g. `application/json`,
+ * `multipart/form-data`), and each entry holds its own body schema.
  *
  * @example
  * ```ts

package/src/nodes/file.ts

@@ -36,27 +36,31 @@ export type ImportNode = BaseNode & {
   kind: 'Import'
   /**
    * Import name(s) to be used.
-   * @example ['useState']
-   * @example 'React'
+   *
+   * @example Named imports
+   * `['useState']`
+   *
+   * @example Default import
+   * `'React'`
    */
   name: ImportName
   /**
    * Path for the import.
-   * @example '@kubb/core'
+   *
+   * @example
+   * `'@kubb/core'`
    */
   path: string
   /**
-   * Add type-only import prefix.
+   * Add a type-only import prefix.
    * - `true` generates `import type { Type } from './path'`
    * - `false` generates `import { Type } from './path'`
-   * @default false
    */
   isTypeOnly?: boolean | null
   /**
-   * Import entire module as namespace.
+   * Import the entire module as a namespace.
    * - `true` generates `import * as Name from './path'`
-   * - `false` generates standard import
-   * @default false
+   * - `false` generates a standard import
    */
   isNameSpace?: boolean | null
   /**
@@ -92,27 +96,31 @@ export type ExportNode = BaseNode & {
   kind: 'Export'
   /**
    * Export name(s) to be used. When omitted, generates a wildcard export.
-   * @example ['useState']
-   * @example 'React'
+   *
+   * @example Named exports
+   * `['useState']`
+   *
+   * @example Single export
+   * `'React'`
    */
   name?: string | Array<string> | null
   /**
    * Path for the export.
-   * @example '@kubb/core'
+   *
+   * @example
+   * `'@kubb/core'`
    */
   path: string
   /**
-   * Add type-only export prefix.
+   * Add a type-only export prefix.
    * - `true` generates `export type { Type } from './path'`
    * - `false` generates `export { Type } from './path'`
-   * @default false
    */
   isTypeOnly?: boolean | null
   /**
    * Export as an aliased namespace.
    * - `true` generates `export * as aliasName from './path'`
    * - `false` generates a standard export
-   * @default false
    */
   asAlias?: boolean | null
 }
@@ -138,22 +146,19 @@ export type SourceNode = BaseNode & {
   name?: string | null
   /**
    * Mark this source as a type-only export.
-   * @default false
    */
   isTypeOnly?: boolean | null
   /**
-   * Include `export` keyword in the generated source.
-   * @default false
+   * Include the `export` keyword in the generated source.
    */
   isExportable?: boolean | null
   /**
    * Include this source in barrel/index file generation.
-   * @default false
    */
   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.
+   * Child nodes that make up this source fragment, in DOM order.
+   * Use a {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -181,8 +186,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. Computed
-   * by `createFile`; callers do not need to provide it.
+   * Unique identifier derived from a SHA256 hash of the file path. `createFile`
+   * computes it, so callers do not need to provide it.
    */
   id: string
   /**
@@ -217,7 +222,7 @@ export type FileNode<TMeta extends object = object> = BaseNode & {
    */
   exports: Array<ExportNode>
   /**
-   * Optional metadata attached to this file (used by plugins for barrel generation etc.).
+   * Optional metadata attached to this file, read by plugins during barrel generation.
    */
   meta?: TMeta
   /**

package/src/nodes/function.ts

@@ -21,9 +21,6 @@ export type TypeExpression = string | TypeLiteralNode | IndexedAccessTypeNode
  * ```
  */
 export type TypeLiteralNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'TypeLiteral'
   /**
    * Members of the object type, rendered in order.
@@ -55,9 +52,6 @@ export type TypeLiteralNode = BaseNode & {
  * ```
  */
 export type IndexedAccessTypeNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'IndexedAccessType'
   /**
    * Name of the type being indexed, e.g. `'GetPetPathParams'`.
@@ -80,9 +74,6 @@ export type IndexedAccessTypeNode = BaseNode & {
  * ```
  */
 export type ObjectBindingPatternNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'ObjectBindingPattern'
   /**
    * Bound elements, rendered in order.
@@ -121,9 +112,6 @@ export type ObjectBindingPatternNode = BaseNode & {
  * `{ id, name? }: { id: string; name?: string } = {}`
  */
 export type FunctionParameterNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'FunctionParameter'
   /**
    * Parameter name, or an {@link ObjectBindingPatternNode} for a destructured group.
@@ -158,9 +146,6 @@ export type FunctionParameterNode = BaseNode & {
  * - `call`        → `(id, { method, url })` function call arguments
  */
 export type FunctionParametersNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'FunctionParameters'
   /**
    * Ordered parameter nodes.
@@ -174,9 +159,9 @@ export type FunctionParametersNode = BaseNode & {
 export type FunctionParamNode = FunctionParameterNode | FunctionParametersNode | TypeLiteralNode | IndexedAccessTypeNode | ObjectBindingPatternNode
 
 /**
- * Handler map keys, one per `FunctionParamNode` kind.
+ * Handler-map keys for the function-parameter printer, one per {@link FunctionParamNode} kind.
  */
-export type FunctionNodeType = 'functionParameter' | 'functionParameters' | 'typeLiteral' | 'indexedAccessType' | 'objectBindingPattern'
+export type FunctionParamKind = FunctionParamNode['kind']
 
 /**
  * Definition for the {@link TypeLiteralNode}.

package/src/nodes/index.ts

@@ -16,7 +16,7 @@ export type { ArrowFunctionNode, BreakNode, CodeNode, ConstNode, FunctionNode, J
 export type { ContentNode } from './content.ts'
 export type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
 export type {
-  FunctionNodeType,
+  FunctionParamKind,
   FunctionParameterNode,
   FunctionParametersNode,
   FunctionParamNode,