@kubb/ast 5.0.0-alpha.9 → 5.0.0-beta.75

package/src/nodes/code.ts

@@ -0,0 +1,304 @@
+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/renderer-jsx`.
+ * 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 a {@link CodeNode}; use {@link TextNode} for raw string content.
+   */
+  nodes?: Array<CodeNode>
+}
+
+/**
+ * AST node representing a TypeScript `type` alias declaration.
+ *
+ * Mirrors the props of the `Type` component from `@kubb/renderer-jsx`.
+ * 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 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.
+ *
+ * Mirrors the props of the `Function` component from `@kubb/renderer-jsx`.
+ * 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 a {@link CodeNode}; use {@link TextNode} for raw string content.
+   */
+  nodes?: Array<CodeNode>
+}
+
+/**
+ * AST node representing a TypeScript arrow function (`const name = () => { ... }`).
+ *
+ * Mirrors the props of the `Function.Arrow` component from `@kubb/renderer-jsx`.
+ * 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 a {@link CodeNode}; use {@link TextNode} for raw string content.
+   */
+  nodes?: Array<CodeNode>
+}
+
+/**
+ * AST node representing a raw text/string fragment in the source output.
+ *
+ * Used instead of bare `string` values so that all entries in `nodes` arrays
+ * are typed `CodeNode` objects rather than a mixed `CodeNode | string` union.
+ *
+ * @example
+ * ```ts
+ * createText('return fetch(id)')
+ * // { kind: 'Text', value: 'return fetch(id)' }
+ * ```
+ */
+export type TextNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Text'
+  /**
+   * The raw string content.
+   */
+  value: string
+}
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * createBreak()
+ * // { kind: 'Break' }
+ * // prints as '' → blank line when surrounded by other nodes
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```ts
+ * createJsx('<>\n  <a href={href}>Open</a>\n</>')
+ * // { kind: 'Jsx', value: '<>\n  <a href={href}>Open</a>\n</>' }
+ * ```
+ */
+export type JsxNode = BaseNode & {
+  /**
+   * Node kind.
+   */
+  kind: 'Jsx'
+  /**
+   * The raw JSX string content.
+   */
+  value: string
+}
+
+/**
+ * Union of all code-generation AST nodes.
+ *
+ * These nodes mirror the JSX components from `@kubb/renderer-jsx` and are used as
+ * structured children in {@link SourceNode.nodes}.
+ */
+export type CodeNode = ConstNode | TypeNode | FunctionNode | ArrowFunctionNode | TextNode | BreakNode | JsxNode

package/src/nodes/file.ts

@@ -0,0 +1,230 @@
+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', nodes: [createText('export type Pet = { id: number }')], isExportable: true, isIndexable: true })
+ * ```
+ *
+ * @example Inline unnamed code block
+ * ```ts
+ * createSource({ nodes: [createText('const x = 1')] })
+ * ```
+ */
+export type SourceNode = BaseNode & {
+  kind: 'Source'
+  /**
+   * Optional name identifying this source (used for deduplication and barrel generation).
+   */
+  name?: 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, in DOM order.
+   * Each entry is a {@link CodeNode}; use {@link TextNode} for raw string content.
+   */
+  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', nodes: [createText('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
+}