Add support for beforeDeclarations

[Danielku15]

🔍 Search Terms

beforeDeclarations declaration transform transformers afterDeclarations

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

The TypeScript compiler API already supports custom transformers in 3 ways:

1. Before built-in .js transformations
2. After built-in .js transformations
3. After built-in .d.ts transformations

But the API is missing a "Before built-in .d.ts transformations" variant.

📃 Motivating Example

To generate type declarations more dynamically, you often need to access AST nodes of your codebase as it is written. The built-in transformers erase already a lot of the AST making this information unavailable. With the help of this new beforeDeclarations you are able to access your full AST and use it to auto-generate your typescript declaration files.

💻 Use Cases

1. Use information from property initializers to include "default values" your JSDoc comments. (see Preserve property comment and insert @default value, if provided #41486).
2. Remove declarations using information like visibility modifiers or used functions in your code to not expose implementation details.

[Danielku15]

Referencing some more related issues where a beforeDeclaration hooks would have a benefit:

• Suggestion: Generate doc comments in emitted JS #10 Situation after: Have the same JsDoc generation possibilities in the .js and d.ts with transforming the comments (currently d.ts would be lacking some information)
• Add capability of transforming and emitting JSDoc comments #17146 Situation after: Transformation of JsDoc allows the use of the full AST information (currently it is limited)
• Preserve property comment and insert @default value, if provided #41486 Situation after: you can write a transformer injecting the @default tags (currently the initializers are erased and information is lost).

The afterDeclarations was added in

• Enable custom transforms for declaration emit  #23701
• Add hook for adding transforms into the declaration emit pipeline after the main one #23946

And another problem:

• On the afterDeclarations there seems something broken on the AST. parent is unset for ts.PropertyDeclaration nodes and both ts.getJSDocCommentsAndTags and ts.getSyntheticLeadingComments return nothing. The built-in transforms seem to break things using 5.5.2. (see here).