@kubb/ast 5.0.0-beta.63 → 5.0.0-beta.64

package/src/nodes/file.ts

@@ -1,380 +0,0 @@
-import { hash } from 'node:crypto'
-import path from 'node:path'
-import { trimExtName } from '@internals/utils'
-import { defineNode } from '../defineNode.ts'
-import { extractStringsFromNodes } from '../utils/extractStringsFromNodes.ts'
-import { combineExports, combineImports, combineSources } from '../utils/fileMerge.ts'
-import type { BaseNode } from './base.ts'
-import type { CodeNode } from './code.ts'
-
-/**
- * Supported file extensions.
- */
-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 Named imports
-   * `['useState']`
-   *
-   * @example Default import
-   * `'React'`
-   */
-  name: ImportName
-  /**
-   * Path for the import.
-   *
-   * @example
-   * `'@kubb/core'`
-   */
-  path: string
-  /**
-   * Add a type-only import prefix.
-   * - `true` generates `import type { Type } from './path'`
-   * - `false` generates `import { Type } from './path'`
-   */
-  isTypeOnly?: boolean | null
-  /**
-   * Import the entire module as a namespace.
-   * - `true` generates `import * as Name from './path'`
-   * - `false` generates a standard import
-   */
-  isNameSpace?: boolean | null
-  /**
-   * When set, the import path is resolved relative to this root.
-   */
-  root?: string | null
-}
-
-/**
- * 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 Named exports
-   * `['useState']`
-   *
-   * @example Single export
-   * `'React'`
-   */
-  name?: string | Array<string> | null
-  /**
-   * Path for the export.
-   *
-   * @example
-   * `'@kubb/core'`
-   */
-  path: string
-  /**
-   * Add a type-only export prefix.
-   * - `true` generates `export type { Type } from './path'`
-   * - `false` generates `export { Type } from './path'`
-   */
-  isTypeOnly?: boolean | null
-  /**
-   * Export as an aliased namespace.
-   * - `true` generates `export * as aliasName from './path'`
-   * - `false` generates a standard export
-   */
-  asAlias?: boolean | null
-}
-
-/**
- * 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 | null
-  /**
-   * Mark this source as a type-only export.
-   */
-  isTypeOnly?: boolean | null
-  /**
-   * Include the `export` keyword in the generated source.
-   */
-  isExportable?: boolean | null
-  /**
-   * Include this source in barrel/index file generation.
-   */
-  isIndexable?: boolean | null
-  /**
-   * Child nodes that make up this source fragment, in DOM order.
-   * Use a {@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. `createFile`
-   * computes it, so callers do not need to provide it.
-   */
-  id: string
-  /**
-   * File name without extension, derived from `baseName`.
-   *
-   * @see https://nodejs.org/api/path.html#pathformatpathobject
-   */
-  name: string
-  /**
-   * File base name, including extension, shaped like `${name}${extname}`.
-   *
-   * @see 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, 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 | null
-  /**
-   * Optional footer appended to the generated file content.
-   * Accepts `null` so `resolver.resolveFooter()` results can be passed directly.
-   */
-  footer?: string | null
-}
-
-/**
- * Definition for the {@link ImportNode}.
- */
-export const importDef = defineNode<ImportNode>({ kind: 'Import' })
-
-/**
- * Definition for the {@link ExportNode}.
- */
-export const exportDef = defineNode<ExportNode>({ kind: 'Export' })
-
-/**
- * Definition for the {@link SourceNode}.
- */
-export const sourceDef = defineNode<SourceNode>({ kind: 'Source' })
-
-/**
- * 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' })
-
-/**
- * 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
-
-/**
- * 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
-
-/**
- * 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
-
-/**
- * Input descriptor for {@link createFile}, before `id`, `name`, and `extname` are computed
- * and `imports`/`exports`/`sources` are deduplicated.
- */
-export type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>, 'kind' | 'id' | 'name' | 'extname' | 'imports' | 'exports' | 'sources'> &
-  Pick<Partial<FileNode<TMeta>>, 'imports' | 'exports' | 'sources'>
-
-/**
- * Creates a fully resolved `FileNode` from a file input descriptor.
- *
- * Computes:
- * - `id` SHA256 hash of the file path
- * - `name` `baseName` without extension
- * - `extname` extension extracted from `baseName`
- *
- * Deduplicates:
- * - `sources` via `combineSources`
- * - `exports` via `combineExports`
- * - `imports` via `combineImports` (also filters unused imports)
- *
- * @throws {Error} when `baseName` has no extension.
- *
- * @example
- * ```ts
- * const file = createFile({
- *   baseName: 'petStore.ts',
- *   path: 'src/models/petStore.ts',
- *   sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
- *   imports: [createImport({ name: ['z'], path: 'zod' })],
- *   exports: [createExport({ name: ['Pet'], path: './petStore' })],
- * })
- * // file.id      = SHA256 hash of 'src/models/petStore.ts'
- * // file.name    = 'petStore'
- * // file.extname = '.ts'
- * ```
- */
-export function createFile<TMeta extends object = object>(input: UserFileNode<TMeta>): FileNode<TMeta> {
-  const rawExtname = path.extname(input.baseName)
-  // Handle dotfile basename like '.ts' where path.extname returns ''
-  const extname = (rawExtname || (input.baseName.startsWith('.') ? input.baseName : '')) as `.${string}`
-  if (!extname) {
-    throw new Error(`No extname found for ${input.baseName}`)
-  }
-
-  const source = (input.sources ?? [])
-    .flatMap((item) => item.nodes ?? [])
-    .map((node) => extractStringsFromNodes([node]))
-    .filter(Boolean)
-    .join('\n\n')
-  const resolvedExports = input.exports?.length ? combineExports(input.exports) : []
-  const combinedImports = input.imports?.length ? combineImports(input.imports, resolvedExports, source || undefined) : []
-  const localNames = new Set((input.sources ?? []).map((item) => item.name).filter((name): name is string => Boolean(name)))
-  const nameOf = (item: string | { propertyName: string; name?: string }): string => (typeof item === 'string' ? item : (item.name ?? item.propertyName))
-  // Drop self-imports. Consolidating output (`mode: 'file'`) can place a symbol's
-  // definition and a cross-file import of it in the same file. The first pass catches imports that
-  // resolve to this file's own path. The second drops imports of names the file already defines,
-  // the case consolidation produces when the import path no longer matches `input.path`. Sources
-  // stay intact, so the local definition remains. Bare specifiers like `'zod'` never match a path.
-  const resolvedImports = combinedImports
-    .filter((imp) => imp.path !== input.path)
-    .flatMap((imp) => {
-      if (!Array.isArray(imp.name)) {
-        return typeof imp.name === 'string' && localNames.has(imp.name) ? [] : [imp]
-      }
-      const kept = imp.name.filter((item) => !localNames.has(nameOf(item)))
-      if (!kept.length) return []
-      return [kept.length === imp.name.length ? imp : { ...imp, name: kept }]
-    })
-  const resolvedSources = input.sources?.length ? combineSources(input.sources) : []
-
-  return {
-    kind: 'File',
-    ...input,
-    id: hash('sha256', input.path, 'hex'),
-    name: trimExtName(input.baseName),
-    extname,
-    imports: resolvedImports,
-    exports: resolvedExports,
-    sources: resolvedSources,
-    meta: input.meta ?? ({} as TMeta),
-  }
-}

package/src/nodes/function.ts

@@ -1,283 +0,0 @@
-import { defineNode } from '../defineNode.ts'
-import type { BaseNode } from './base.ts'
-
-/**
- * A language-agnostic type expression used as a function parameter type annotation.
- *
- * - a plain `string` is a type reference rendered as-is, e.g. `'string'`, `'QueryParams'`, `'Partial<Config>'`
- * - a {@link TypeLiteralNode} is an inline anonymous type, e.g. `{ petId: string; name?: string }`
- * - an {@link IndexedAccessTypeNode} is a single field accessed from a named type, e.g. `PathParams['petId']`
- */
-export type TypeExpression = string | TypeLiteralNode | IndexedAccessTypeNode
-
-/**
- * AST node for an inline anonymous object type grouping named fields.
- * TypeScript renders as `{ key: Type; other?: OtherType }`.
- *
- * @example
- * ```ts
- * createTypeLiteral({ members: [{ name: 'petId', type: 'string', optional: false }] })
- * // { petId: string }
- * ```
- */
-export type TypeLiteralNode = BaseNode & {
-  kind: 'TypeLiteral'
-  /**
-   * Members of the object type, rendered in order.
-   */
-  members: Array<{
-    /**
-     * Member key.
-     */
-    name: string
-    /**
-     * Member type expression.
-     */
-    type: TypeExpression
-    /**
-     * Whether the member is optional, rendered with `?`.
-     */
-    optional?: boolean
-  }>
-}
-
-/**
- * AST node for a single field accessed from a named group type.
- * TypeScript renders as `target['key']`.
- *
- * @example
- * ```ts
- * createIndexedAccessType({ target: 'GetPetPathParams', key: 'petId' })
- * // GetPetPathParams['petId']
- * ```
- */
-export type IndexedAccessTypeNode = BaseNode & {
-  kind: 'IndexedAccessType'
-  /**
-   * Name of the type being indexed, e.g. `'GetPetPathParams'`.
-   */
-  target: string
-  /**
-   * Field key to access, e.g. `'petId'`.
-   */
-  key: string
-}
-
-/**
- * AST node for an object destructuring binding, used as the name of a grouped function parameter.
- * TypeScript renders as `{ id, name }` or `{ id: renamed }` when `propertyName` differs.
- *
- * @example
- * ```ts
- * createObjectBindingPattern({ elements: [{ name: 'id' }, { name: 'name' }] })
- * // { id, name }
- * ```
- */
-export type ObjectBindingPatternNode = BaseNode & {
-  kind: 'ObjectBindingPattern'
-  /**
-   * Bound elements, rendered in order.
-   */
-  elements: Array<{
-    /**
-     * Local binding name.
-     */
-    name: string
-    /**
-     * Source key when it differs from the binding name, rendered as `propertyName: name`.
-     */
-    propertyName?: string
-  }>
-}
-
-/**
- * AST node for one function parameter.
- *
- * A simple parameter has a `string` name. A destructured group has an
- * {@link ObjectBindingPatternNode} name paired with a {@link TypeLiteralNode} type.
- *
- * @example Required parameter
- * `name: Type`
- *
- * @example Optional parameter
- * `name?: Type`
- *
- * @example Parameter with default value
- * `name: Type = defaultValue`
- *
- * @example Rest parameter
- * `...name: Type[]`
- *
- * @example Destructured group
- * `{ id, name? }: { id: string; name?: string } = {}`
- */
-export type FunctionParameterNode = BaseNode & {
-  kind: 'FunctionParameter'
-  /**
-   * Parameter name, or an {@link ObjectBindingPatternNode} for a destructured group.
-   */
-  name: string | ObjectBindingPatternNode
-  /**
-   * Type annotation as a {@link TypeExpression}. Omit for untyped output.
-   */
-  type?: TypeExpression
-  /**
-   * Whether the parameter is optional, rendered with `?`.
-   */
-  optional?: boolean
-  /**
-   * Default value, written verbatim after `=`. Commonly `'{}'` for a destructured group.
-   */
-  default?: string
-  /**
-   * When `true` the parameter is emitted as a rest parameter, e.g. `...name: Type[]`.
-   */
-  rest?: boolean
-}
-
-/**
- * AST node for a complete function parameter list.
- *
- * Printers are responsible for sorting (`required` → `optional` → `defaulted`).
- * Nodes are plain immutable data.
- *
- * Renders differently depending on the output mode:
- * - `declaration` → `(id: string, config: Config = {})` function declaration parameters
- * - `call`        → `(id, { method, url })` function call arguments
- */
-export type FunctionParametersNode = BaseNode & {
-  kind: 'FunctionParameters'
-  /**
-   * Ordered parameter nodes.
-   */
-  params: ReadonlyArray<FunctionParameterNode>
-}
-
-/**
- * Union of all function-parameter AST node variants used by the function-parameter printer.
- */
-export type FunctionParamNode = FunctionParameterNode | FunctionParametersNode | TypeLiteralNode | IndexedAccessTypeNode | ObjectBindingPatternNode
-
-/**
- * Handler-map keys for the function-parameter printer, one per {@link FunctionParamNode} kind.
- */
-export type FunctionParamKind = FunctionParamNode['kind']
-
-/**
- * Definition for the {@link TypeLiteralNode}.
- */
-export const typeLiteralDef = defineNode<TypeLiteralNode, Pick<TypeLiteralNode, 'members'>>({ kind: 'TypeLiteral' })
-
-/**
- * Definition for the {@link IndexedAccessTypeNode}.
- */
-export const indexedAccessTypeDef = defineNode<IndexedAccessTypeNode, Omit<IndexedAccessTypeNode, 'kind'>>({ kind: 'IndexedAccessType' })
-
-/**
- * Definition for the {@link ObjectBindingPatternNode}.
- */
-export const objectBindingPatternDef = defineNode<ObjectBindingPatternNode, Pick<ObjectBindingPatternNode, 'elements'>>({ kind: 'ObjectBindingPattern' })
-
-/**
- * Plain property descriptor for a destructured group built by {@link createFunctionParameter}.
- */
-type FunctionParameterProperty = {
-  name: string
-  type: TypeExpression
-  optional?: boolean
-}
-
-type FunctionParameterInput =
-  | { name: string; type?: TypeExpression; optional?: boolean; default?: string; rest?: boolean }
-  | { properties: Array<FunctionParameterProperty>; optional?: boolean; default?: string }
-
-/**
- * Definition for the {@link FunctionParameterNode}. `optional` defaults to `false`.
- * Passing `properties` builds a destructured group: an {@link ObjectBindingPatternNode} name
- * paired with a {@link TypeLiteralNode} type.
- */
-export const functionParameterDef = defineNode<FunctionParameterNode, FunctionParameterInput>({
-  kind: 'FunctionParameter',
-  build: (input) => {
-    if ('properties' in input) {
-      return {
-        name: createObjectBindingPattern({ elements: input.properties.map((p) => ({ name: p.name })) }),
-        type: createTypeLiteral({ members: input.properties.map((p) => ({ name: p.name, type: p.type, optional: p.optional ?? false })) }),
-        optional: input.optional ?? false,
-        ...(input.default !== undefined ? { default: input.default } : {}),
-      }
-    }
-    return { optional: false, ...input }
-  },
-})
-
-/**
- * Definition for the {@link FunctionParametersNode}.
- */
-export const functionParametersDef = defineNode<FunctionParametersNode, Partial<Omit<FunctionParametersNode, 'kind'>>>({
-  kind: 'FunctionParameters',
-  defaults: { params: [] },
-})
-
-/**
- * Creates a {@link TypeLiteralNode} representing an inline anonymous object type.
- *
- * @example
- * ```ts
- * createTypeLiteral({ members: [{ name: 'petId', type: 'string', optional: false }] })
- * // { petId: string }
- * ```
- */
-export const createTypeLiteral = typeLiteralDef.create
-
-/**
- * Creates an {@link IndexedAccessTypeNode} representing a single field accessed from a named type.
- *
- * @example
- * ```ts
- * createIndexedAccessType({ target: 'DeletePetPathParams', key: 'petId' })
- * // DeletePetPathParams['petId']
- * ```
- */
-export const createIndexedAccessType = indexedAccessTypeDef.create
-
-/**
- * Creates an {@link ObjectBindingPatternNode} for a destructured parameter binding.
- *
- * @example
- * ```ts
- * createObjectBindingPattern({ elements: [{ name: 'id' }, { name: 'name' }] })
- * // { id, name }
- * ```
- */
-export const createObjectBindingPattern = objectBindingPatternDef.create
-
-/**
- * Creates a `FunctionParameterNode`. `optional` defaults to `false`.
- *
- * @example Optional param
- * ```ts
- * createFunctionParameter({ name: 'params', type: 'QueryParams', optional: true })
- * // → params?: QueryParams
- * ```
- *
- * @example Destructured group
- * ```ts
- * createFunctionParameter({ properties: [{ name: 'id', type: 'string' }, { name: 'name', type: 'string', optional: true }], default: '{}' })
- * // → { id, name }: { id: string; name?: string } = {}
- * ```
- */
-export const createFunctionParameter = functionParameterDef.create
-
-/**
- * Creates a `FunctionParametersNode` from an ordered list of parameters.
- *
- * @example
- * ```ts
- * const empty = createFunctionParameters()
- * // { kind: 'FunctionParameters', params: [] }
- * ```
- */
-export function createFunctionParameters(props: Partial<Omit<FunctionParametersNode, 'kind'>> = {}): FunctionParametersNode {
-  return functionParametersDef.create(props)
-}