.d.ts emitted declarations should not include local variable names from parameter destructuring
octogonz opened this issue · 2 comments
🔍 Search Terms
parameter destructuring rename .d.ts declaration
✅ 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
When using parameter destructuring, a function's parameter list includes the names of local variables. The compiler should not include these local variable names in the generated .d.ts file, because they are an internal implementation detail. Although omitting the local variables would have no operational effect on the declaration, doing so would improve readability, particularly when these signatures end up on an API documentation website.
📃 Motivating Example
Consider this API source code:
book.ts
export interface Book {
title: string;
}
export function printTitle({ title: logMessage }: Book): void {
console.log(logMessage);
}The compiler emits this .d.ts file which includes both title (the destructuring source field) and logMessage (the target local variable):
book.d.ts
export interface Book {
title: string;
}
export declare function printTitle({ title: logMessage }: Book): void;💻 Use Cases
-
What do you want to use this for?
logMessageis an implementation detail. It increases the size of the .d.ts file without having any observable effect to consumers of theprintTitle()API. -
What shortcomings exist with current approaches?
Imagine the above signature is displayed on an API documentation website or VS Code IntelliSense preview. The audience reading this signature may be confused by variables such as
logMessage. What is that? Where are the docs forlogMessage.API Extractor also triggers an API review workflow whenever the type signature changes. Omitting implementation details from the .d.ts signature might avoid some false alarms for inconsequential changes.
-
What workarounds are you using in the meantime?
A .d.ts rollup tool such as API Extractor could automatically trim these extraneous tokens. However safely trimming them is a nontrivial operation as the AST changes in each compiler release. It would be much better for the compiler to implement this feature.