Provide .ts developer experience for .js modules (with a .d.ts without JSDoc)

[Ethan-Arrowood]

Search Terms

checking .js files with declared types
reference types in .js files
.js developer experience
checking .js types without JSDoc

Suggestion

I'd like to have the same developer experience of writing .ts files that have their types declared in .d.ts files, when writing .js files with types declared in .d.ts files. I've asked a question about this (apparently missing) feature on StackOverFlow. This issue/feature is similar to #29056; however, this would be for the developers writing the module rather than those consuming the module. Also, be aware that the JS project does not support JSDoc typings.

To reiterate (from the SOF post) the story for this feature:
Imagine you are working on a project MyLibrary. It is written in JavaScript (MyLibrary.js) and you have also written a TypeScript declaration file (MyLibrary.d.ts). It is published to npm alongside your JS code so you can provide TS developers the ability to consume your project code and use it in TypeScript projects.

Now, you have some contributors to MyLibrary that are TypeScript developers. They would like the typings written in MyLibrary.d.ts to be inferred in the MyLibrary.js code (essentially granting them the TS dev experience while writting JS code).

Use Cases

The Fastify Node.js server project is written in JavaScript and provides a fastify.d.ts file for typings. As a maintainer of this project I'd like for the types defined in this file to be referenced in the fastify.js file.

This type of dev experience might be difficult because, for example, the fastify.js file exports a single function build. When a dev uses fastify they would often write const fastify = requires('fastify') and then go from there. Our typings do not define types for build but for a module namespace Fastify object. If things worked like I wanted them to, i'd imagine the build function would need to be renamed to whatever I'm using in the type file.

I'm aware this feature request is maybe an anti-pattern, but I'd like to share it nonetheless to at least be discussed. I think it would be brilliant to provide a nearly equivalent developer experience for both JavaScript and TypeScript developers working on the same module library.

If this feature is already being worked on and I failed to land on it from my searches please link me to relevant issues and/or prs. I did search this repo issues, read the FAQ, read the 3.4 feature doc, and searched tirelessly on google.

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.

[RyanCavanaugh]

This is a pretty coherent scenario IMHO. I think the question is how common this setup of development is.

[Ethan-Arrowood]

For any project maintaining its own .d.ts file I think this would be very common as at least one of the project maintainers is a TypeScript developer. In the case of fastify I believe we have 3 or 4 at the moment.

[ustun]

I think this feature would aid TypeScript adoption significantly. For adoption, most projects need to stay in JS, so that the transition is gradual. JSDoc helps, but is quite verbose.

Think of it this way: you have a foo.js file, an accompanying foo.test.js file and a foo.d.ts file. The test and type files are enhancements that do not appear at all during runtime, so it is easier to sell and completely optional.

[wojpawlik]

👍, combined with checkJs and noImplicitAny this would detect missing and incorrect typings.

[frank-dspeed]

I am not sure but as a early adopter of the new ModuleResolve algos i was forced to experiment with so called composit projects and i am also a JS only user and found out that the following is true! you can create a folder

myfolder
myfolder/tsconfig.json

then you can put your js files into that and also the d.ts files simply besure they get loaded when you then inside your .ts project reference the composit project it will work

also a other new pattern that works is to use npm with the new workspaces array inside the package.json it is able to transition folders/that/are/deep/nested to folders/node_modules/nested so that it can easy get used with module resolution node and this way you can put a package.json inside the nested folder that points via the types setting to the d.ts

hope that makes some sense its only a fast write up but i hope it helps some one into the right direction.

Explaining a bit more

the composit flag builds projects before they get used this way you already builded it by hand via your .js .d.ts combination and typescript will pick it up

https://www.typescriptlang.org/docs/handbook/project-references.html

[alshdavid]

I think the question is how common this setup of development is.

Anecdotally, I have run into wanting this a few times.

Typically it comes up when maintaining a legacy application or one where TypeScript was excluded due to the overhead of setting up the toolchain (ironically).

Another scenario is when working on smaller web projects that don't use a compiler (say, using browser modules) and types would be a nice addition.

JSDoc is a bit verbose, doesn't have useful features from TypeScript and isn't as well documented. Populating types from an associated .d.ts file would be a great alternative to JSDoc.