Use JSDoc to check and generate TypeScript typings

[ChristianMurphy]

Rendered version: https://github.com/unifiedjs/rfcs/blob/963c1c20de118a2e9e60e249e56a5f18c573c8fa/text/0000-generate-typings-from-jsdoc.md

This would also be made easier by #4
Blog post by another project (and a remark adopter) who have also taken this approach https://dev.to/open-wc/generating-typescript-definition-files-from-javascript-5bp2
Example of what this would look like in unified vfile/vfile-message#8

[ChristianMurphy]

/cc @Rokt33r @JounQin

[wooorm]

I think this is a great idea! unified stuff used to have JSDocs way back when!

[wooorm]

Another drawback is that the code side increases a lot. The code I just linked had 49 lines of code, the file with comments is 139 lines. That’s almost tripling the size.

If we pull index.d.ts and # API in readme.md from the code, that may be worth it though.

[Murderlon]

This makes sense! The barrier for me when adding types to an existing package for the first time was figuring out imports, name spaces, and other specific TypeScript things I did not encounter before. This switches to a more 'natural' type specification and leaves the details to the compiler.

However, adding comments to test files to also test types feels a bit weird to me. I’m not sure how extensive the generated test.d.ts file is out-of-the-box and what our standards are for type tests. But I feel that part might make more sense explicitly in its own file. The downside is that it brings in extra config files, though we already have those in the existing approach.

[ChristianMurphy]

Another drawback is that the code side increases a lot. The code I just linked had 49 lines of code, the file with comments is 139 lines. That’s almost tripling the size.

Good point, updating RFC to include this.

If we pull index.d.ts and # API in readme.md from the code, that may be worth it though.

Another RFC for this is in the works.

However, adding comments to test files to also test types feels a bit weird to me.

Good point, I may add a dedicated section to the RFC for this.
The thinking here is that the annotations in the tests would not be a part of the public API or the typings.
This would be suppressed through gitignore and JSDoc annotations.
It would allow for the existing test suite to check both how the code runs, and validate that the typings work.

But I feel that part might make more sense explicitly in its own file. The downside is that it brings in extra config files, though we already have those in the existing approach.

I see your point, and I'm open to the idea.
The reason I didn't go that direction initially are duplication and missed cases:

• duplication type tests need to follow a similar coverage path to unit tests, having both would lead to some overlap
• missed cases when type tests and unit tests are used together they can articulate edge cases that may be difficult to capture otherwise, For example an API which can return number may return NaN in some circumstances, which is perfectly valid from a static typing perspective, and would only be seen in the unit tests. Having the unit tests also be the type tests gives a single source of truth for seeing what those edge cases may be.

Another alternative would be to make test file a .ts file and use ts-node to run the test suite.

[Rokt33r]

Hmm.. I think using JSDoc would work for simple projects. But for unified ecosystem, I'm a bit worrying.

I've checked how interfaces works in JSDoc but I couldn't find proper ways to importing and exporting those interfaces. I think this is quite important for unified because most of packages of unified are using Node, VFile and Plugin interfaces or type alias.

Also we might lose some keywords like any and unknown.

How can we tackle those problems if we adopt JSDoc?

[ChristianMurphy]

Thanks for the feedback @Rokt33r! 🙇

I've checked how interfaces works in JSDoc but I couldn't find proper ways to importing and exporting those interfaces.

This is a concern I initially shared.
And is part of why I opened vfile/vfile-message#8 before opening this RFC.
An example of importing and exporting interfaces is here: https://github.com/vfile/vfile-message/blob/4fd342b923abe68c8ce0371cf82c5ce807f52fb4/index.d.ts#L2-L12

Documentation for these is located at https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#import-types and https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#typedef-callback-and-param

Also we might lose some keywords like any and unknown.

While I would generally prefer to stay away from both of these types.
Both any and unknown are supported https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html#type

[Rokt33r]

Thanks for clarification. I've read the article from typescript just now. It looks good to me. I also want to try to adopt it. 👍

[wooorm]

for anyone reading along, @ChristianMurphy and I have recently tried this in xdm, works pretty well, although indeed a bit verbose: https://github.com/wooorm/xdm/blob/964eb45052e7fe130788540521b8ec81a1138fea/lib/core.js#L13

[JounQin]

Why not use .ts directly. 😂

[wooorm]

I think these are my main three reasons on why I prefer jsdoc ts over .ts:

• TS is a understood by less people than JS
• It adds an extra compile step
• I think it’s more likely that TC39 standardizes jsdoc, or a different type system, instead of how .ts files work currently, meaning that similar to CoffeeScript, in a couple years we’ll all be rewriting things back into JS

[ChristianMurphy]

• I think it’s more likely that TC39 standardizes jsdoc, or a different type system, instead of how .ts files work currently,

It is possible.
But not the most likely outcome, more likely is something like pep-0526 did for Python where annotations are standardized, but types themselves may not be, Brendan Eich one of the original creators of JS spoke about this recently in an interview.
Which would also remove the second concern

It adds an extra compile step

---

In the meantime, JSDoc based annotations allow authors and maintainers that prefer vanilla javascript to continue doing so, and also generate typings which keep in sync with the code.
This also addresses one of the issues with handwritten dts files, namely that the types can get out of sync with the implementation with little to no warning. While with JSDoc based annotations, the type checker can flag cases where things are out of sync.

[ChristianMurphy]

Another possible value point for JSDoc, it could be used to generate the readme documentation, for example something like: https://github.com/jsdoc2md/jsdoc-to-markdown

[ChristianMurphy]

JSDoc based types has been rolled out to most of unified as part of unifiedjs/unified#121
Would it make sense to merge this? or close it?