AST transformation & postprocessing

esm-d-ts can be configured for type declaration AST transformation during generation and in a postprocessing stage. Working with AST transformation is an involved process, but provides capabilities that aren't presently supported by the Typescript compiler / tsc. Transformation occurs during generation through defining tsTransformers in a config file. Postprocessing is configured through defining postprocess in a config file.

postprocess:

Postprocessing of the generated bundle declarations provides an avenue to support features that are not available through the Typescript compiler. esm-d-ts provides optional postprocessing of the final bundled DTS file and this makes it much easier to coordinate AST transformation across all symbols in the given package / module. Please refer to the ProcessorFunction /* TODO: INSERT LINK */ type alias for the expected function signature. An object is passed into the processor function with the following properties:

• Logger: The static Logger /* TODO: INSERT LINK */ class which should be used for any logging.

• inheritance: An instance of GraphAnalysis /* TODO: INSERT LINK */ which is pre-populated with the inheritance graph of all classes.

• sourceFile: A ts-morph SourceFile instance which is created from contents of the generated bundle. ts-morph is much easier to use than the underlying Typescript compiler AST mechanisms.

@inheritDoc support:

@inheritDoc is an unsupported JSDoc tag by the Typescript compiler. This is a useful tag for those working with deep inheritance hierarchies as it indicates that a parent class method or constructor function is overridden and documentation is forwarded on to a child implementation. By default, the Typescript compiler does not type the parameters to any @inheritDoc method or function and leaves them as any. The first built-in postprocessor adds support for @inheritDoc.

The following is an example esm-d-ts.config.js configuration file that loads the processInheritDoc postprocessor.

import { processInheritDoc } from '@typhonjs-build-test/esm-d-ts/postprocess';

/**
 * Generate DTS with experimental postprocessing to adjust declarations for `@inheritDoc` support.
 */

/** @type {import('@typhonjs-build-test/esm-d-ts').GenerateConfig[]} */
const configs = [
   { input: './src/index.js', postprocess: [processInheritDoc] }
];

export default configs;

tsTranformers: