Repository navigation
Use JSDoc with tsc for strong static typing #65
Description
It is possible to use JSDoc comments with the TypeScript compiler to enforce some strong typing, as documented in the following resources:
- https://medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76 - this is the best explanation I have found but may be a little outdated
- https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/ - more formal explanation which I think is not quite as clear
Here is the best example I have found: prettier/prettier#6313
I would personally favor this alternative over porting to TypeScript as proposed in #64.
Activity
[-]Use JSDoc with tsc for strong typing[/-][+]Use JSDoc with tsc for strong static typing[/+]fbartho commentedon Oct 10, 2019
I'm also looking to do a technique like this for another node library I contribute to.
I think this is set up to work best with the next major version of TypeScript coming out at the beginning of next month, as they're making changes to support parsing JS+JSDoc via TypeScript-compiler.
Specifically, I think this PR was a blocker: microsoft/TypeScript#32372
If JSDoc is super detailed and robust, then theoretically, the
.d.tsdeclaration file could be directly output from there. -- From my initial work writing the JSDoc types for another library, however, it was way clunkier and harder to do than directly writing TypeScript, and nothing helped guide correctness in the JSDoc types. :(erisu commentedon Jun 16, 2026
I think the tsc angle can be revisited later if needed once the JSDoc coverage and structure are in place. Since this ticket has become stale, I’d like to focus on the JSDoc improvements first as the immediate step forward.
There hasn't been any activity on this for several years, so I’m closing it in favor of consolidating the work under #171.