@kubb/ast 5.0.0-beta.6 → 5.0.0-beta.61

package/src/nodes/code.ts

@@ -1,3 +1,4 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 
 /**
@@ -6,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>
 }
@@ -24,9 +29,6 @@ export type JSDocNode = {
  * ```
  */
 export type ConstNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Const'
   /**
    * Name of the constant declaration.
@@ -34,26 +36,26 @@ export type ConstNode = BaseNode & {
   name: string
   /**
    * Whether the declaration should be exported.
-   * @default false
    */
-  export?: boolean
+  export?: boolean | null
   /**
-   * Optional explicit type annotation.
-   * @example 'Pet'
+   * Explicit type annotation.
+   *
+   * @example Type reference
+   * `'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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -71,9 +73,6 @@ export type ConstNode = BaseNode & {
  * ```
  */
 export type TypeNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Type'
   /**
    * Name of the type alias.
@@ -81,26 +80,19 @@ export type TypeNode = BaseNode & {
   name: string
   /**
    * 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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
 
-/**
- * Convenience alias for {@link TypeNode}.
- * @deprecated Use `TypeNode` directly.
- */
-export type TypeDeclarationNode = TypeNode
-
 /**
  * AST node representing a TypeScript `function` declaration.
  *
@@ -114,9 +106,6 @@ export type TypeDeclarationNode = TypeNode
  * ```
  */
 export type FunctionNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Function'
   /**
    * Name of the function.
@@ -124,40 +113,41 @@ export type FunctionNode = BaseNode & {
   name: string
   /**
    * 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']
+   *
+   * @example Constrained generics
+   * `['T', 'U extends string']`
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
-   * @example 'Pet'
+   *
+   * @example Type reference
+   * `'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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -175,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).
@@ -185,45 +172,45 @@ export type ArrowFunctionNode = BaseNode & {
   name: string
   /**
    * 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']
+   *
+   * @example Constrained generics
+   * `['T', 'U extends string']`
    */
-  generics?: string | string[]
+  generics?: string | Array<string> | null
   /**
    * Return type annotation.
-   * @example 'Pet'
+   *
+   * @example Type reference
+   * `'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.
+   * Each entry is a {@link CodeNode}. Use {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -241,9 +228,6 @@ export type ArrowFunctionNode = BaseNode & {
  * ```
  */
 export type TextNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Text'
   /**
    * The raw string content.
@@ -254,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
@@ -266,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
@@ -285,9 +265,6 @@ export type BreakNode = BaseNode & {
  * ```
  */
 export type JsxNode = BaseNode & {
-  /**
-   * Node kind.
-   */
   kind: 'Jsx'
   /**
    * The raw JSX string content.
@@ -302,3 +279,117 @@ export type JsxNode = BaseNode & {
  * structured children in {@link SourceNode.nodes}.
  */
 export type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode | TextNode | BreakNode | JsxNode
+
+/**
+ * Definition for the {@link ConstNode}.
+ */
+export const constDef = defineNode<ConstNode>({ kind: 'Const' })
+
+/**
+ * Creates a `ConstNode` representing a TypeScript `const` declaration.
+ *
+ * @example Exported constant with type and `as const`
+ * ```ts
+ * createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true })
+ * // export const pets: Pet[] = ... as const
+ * ```
+ */
+export const createConst = constDef.create
+
+/**
+ * Definition for the {@link TypeNode}.
+ */
+export const typeDef = defineNode<TypeNode>({ kind: 'Type' })
+
+/**
+ * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
+ *
+ * @example
+ * ```ts
+ * createType({ name: 'Pet', export: true })
+ * // export type Pet = ...
+ * ```
+ */
+export const createType = typeDef.create
+
+/**
+ * Definition for the {@link FunctionNode}.
+ */
+export const functionDef = defineNode<FunctionNode>({ kind: 'Function' })
+
+/**
+ * Creates a `FunctionNode` representing a TypeScript `function` declaration.
+ *
+ * @example
+ * ```ts
+ * createFunction({ name: 'fetchPet', export: true, async: true, returnType: 'Pet' })
+ * // export async function fetchPet(): Promise<Pet> { ... }
+ * ```
+ */
+export const createFunction = functionDef.create
+
+/**
+ * Definition for the {@link ArrowFunctionNode}.
+ */
+export const arrowFunctionDef = defineNode<ArrowFunctionNode>({ kind: 'ArrowFunction' })
+
+/**
+ * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
+ *
+ * @example
+ * ```ts
+ * createArrowFunction({ name: 'double', export: true, params: 'n: number', singleLine: true })
+ * // export const double = (n: number) => ...
+ * ```
+ */
+export const createArrowFunction = arrowFunctionDef.create
+
+/**
+ * Definition for the {@link TextNode}.
+ */
+export const textDef = defineNode<TextNode, string>({ kind: 'Text', build: (value) => ({ value }) })
+
+/**
+ * Creates a {@link TextNode} representing a raw string fragment in the source output.
+ *
+ * @example
+ * ```ts
+ * createText('return fetch(id)')
+ * // { kind: 'Text', value: 'return fetch(id)' }
+ * ```
+ */
+export const createText = textDef.create
+
+/**
+ * Definition for the {@link BreakNode}.
+ */
+export const breakDef = defineNode<BreakNode, void>({ kind: 'Break', build: () => ({}) })
+
+/**
+ * Creates a {@link BreakNode} representing a line break in the source output.
+ *
+ * @example
+ * ```ts
+ * createBreak()
+ * // { kind: 'Break' }
+ * ```
+ */
+export function createBreak(): BreakNode {
+  return breakDef.create()
+}
+
+/**
+ * Definition for the {@link JsxNode}.
+ */
+export const jsxDef = defineNode<JsxNode, string>({ kind: 'Jsx', build: (value) => ({ value }) })
+
+/**
+ * Creates a {@link JsxNode} representing a raw JSX fragment in the source output.
+ *
+ * @example
+ * ```ts
+ * createJsx('<>\n  <a href={href}>Open</a>\n</>')
+ * // { kind: 'Jsx', value: '<>\n  <a href={href}>Open</a>\n</>' }
+ * ```
+ */
+export const createJsx = jsxDef.create

package/src/nodes/content.ts

@@ -0,0 +1,56 @@
+import { defineNode } from '../node.ts'
+import type { BaseNode } from './base.ts'
+import type { SchemaNode } from './schema.ts'
+
+/**
+ * AST node representing one content-type entry of a request body or response.
+ *
+ * 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
+ * const content: ContentNode = {
+ *   kind: 'Content',
+ *   contentType: 'application/json',
+ *   schema: createSchema({ type: 'string' }),
+ * }
+ * ```
+ */
+export type ContentNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Content'
+  /**
+   * The content type for this entry (e.g. `'application/json'`).
+   */
+  contentType: string
+  /**
+   * Body schema for this content type.
+   */
+  schema?: SchemaNode
+  /**
+   * Property keys to exclude from the generated type via `Omit<Type, Keys>`.
+   * Set when a referenced schema has `readOnly`/`writeOnly` fields that should be omitted.
+   */
+  keysToOmit?: Array<string> | null
+}
+
+/**
+ * Loosely-typed content entry accepted by the builders, normalized into a {@link ContentNode}.
+ */
+export type UserContent = Omit<ContentNode, 'kind'>
+
+/**
+ * Definition for the {@link ContentNode}.
+ */
+export const contentDef = defineNode<ContentNode, UserContent>({
+  kind: 'Content',
+  children: ['schema'],
+})
+
+/**
+ * Creates a `ContentNode` for a single request-body or response content type.
+ */
+export const createContent = contentDef.create

package/src/nodes/file.ts

@@ -1,10 +1,11 @@
+import { defineNode } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { CodeNode } from './code.ts'
 
 /**
  * Supported file extensions.
  */
-export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
+type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
 
 type ImportName = string | Array<string | { propertyName: string; name?: string }>
 
@@ -35,33 +36,37 @@ 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
+  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
+  isNameSpace?: boolean | null
   /**
    * When set, the import path is resolved relative to this root.
    */
-  root?: string
+  root?: string | null
 }
 
 /**
@@ -91,29 +96,33 @@ 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>
+  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
+  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,25 +143,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
+   * Include the `export` keyword in the generated source.
    */
-  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.
+   * Child nodes that make up this source fragment, in DOM order.
+   * Use a {@link TextNode} for raw string content.
    */
   nodes?: Array<CodeNode>
 }
@@ -180,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.
-   * @default hash
+   * Unique identifier derived from a SHA256 hash of the file path. `createFile`
+   * computes it, so callers do not need to provide it.
    */
   id: string
   /**
@@ -216,15 +222,70 @@ 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
   /**
    * 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
 }
+
+/**
+ * Definition for the {@link ImportNode}.
+ */
+export const importDef = defineNode<ImportNode>({ kind: 'Import' })
+
+/**
+ * Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
+ *
+ * @example Named import
+ * ```ts
+ * createImport({ name: ['useState'], path: 'react' })
+ * // import { useState } from 'react'
+ * ```
+ */
+export const createImport = importDef.create
+
+/**
+ * Definition for the {@link ExportNode}.
+ */
+export const exportDef = defineNode<ExportNode>({ kind: 'Export' })
+
+/**
+ * Creates an `ExportNode` representing a language-agnostic export/public API declaration.
+ *
+ * @example Named export
+ * ```ts
+ * createExport({ name: ['Pet'], path: './Pet' })
+ * // export { Pet } from './Pet'
+ * ```
+ */
+export const createExport = exportDef.create
+
+/**
+ * Definition for the {@link SourceNode}.
+ */
+export const sourceDef = defineNode<SourceNode>({ kind: 'Source' })
+
+/**
+ * Creates a `SourceNode` representing a fragment of source code within a file.
+ *
+ * @example
+ * ```ts
+ * createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
+ * ```
+ */
+export const createSource = sourceDef.create
+
+/**
+ * Definition for the {@link FileNode}. The fully resolved builder lives in
+ * `createFile`, so this definition only supplies the guard.
+ */
+export const fileDef = defineNode<FileNode>({ kind: 'File' })