microsoft / microsoft/TypeScript
JSDoc-typed node modules require special configuration in consumers to be useful
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 111k
- Forks
- 14.3k
- Avg merge
- 2d 4h
- Merged PRs (30d)
- 132
Description
It looks like an ongoing goal for TS is to recommend JSDoc as the recommended way to give type-checking to raw JS users. As a user I am not a huge fan of this approach but I'll try to be objective in this issue.
If I write a node module js-lib as raw javascript typed with jsdoc, it will appear as untyped to consumers of my module unless they specifically opt in to JS type checking.
Example:
+-js-lib
| +-index.js
| +-package.json
|
+-ts-consumer
+-index.ts
+-package.json
+-tsconfig.json
js-lib/index.js
/**
* @param {string} s
* @returns {number}
*/
module.exports = function test(s) { return parseInt(s) };
js-lib/package.json
{
"name": "js-lib",
"main": "index.js"
}
ts-consumer/index.ts
import test = require('../js-lib');
// index.ts(1,23): error TS6143: Module '../js-lib' was resolved to '/Users/jarrad/src/personal/ts-test/lib/js-index.js', but '--allowJs' is not set.
import test = require('js-lib'); // after npm install ../js-lib
// index.ts(1,23): error TS7016: Could not find a declaration file for module 'lib'. '/Users/jarrad/src/personal/ts-test/lib/index.js' implicitly has an 'any' type.
// Try `npm install @types/lib` if it exists or add a new declaration (.d.ts) file containing `declare module 'lib';
test("test");
ts-consumer/tsconfig.json
{
"compilerOptions": {
"strict": true
}
}
It should be possible for me to make my js-lib usable to Typescript authors without them having to configure their own project with allowJs and checkJs.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Reproduce the issue using js-lib/index.js, js-lib/package.json, ts-consumer/index.ts, and ts-consumer/tsconfig.json from the example. Start by tracing how the compiler resolves a JavaScript Node module and discovers type information for a TypeScript consumer. Done means a JSDoc-typed module can provide useful types without consumers enabling allowJs and checkJs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js, typescript
- Domain
- compilers, developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100