@kubb/ast 5.0.0-alpha.30 → 5.0.0-alpha.32

package/src/nodes/code.ts

@@ -0,0 +1,237 @@
+import type { BaseNode } from './base.ts'
+
+/**
+ * JSDoc documentation metadata attached to code declarations.
+ */
+export type JSDocNode = {
+  /**
+   * JSDoc comment lines. `undefined` entries are filtered out during rendering.
+   * @example ['@description A pet resource', '@deprecated']
+   */
+  comments?: Array<string | undefined>
+}
+
+/**
+ * AST node representing a TypeScript `const` declaration.
+ *
+ * Mirrors the props of the `Const` component from `@kubb/react-fabric`.
+ * The `children` prop of the component is represented as `nodes`.
+ *
+ * @example
+ * ```ts
+ * createConst({ name: 'pet', export: true, asConst: true })
+ * // export const pet = ... as const
+ * ```
+ */
+export type ConstNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Const'
+  /**
+   * Name of the constant declaration.
+   */
+  name: string
+  /**
+   * Whether the declaration should be exported.
+   * @default false
+   */
+  export?: boolean
+  /**
+   * Optional explicit type annotation.
+   * @example 'Pet'
+   */
+  type?: string
+  /**
+   * JSDoc documentation metadata.
+   */
+  JSDoc?: JSDocNode
+  /**
+   * Whether to append `as const` to the declaration.
+   * @default false
+   */
+  asConst?: boolean
+  /**
+   * Child nodes representing the value of the constant (children of the `Const` component).
+   * Each entry is either a structured {@link CodeNode} or a raw string expression.
+   */
+  nodes?: Array<CodeNode | string>
+}
+
+/**
+ * AST node representing a TypeScript `type` alias declaration.
+ *
+ * Mirrors the props of the `Type` component from `@kubb/react-fabric`.
+ * The `children` prop of the component is represented as `nodes`.
+ *
+ * @example
+ * ```ts
+ * createType({ name: 'Pet', export: true })
+ * // export type Pet = ...
+ * ```
+ */
+export type TypeNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Type'
+  /**
+   * Name of the type alias.
+   */
+  name: string
+  /**
+   * Whether the declaration should be exported.
+   * @default false
+   */
+  export?: boolean
+  /**
+   * JSDoc documentation metadata.
+   */
+  JSDoc?: JSDocNode
+  /**
+   * Child nodes representing the type body (children of the `Type` component).
+   * Each entry is either a structured {@link CodeNode} or a raw string expression.
+   */
+  nodes?: Array<CodeNode | string>
+}
+
+/**
+ * Convenience alias for {@link TypeNode}.
+ * @deprecated Use `TypeNode` directly.
+ */
+export type TypeDeclarationNode = TypeNode
+
+/**
+ * AST node representing a TypeScript `function` declaration.
+ *
+ * Mirrors the props of the `Function` component from `@kubb/react-fabric`.
+ * The `children` prop of the component is represented as `nodes`.
+ *
+ * @example
+ * ```ts
+ * createFunctionDeclaration({ name: 'getPet', export: true, async: true, returnType: 'Pet' })
+ * // export async function getPet(): Promise<Pet> { ... }
+ * ```
+ */
+export type FunctionNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Function'
+  /**
+   * Name of the function.
+   */
+  name: string
+  /**
+   * Whether the function is a default export.
+   * @default false
+   */
+  default?: boolean
+  /**
+   * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
+   */
+  params?: string
+  /**
+   * Whether the function should be exported.
+   * @default false
+   */
+  export?: boolean
+  /**
+   * Whether the function is async. When `true`, the return type is wrapped in `Promise<>`.
+   * @default false
+   */
+  async?: boolean
+  /**
+   * TypeScript generic type parameters.
+   * @example ['T', 'U extends string']
+   */
+  generics?: string | string[]
+  /**
+   * Return type annotation.
+   * @example 'Pet'
+   */
+  returnType?: string
+  /**
+   * JSDoc documentation metadata.
+   */
+  JSDoc?: JSDocNode
+  /**
+   * Child nodes representing the function body (children of the `Function` component).
+   * Each entry is either a structured {@link CodeNode} or a raw string statement.
+   */
+  nodes?: Array<CodeNode | string>
+}
+
+/**
+ * AST node representing a TypeScript arrow function (`const name = () => { ... }`).
+ *
+ * Mirrors the props of the `Function.Arrow` component from `@kubb/react-fabric`.
+ * The `children` prop of the component is represented as `nodes`.
+ *
+ * @example
+ * ```ts
+ * createArrowFunctionDeclaration({ name: 'getPet', export: true, singleLine: true })
+ * // export const getPet = () => ...
+ * ```
+ */
+export type ArrowFunctionNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'ArrowFunction'
+  /**
+   * Name of the arrow function (used as the `const` variable name).
+   */
+  name: string
+  /**
+   * Whether the function is a default export.
+   * @default false
+   */
+  default?: boolean
+  /**
+   * Function parameter list rendered as a string (e.g. from `FunctionParams.toConstructor()`).
+   */
+  params?: string
+  /**
+   * Whether the arrow function should be exported.
+   * @default false
+   */
+  export?: boolean
+  /**
+   * Whether the arrow function is async. When `true`, the return type is wrapped in `Promise<>`.
+   * @default false
+   */
+  async?: boolean
+  /**
+   * TypeScript generic type parameters.
+   * @example ['T', 'U extends string']
+   */
+  generics?: string | string[]
+  /**
+   * Return type annotation.
+   * @example 'Pet'
+   */
+  returnType?: string
+  /**
+   * JSDoc documentation metadata.
+   */
+  JSDoc?: JSDocNode
+  /**
+   * Render the arrow function body as a single-line expression.
+   * @default false
+   */
+  singleLine?: boolean
+  /**
+   * Child nodes representing the function body (children of the `Function.Arrow` component).
+   * Each entry is either a structured {@link CodeNode} or a raw string statement.
+   */
+  nodes?: Array<CodeNode | string>
+}
+
+/**
+ * Union of all code-generation AST nodes.
+ *
+ * These nodes mirror the JSX components from `@kubb/react-fabric` and are used as
+ * structured children in {@link SourceNode.nodes}.
+ */
+export type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode

package/src/nodes/file.ts

@@ -0,0 +1,235 @@
+import type { BaseNode } from './base.ts'
+import type { CodeNode } from './code.ts'
+
+/**
+ * Supported file extensions.
+ */
+export type Extname = '.ts' | '.js' | '.tsx' | '.json' | `.${string}`
+
+type ImportName = string | Array<string | { propertyName: string; name?: string }>
+
+/**
+ * Represents a language-agnostic import/dependency declaration.
+ *
+ * @example Named import (TypeScript: `import { useState } from 'react'`)
+ * ```ts
+ * createImport({ name: ['useState'], path: 'react' })
+ * ```
+ *
+ * @example Default import (TypeScript: `import React from 'react'`)
+ * ```ts
+ * createImport({ name: 'React', path: 'react' })
+ * ```
+ *
+ * @example Type-only import (TypeScript: `import type { FC } from 'react'`)
+ * ```ts
+ * createImport({ name: ['FC'], path: 'react', isTypeOnly: true })
+ * ```
+ *
+ * @example Namespace import (TypeScript: `import * as React from 'react'`)
+ * ```ts
+ * createImport({ name: 'React', path: 'react', isNameSpace: true })
+ * ```
+ */
+export type ImportNode = BaseNode & {
+  kind: 'Import'
+  /**
+   * Import name(s) to be used.
+   * @example ['useState']
+   * @example 'React'
+   */
+  name: ImportName
+  /**
+   * Path for the import.
+   * @example '@kubb/core'
+   */
+  path: string
+  /**
+   * Add type-only import prefix.
+   * - `true` generates `import type { Type } from './path'`
+   * - `false` generates `import { Type } from './path'`
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Import entire module as namespace.
+   * - `true` generates `import * as Name from './path'`
+   * - `false` generates standard import
+   * @default false
+   */
+  isNameSpace?: boolean
+  /**
+   * When set, the import path is resolved relative to this root.
+   */
+  root?: string
+}
+
+/**
+ * Represents a language-agnostic export/public API declaration.
+ *
+ * @example Named export (TypeScript: `export { Pets } from './Pets'`)
+ * ```ts
+ * createExport({ name: ['Pets'], path: './Pets' })
+ * ```
+ *
+ * @example Type-only export (TypeScript: `export type { Pet } from './Pet'`)
+ * ```ts
+ * createExport({ name: ['Pet'], path: './Pet', isTypeOnly: true })
+ * ```
+ *
+ * @example Wildcard export (TypeScript: `export * from './utils'`)
+ * ```ts
+ * createExport({ path: './utils' })
+ * ```
+ *
+ * @example Namespace alias (TypeScript: `export * as utils from './utils'`)
+ * ```ts
+ * createExport({ name: 'utils', path: './utils', asAlias: true })
+ * ```
+ */
+export type ExportNode = BaseNode & {
+  kind: 'Export'
+  /**
+   * Export name(s) to be used. When omitted, generates a wildcard export.
+   * @example ['useState']
+   * @example 'React'
+   */
+  name?: string | Array<string>
+  /**
+   * Path for the export.
+   * @example '@kubb/core'
+   */
+  path: string
+  /**
+   * Add type-only export prefix.
+   * - `true` generates `export type { Type } from './path'`
+   * - `false` generates `export { Type } from './path'`
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Export as an aliased namespace.
+   * - `true` generates `export * as aliasName from './path'`
+   * - `false` generates a standard export
+   * @default false
+   */
+  asAlias?: boolean
+}
+
+/**
+ * Represents a fragment of source code within a file.
+ *
+ * @example Named exportable source
+ * ```ts
+ * createSource({ name: 'Pet', value: 'export type Pet = { id: number }', isExportable: true, isIndexable: true })
+ * ```
+ *
+ * @example Inline unnamed code block
+ * ```ts
+ * createSource({ value: 'const x = 1' })
+ * ```
+ */
+export type SourceNode = BaseNode & {
+  kind: 'Source'
+  /**
+   * Optional name identifying this source (used for deduplication and barrel generation).
+   */
+  name?: string
+  /**
+   * The source code value.
+   */
+  value?: string
+  /**
+   * Mark this source as a type-only export.
+   * @default false
+   */
+  isTypeOnly?: boolean
+  /**
+   * Include `export` keyword in the generated source.
+   * @default false
+   */
+  isExportable?: boolean
+  /**
+   * Include this source in barrel/index file generation.
+   * @default false
+   */
+  isIndexable?: boolean
+  /**
+   * Structured child nodes representing the content of this source fragment.
+   * These correspond to the children of the `File.Source` component from `@kubb/react-fabric`
+   * (e.g. `ConstNode`, `TypeDeclarationNode`, `FunctionDeclarationNode`, `ArrowFunctionDeclarationNode`).
+   */
+  nodes?: Array<CodeNode>
+}
+
+/**
+ * Represents a fully resolved file in the AST.
+ *
+ * Created via `createFile()`, which computes the `id`, `name`, and `extname` from the input
+ * and deduplicates `imports`, `exports`, and `sources`.
+ *
+ * @example
+ * ```ts
+ * const file = createFile({
+ *   baseName: 'petStore.ts',
+ *   path: 'src/models/petStore.ts',
+ *   sources: [createSource({ name: 'Pet', value: 'export type Pet = { id: number }', isExportable: true })],
+ *   imports: [createImport({ name: ['z'], path: 'zod' })],
+ *   exports: [createExport({ name: ['Pet'], path: './petStore' })],
+ * })
+ * // file.id   = SHA256 hash of the path
+ * // file.name = 'petStore'
+ * // file.extname = '.ts'
+ * ```
+ */
+export type FileNode<TMeta extends object = object> = BaseNode & {
+  kind: 'File'
+  /**
+   * Unique identifier derived from a SHA256 hash of the file path.
+   * @default hash
+   */
+  id: string
+  /**
+   * File name without extension, derived from `baseName`.
+   * @link https://nodejs.org/api/path.html#pathformatpathobject
+   */
+  name: string
+  /**
+   * File base name, including extension.
+   * Based on UNIX basename: `${name}${extname}`
+   * @link https://nodejs.org/api/path.html#pathbasenamepath-suffix
+   */
+  baseName: `${string}.${string}`
+  /**
+   * Full qualified path to the file.
+   */
+  path: string
+  /**
+   * File extension extracted from `baseName`.
+   */
+  extname: Extname
+  /**
+   * Deduplicated list of source code fragments.
+   */
+  sources: Array<SourceNode>
+  /**
+   * Deduplicated list of import declarations.
+   */
+  imports: Array<ImportNode>
+  /**
+   * Deduplicated list of export declarations.
+   */
+  exports: Array<ExportNode>
+  /**
+   * Optional metadata attached to this file (used by plugins for barrel generation etc.).
+   */
+  meta?: TMeta
+  /**
+   * Optional banner prepended to the generated file content.
+   */
+  banner?: string
+  /**
+   * Optional footer appended to the generated file content.
+   */
+  footer?: string
+}

package/src/nodes/function.ts

@@ -1,19 +1,37 @@
 import type { BaseNode } from './base.ts'
 
 /**
- * AST node representing a language-agnostic type expression produced during parameter resolution.
- * Each language printer renders the variant into its own syntax.
+ * AST node representing a language-agnostic type expression used as a function parameter
+ * type annotation. Each language printer renders the variant into its own syntax.
  *
  * - `struct` — an inline anonymous type grouping named fields.
- *   TypeScript renders as `{ petId: string; name?: string }`, Python as a `TypedDict` reference.
+ *   TypeScript renders as `{ petId: string; name?: string }`.
  * - `member` — a single named field accessed from a named group type.
- *   TypeScript renders as `PathParams['petId']`, C# as `PathParams.PetId`.
+ *   TypeScript renders as `PathParams['petId']`.
+ *
+ * @example Reference variant
+ * ```ts
+ * createParamsType({ variant: 'reference', name: 'QueryParams' })
+ * // QueryParams
+ * ```
+ *
+ * @example Struct variant
+ * ```ts
+ * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
+ * // { petId: string }
+ * ```
+ *
+ * @example Member variant
+ * ```ts
+ * createParamsType({ variant: 'member', base: 'PathParams', key: 'petId' })
+ * // PathParams['petId']
+ * ```
  */
-export type TypeNode = BaseNode & {
+export type ParamsTypeNode = BaseNode & {
   /**
    * Node kind.
    */
-  kind: 'Type'
+  kind: 'ParamsType'
 } & (
     | {
         /**
@@ -35,7 +53,7 @@ export type TypeNode = BaseNode & {
         /**
          * Properties of the struct type.
          */
-        properties: Array<{ name: string; optional: boolean; type: TypeNode }>
+        properties: Array<{ name: string; optional: boolean; type: ParamsTypeNode }>
       }
     | {
         /**
@@ -79,19 +97,19 @@ export type FunctionParameterNode = BaseNode & {
    */
   name: string
   /**
-   * Type annotation as a structured {@link TypeNode}.
+   * Type annotation as a structured {@link ParamsTypeNode}.
    * Omit for untyped output.
    *
    * @example Reference type node
-   * `{ kind: 'Type', variant: 'reference', name: 'string' }` → `petId: string`
+   * `{ kind: 'ParamsType', variant: 'reference', name: 'string' }` → `petId: string`
    *
    * @example Struct type node
-   * `{ kind: 'Type', variant: 'struct', properties: [...] }` → `{ key: Type; other?: OtherType }`
+   * `{ kind: 'ParamsType', variant: 'struct', properties: [...] }` → `{ key: Type; other?: OtherType }`
    *
    * @example Member type node
-   * `{ kind: 'Type', variant: 'member', base: 'PathParams', key: 'petId' }` → `PathParams['petId']`
+   * `{ kind: 'ParamsType', variant: 'member', base: 'PathParams', key: 'petId' }` → `PathParams['petId']`
    */
-  type?: TypeNode
+  type?: ParamsTypeNode
   /**
    * When `true` the parameter is emitted as a rest parameter.
    *
@@ -147,7 +165,7 @@ export type ParameterGroupNode = BaseNode & {
    * Optional explicit type annotation for the whole group.
    * When absent, printers auto-compute it from `properties`.
    */
-  type?: TypeNode
+  type?: ParamsTypeNode
   /**
    * When `true`, `properties` are emitted as individual top-level parameters instead of
    * being wrapped in a single grouped construct.
@@ -191,11 +209,11 @@ export type FunctionParametersNode = BaseNode & {
 }
 
 /**
- * The four function-signature AST node variants.
+ * Union of all function-parameter AST node variants used by the function-parameter printer.
  */
-export type FunctionNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | TypeNode
+export type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode
 
 /**
- * Handler map keys — one per `FunctionNode` kind.
+ * Handler map keys — one per `FunctionParamNode` kind.
  */
-export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'type'
+export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'

package/src/nodes/index.ts

@@ -1,19 +1,25 @@
-import type { FunctionNode } from './function.ts'
+import type { ArrowFunctionNode, ConstNode, FunctionNode, TypeNode } from './code.ts'
+import type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
+import type { FunctionParamNode, ParamsTypeNode } from './function.ts'
 import type { OperationNode } from './operation.ts'
+import type { OutputNode } from './output.ts'
 import type { ParameterNode } from './parameter.ts'
 import type { PropertyNode } from './property.ts'
 import type { ResponseNode } from './response.ts'
-import type { RootNode } from './root.ts'
+import type { InputNode } from './root.ts'
 import type { SchemaNode } from './schema.ts'
 
 export type { BaseNode, NodeKind } from './base.ts'
-export type { FunctionNode, FunctionNodeType, FunctionParameterNode, FunctionParametersNode, ParameterGroupNode, TypeNode } from './function.ts'
+export type { ArrowFunctionNode, CodeNode, ConstNode, FunctionNode, JSDocNode, TypeDeclarationNode, TypeNode } from './code.ts'
+export type { ExportNode, FileNode, ImportNode, SourceNode } from './file.ts'
+export type { FunctionNodeType, FunctionParameterNode, FunctionParametersNode, FunctionParamNode, ParameterGroupNode, ParamsTypeNode } from './function.ts'
 export type { HttpStatusCode, MediaType, StatusCode } from './http.ts'
 export type { HttpMethod, OperationNode } from './operation.ts'
+export type { OutputNode } from './output.ts'
 export type { ParameterLocation, ParameterNode } from './parameter.ts'
 export type { PropertyNode } from './property.ts'
 export type { ResponseNode } from './response.ts'
-export type { RootMeta, RootNode } from './root.ts'
+export type { InputMeta, InputNode } from './root.ts'
 export type {
   ArraySchemaNode,
   ComplexSchemaType,
@@ -50,12 +56,31 @@ export type {
  * ```ts
  * function getKind(node: Node): string {
  *   switch (node.kind) {
- *     case 'Root':
- *       return 'root'
+ *     case 'Input':
+ *       return 'input'
+ *     case 'Output':
+ *       return 'output'
  *     default:
  *       return 'other'
  *   }
  * }
  * ```
  */
-export type Node = RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode | FunctionNode
+export type Node =
+  | InputNode
+  | OutputNode
+  | OperationNode
+  | SchemaNode
+  | PropertyNode
+  | ParameterNode
+  | ResponseNode
+  | FunctionParamNode
+  | FileNode
+  | ImportNode
+  | ExportNode
+  | SourceNode
+  | ConstNode
+  | TypeNode
+  | ParamsTypeNode
+  | FunctionNode
+  | ArrowFunctionNode

package/src/nodes/output.ts

@@ -0,0 +1,26 @@
+import type { BaseNode } from './base.ts'
+import type { FileNode } from './file.ts'
+
+/**
+ * Output AST node that groups all generated file output for one API document.
+ *
+ * Produced by generators and consumed by the build pipeline to write files.
+ *
+ * @example
+ * ```ts
+ * const output: OutputNode = {
+ *   kind: 'Output',
+ *   files: [],
+ * }
+ * ```
+ */
+export type OutputNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Output'
+  /**
+   * Generated file nodes.
+   */
+  files: Array<FileNode>
+}