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.

Start by investigating how tsc handles source .d.ts files and the configured outDir, using the existing behavior described in the issue as the baseline. Define the option's scope and copying behavior, then verify that custom declarations appear in the distributable output without changing existing compiler behavior.