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

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.

[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.