[OT] document how to use JSDoc for strong typing in JavaScript

[brodycj]

Hi @rbiggs, please forgive me if this is too far off-topic here. I think we have discussed this subject in multiple places, but it has stalled in the other projects for various reasons.

Considering that you seem to have the most experience with using JSDoc to get rid of TypeScript code, including *.d.ts files, I think you would be the right person to document this whole process.

The documentation in https://medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76 looks the best but I wonder if it is still up-to-date or not.

Microsoft already has documentation in https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/ but it seems to be not as clear to me.

I think this kind of documentation could really help other people in the Prettier and Grommet projects, in the following discussions:

• Would you accept a PR that converts this project to build with TypeScript? prettier/prettier#6286
• Use JSDoc instead of TypeScript for strong typing grommet/grommet#3353 / Roadmap suggestions from the community - request for comments grommet/grommet#3271
• proposal in Provide internal TypeScript support to improve code quality prettier/prettier#6313 which seems to do it right

I would be happy to help with feedback and maybe some contributions, no promises right now.

[rbiggs]

Hmmm... I could probably write another post specifically about how to use TypeScript specifically as a type linter, the way people use ESLint, for live type checking.

[brodycj]

I think that could really help a lot of people over time, ideally if it can be framework agnostic somehow, thanks.

I could also take a look, someday:)

[rbiggs]

Well, at the moment TypeScript is the best solution for live type checking of JavaScript. This is due to the fact that Microsoft implemented the TypeScript Language Server that runs in the background. It can check the JavaScript and infer types dynamically. To be honest, inferring types is not very good. But providing JSDoc type information gets around this so that the type information gleaned from JavaScript is almost on par with actual TypeScript code.

The support for live checking with Facebook's Flow isn't on the same level, and it doesn't support JSDoc comments currently. It uses its own comment system that more closely resembles TypeScript and requires a build step.

[brodycj]

Well, at the moment TypeScript is the best solution for live type checking of JavaScript.

To be 100% clear, I think you mean using the TypeScript compiler or toolset to check the JavaScript with JSDoc comments and not converting JavaScript source code to TypeScript with the .ts extension. This is what I was thinking all along here (I think I did not make this clear enough).

Improved type inference would be nice if the tooling improves the support someday in the future. And I think Flow had more advantage in the past.

I am now wondering if typescript-eslint can help us out with the type checking somehow?

P.S. I got the typescript-eslint idea from: https://devblogs.microsoft.com/typescript/how-to-upgrade-to-typescript-without-anybody-noticing-part-1/

[rbiggs]

Yes, I meant using TypeScript to lint JavaScript types--no build needed. The linting occurs as you code, live. You just need to set up the project to use checkjs: true for VSCode. With that setting, VSCode will use TypeScript to check the JavaScript types through both inference and by using the type information provided by any JSDoc comments.

[rbiggs]

I'm thinking I'll do a video for Youtube show how to do all of this.

[brodycj]

Video would sure be nice, I wouldn't mind some notes or even a sample project for people to play with.

I hope to look at this someday as well. Thanks again for looking at this.

[rbiggs]

Thanks. I'll let you know when I get the video up.

[rbiggs]

Just published an article on how to get going with type linting JavaScript: https://medium.com/@trukrs/javascript-type-linting-5903e9e3625f

[brodycj]

Thanks @rbiggs, really nice. It would also be good if we can support this in the npm scripts that can be tested on a build server. (I know we tried doing this on Preact last year, does not seem to be documented so well.) Would you consider adding any pointers?

This looks pretty interesting: https://www.robertcooper.me/using-eslint-and-prettier-in-a-typescript-project

[rbiggs]

Brody, when you say support this in the npm scripts that can be tested on a build server, are you taking about a type test at build time? If so I have implemented that with Composi/core :-).
In my package scripts I have the following line:

"checkjs": "tsc --allowJs --checkJs --noEmit --moduleResolution node --target ES6 src/*.js"

When I build before a commit, this runs a type check on the source code. Once in a while it catches something that I missed.

[rbiggs]

By the way, the above test has TypeScript parse the source code and compare it with the type information in the JSDoc comments to verify the types.

[brodycj]

Yes. I think it would help a lot of people if you can include the information about the npm script in the article itself. I keep encountering projects that could benefit from all of this information, issues in https://github.com/apache/cordova-node-xcode for example: apache/cordova-node-xcode#20 apache/cordova-node-xcode#38 apache/cordova-node-xcode#64 apache/cordova-node-xcode#65 Thanks! -- Sent from my mobile

[rbiggs]

OK, so I made a very basic starter project for type linting and put a link in the article: https://github.com/composi/check-js. You is set up to provide live type linting, as well as build-time type linting. You can run a test for types in two ways:

// Run only a check for types:
npm run checkjs

// Run all npm scripts sequentially: Prettier, ESLint, Jest and type checking:
npm start

[rbiggs]

This project is very basic and the JavaScript doesn't have much in the way of types. But this is the same approach I'm using with @composi/core, which has tons of type definitions. This works great for that project.

[brodycj]

Awesome, many thanks! I will try it out tomorrow. -- Sent from my mobile

[brodycj]

Thanks for all of your help so far. I have been able to apply the JavaScript type linting to Prettier, now dealing with a screen full of type errors. Closing this one out, will raise issues if needed on your check-js project.

[rbiggs]

No problem. Just so you know, I just did a checkin for check-js. It was missing the .vscode/settings.json file that turns on automatic type linting in the project :-/ Was being excluded by the .ignore file. Didn't notice that till now.

[brodycj]

prettier/prettier#6702 (comment)

I used to be able to just type a function and hit enter to get an automatic import. Without jsconfig that's not working now.

@rbiggs can you post a sample demo project for that?

[brodycj]

Thanks for your reply on that pr

On Fri, Oct 25, 2019 at 1:24 PM Chris Brody ***@***.***> wrote: prettier/prettier#6702 (comment) <prettier/prettier#6702 (comment)> I used to be able to just type a function and hit enter to get an automatic import. Without jsconfig that's not working now. @rbiggs <https://github.com/rbiggs> can you post a sample demo project for that? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#5?email_source=notifications&email_token=AAL42UE4SKE3SL3SR6C3QITQQMTU3A5CNFSM4IXH6RCKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECJAICA#issuecomment-546440200>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAL42UFYPQSQPVPYVLCB45DQQMTU3ANCNFSM4IXH6RCA> .

-- Sent from my mobile

[brodycj]

@rbiggs you should see that we got this started in Prettier: prettier/prettier#6770

[brodycj]

I just found an article that discusses using VS Code with checkJs, though with a different purpose: https://www.twilio.com/blog/move-to-typescript

[rbiggs]

Well yeah. Typescript guys always asume once a JavaScript dev experiences types, they’ll naturally want to switch to TypeScript. If that were the case though, we would probably be looking at a real type safe language such as Elm, PureScript, ClousureScript and ReasonML.

…

Sent from my iPhone

On Jan 22, 2020, at 3:50 PM, Chris Brody ***@***.***> wrote:  I just found an article that discusses using VS Code with checkJs, though with a different purpose: https://www.twilio.com/blog/move-to-typescript — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[Raynos]

I've recently gone down the same path with jsdoc + linting.

I found your blog post super helpful.

I looked into eslint and eslint-typescript ;

I found a few useful tools that help with type safety

• https://github.com/Raynos/tsdocstandard ; a zero-config CLI like standard or prettier that will know how to lint jsdoc projects.
• https://github.com/Raynos/eslint-config-tsdocstandard ; A set of eslint rules and plugins that work with checkJS / allowJS / jsdoc
• https://github.com/plantain-00/type-coverage ; A program to check whether your javascript file has 100% type coverage. This is useful as typescript is "less strict" by default in checkJS then with typescript files.

I have some examples of using these tools and using jsdoc as pull requests

• Add JSDoc Type definitions Raynos/error#24 ; Add jsdoc to a javascript project
• Delete TypeScript; Long live JavaScript Raynos/sync-wait-group#2 ; Convert a typescript project into a jsdoc project