Option to copy custom types to outDir

Search Terms

declaration files, .d.ts, ergonomics, distributable package, library, compiler option

Suggestion

I would like tsc to include an option that enables copying .d.ts files from my project's source tree into the configured outDir.

Use Cases

I maintain a distributable library that is often used as a dependency of other packages. As often as I can, I depend on @type/* packages and the core type libraries to express the types in the platforms that my library supports.

However, there are cases where these sources do not reflect the ground truth of my supported platforms (for example, old browsers w/ proprietary APIs, or experimental/unstable/nascent web platform features). In these cases, it isn't suitable to upstream my custom types to another package, and even if it was, the latency involved in waiting for upstream contributions to be accepted and published is not a good reason to block a release of my library.

In cases like these, I tend to express the types in .d.ts files in my source tree. However, per https://github.com/Microsoft/TypeScript/issues/5112, tsc does not copy these files to my configured outDir as a matter of principle. This means that I have to complicate my build with an additional copy step in order to produce a comprehensive, publishable artifact. Meanwhile, it seems like tsc could make my life a lot simpler by copying over these files on my behalf.

Examples

This could manifest in a lot of ways, but a strawperson would be to add a compiler flag. Call it --include-custom-type-declarations (or any suitable name).

If tsc is invoked with this flag set to true, then tsc will include all .d.ts declarations in the source tree among the artifacts generated in the outDir.

Checklist

My suggestion meets these guidelines:

• 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, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

首先调查 tsc 如何处理源 .d.ts 文件和配置的 outDir，并以 issue 中描述的现有行为作为基准。定义该选项的范围和复制行为，然后验证自定义声明会出现在可分发输出中，同时不改变现有的编译器行为。