@stacksjs/dtsx/dist/src/transformers.d.ts

A modern, fast .d.ts generation tool, powered by Bun.

import type { Declaration, DeclarationKind, ParameterDeclaration } from './types';
import type { Plugin } from './plugins';
/**
 * Create a new declaration with defaults
 */
export declare function createDeclaration(kind: DeclarationKind, name: string, text: string, options?: Partial<Omit<Declaration, 'kind' | 'name' | 'text'>>): Declaration;
/**
 * Clone a declaration (deep copy).
 * Uses the structured-clone algorithm where available — typically 3-5× faster
 * than the JSON round-trip and correctly preserves nested arrays / Sets.
 * Falls back to JSON for environments without structuredClone.
 */
export declare function cloneDeclaration(decl: Declaration): Declaration;
/**
 * Walk declarations with a visitor
 */
export declare function walkDeclarations(declarations: Declaration[], visitor: DeclarationVisitor, parent?: Declaration | null): void;
/**
 * Find declarations matching a predicate
 */
export declare function findDeclarations(declarations: Declaration[], predicate: (decl: Declaration) => boolean): Declaration[];
/**
 * Map declarations with a transformer
 */
export declare function mapDeclarations(declarations: Declaration[], transformer: Transformer, context: Omit<TransformerContext, 'index' | 'total' | 'allDeclarations'>): Promise<Declaration[]>;
/**
 * Compose multiple transformers into one
 */
export declare function composeTransformers(...transformers: Transformer[]): Transformer;
/**
 * Create a transformer that only applies to specific declaration kinds
 */
export declare function filterByKind(kinds: DeclarationKind | DeclarationKind[], transformer: Transformer): Transformer;
/**
 * Create a transformer that only applies when a predicate is true
 */
export declare function filterByPredicate(predicate: (decl: Declaration) => boolean, transformer: Transformer): Transformer;
/**
 * Create a transformer plugin from transformers
 */
export declare function createTransformerPlugin(options: {
  name: string
  version?: string
  description?: string
  /** Transform source code before parsing */
  beforeParse?: TextTransformer
  /** Transform declarations */
  transform?: Transformer
  /** Transform generated .d.ts content after generation */
  afterGenerate?: TextTransformer
}): Plugin;
/**
 * Rename declarations matching a pattern
 */
export declare function createRenameTransformer(pattern: string | RegExp, replacement: string | ((_match: string, _decl: Declaration) => string)): Transformer;
/**
 * Add a prefix to declaration names
 */
export declare function createPrefixTransformer(prefix: string, filter?: (decl: Declaration) => boolean): Transformer;
/**
 * Add a suffix to declaration names
 */
export declare function createSuffixTransformer(suffix: string, filter?: (decl: Declaration) => boolean): Transformer;
/**
 * Remove declarations by name pattern
 */
export declare function createRemoveTransformer(pattern: string | RegExp | ((_decl: Declaration) => boolean)): Transformer;
/**
 * Add JSDoc comments to declarations
 */
export declare function createJSDocTransformer(getJSDoc: (decl: Declaration) => string | string[] | null | undefined): Transformer;
/**
 * Modify type annotations
 */
export declare function createTypeTransformer(transformer: (type: string, decl: Declaration) => string | null | undefined): Transformer;
/**
 * Modify return types of functions
 */
export declare function createReturnTypeTransformer(transformer: (returnType: string, decl: Declaration) => string | null | undefined): Transformer;
/**
 * Transform function parameters
 */
export declare function createParameterTransformer(transformer: (
    params: ParameterDeclaration[],
    decl: Declaration,
  ) => ParameterDeclaration[] | null | undefined): Transformer;
/**
 * Add modifiers (export, declare, etc.)
 */
export declare function createModifierTransformer(modifier: string, filter?: (decl: Declaration) => boolean): Transformer;
/**
 * Strip specific JSDoc tags
 */
export declare function createStripTagsTransformer(tags: string[]): Transformer;
/**
 * Wrap types in a utility type
 */
export declare function createWrapTypeTransformer(utilityType: string, filter?: (decl: Declaration) => boolean): Transformer;
/**
 * Plugin that prefixes all exported types with a namespace
 */
export declare function createNamespacePrefixPlugin(namespace: string): Plugin;
/**
 * Make all declarations readonly (for interfaces/types)
 */
export declare const readonlyTransformer: Transformer;
/**
 * Make all optional properties required
 */
export declare const requiredTransformer: Transformer;
/**
 * Make all required properties optional
 */
export declare const optionalTransformer: Transformer;
/**
 * Plugin that makes all interface properties readonly
 */
export declare const readonlyPlugin: Plugin;
/**
 * Plugin that strips @internal, @private, and @hidden tags
 */
export declare const stripPrivatePlugin: Plugin;
/**
 * Plugin that adds 'declare' keyword to all declarations
 */
export declare const declarePlugin: Plugin;
/**
 * Context available to transformers
 */
export declare interface TransformerContext {
  filePath: string
  sourceCode: string
  index: number
  total: number
  allDeclarations: readonly Declaration[]
  createDeclaration: typeof createDeclaration
  cloneDeclaration: typeof cloneDeclaration
  modifyText: (decl: Declaration, text: string) => Declaration
  addModifier: (decl: Declaration, modifier: string) => Declaration
  removeModifier: (decl: Declaration, modifier: string) => Declaration
}
/**
 * Context for text transformers
 */
export declare interface TextTransformerContext {
  filePath: string
  phase: 'before' | 'after'
}
/**
 * Visitor pattern for walking declaration trees
 */
export declare interface DeclarationVisitor {
  enter?: (decl: Declaration, parent: Declaration | null) => void
  leave?: (decl: Declaration, parent: Declaration | null) => void
  function?: (_decl: Declaration, _parent: Declaration | null) => void
  variable?: (decl: Declaration, parent: Declaration | null) => void
  interface?: (decl: Declaration, parent: Declaration | null) => void
  type?: (decl: Declaration, parent: Declaration | null) => void
  class?: (decl: Declaration, parent: Declaration | null) => void
  enum?: (decl: Declaration, parent: Declaration | null) => void
  import?: (decl: Declaration, parent: Declaration | null) => void
  export?: (decl: Declaration, parent: Declaration | null) => void
  module?: (decl: Declaration, parent: Declaration | null) => void
  namespace?: (decl: Declaration, parent: Declaration | null) => void
  unknown?: (decl: Declaration, parent: Declaration | null) => void
}
/**
 * Result of a transformer, can be:
 * - Declaration: replaced declaration
 * - Declaration[]: multiple declarations (split)
 * - null: remove the declaration
 * - undefined: no change
 */
export type TransformResult = Declaration | Declaration[] | null | undefined;
/**
 * Transformer function that operates on a single declaration
 */
export type Transformer = (
  declaration: Declaration,
  context: TransformerContext,
) => TransformResult | Promise<TransformResult>;
/**
 * Text transformer operates on the raw text before/after processing
 */
export type TextTransformer = (
  content: string,
  context: TextTransformerContext,
) => string | Promise<string>;