Option to copy custom types to outDir

cdata commented 4 years ago

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:

[x] This wouldn't be a breaking change in existing TypeScript/JavaScript code
[x] This wouldn't change the runtime behavior of existing JavaScript code
[x] This could be implemented without emitting different JS based on the types of the expressions
[x] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
[x] This feature would agree with the rest of TypeScript's Design Goals.

restjohn commented 4 years ago

This would also be useful for projects migrating from JavaScript to TypeScript. I want to write custom type declaration files for legacy JavaScript files and output the .d.ts files from my source tree. However, because my tsconfig.json has { declarations: true, allowJs: true }, tsc disregards the .d.ts files in my source tree and generates its own, less rich declarations for the JavaScript modules.

For example, I have

src/
|- models/
   |- user.js
   |- user.d.ts (custom type declaration)

and tsc emits

lib/
|- models/
   |- user.js
   |- user.d.ts (tsc's interpretation of user.js, ignoring custom declarations)

I know I can write JSDoc in my legacy JavaScript files, but I'd much rather write TypeScript declarations and have tsc emit them.

restjohn commented 4 years ago

This has started to cause me minor grief because I have to compile unnecessarily. My project is setup as follows.

tsconfig.json (base config with common compiler settings)
src/
|- tsconfig.json (extends ../tsconfig.json, includes ./**/*, outDir: ../lib)
|- @types
   |- module-name
      |- index.d.ts (custom declarations for untyped module-name; tsc does not emit :/ )
|- **/*.ts (app ts files)
|- other-resources
   |- image files, openapi docs, etc. (tsc does not emit, ok)
|- scope-x
   |- legacy-x1.js (untyped legacy js module)
   |- legacy-x1.d.ts (inline declarations for untyped legacy js module; tsc does not emit :/ )
test/
|- tsconfig.json (extends ../tsconfig.json, includes ./**/*, outDir: ../test-lib, references ../src/tsconfig.json)
|- **/*.test.ts (imports compiled modules from ../lib, needs custom type declarations that tsc did not emit)

The tsconfig.json in the test directory uses a project reference to the src directory, which is great. Normally, to build test, my NPM script would simply tsc -b test. However, now that I have custom .d.ts type declarations in src that tsc does not emit, and TS files in test reference compiled modules in ../lib, I am forced to undermine the project reference functionality and explicitly npm run the entire build process for src, which includes manually copying type declarations and resources after tsc -b src, in order for modules in test to access necessary type information. So, I have a chicken and egg problem. tsc -b test will build both src and test, but the src build will not emit my custom declarations, and test imports from the src output directory lib, and the custom types are not present. I cannot copy the custom types to where they need to be before tsc -b test, because the src build will just overwrite them.

I need tsc to emit my custom type declarations that I have created alongside their legacy .js module counterparts.

restjohn commented 4 years ago

Please see my example repository for a demonstration of the issue.

restjohn commented 4 years ago

By the way, the purpose of including custom type definition files is not only for compiled tests in the same project, but for down-stream consumers of the package as well.

microsoft / TypeScript