composi/core

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

Closed this issue · 24 comments

brodycj commented

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:

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

rbiggs commented

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 commented

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 commented

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 commented

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 commented

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 commented

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

brodycj commented

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 commented

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

rbiggs commented

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

brodycj commented

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 commented

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 commented

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 commented
rbiggs commented

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 commented

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 commented
brodycj commented

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 commented

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 commented

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 commented
brodycj commented

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

brodycj commented

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 commented
Raynos commented

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

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