search

composi / core

A JavaScript library for creating websites, PWAs and hybrid apps.
MIT License
27 stars 2 forks source link

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

Closed brodycj closed 4 years ago

brodycj commented 5 years ago

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 5 years ago

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 5 years ago

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 5 years ago

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 5 years ago

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 5 years ago

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 5 years ago

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

brodycj commented 5 years ago

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 5 years ago

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

rbiggs commented 4 years ago

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

brodycj commented 4 years ago

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 4 years ago

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 4 years ago

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 4 years ago

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:

https://github.com/apache/cordova-node-xcode/issues/20

https://github.com/apache/cordova-node-xcode/issues/38

https://github.com/apache/cordova-node-xcode/issues/64

https://github.com/apache/cordova-node-xcode/issues/65

Thanks! -- Sent from my mobile

rbiggs commented 4 years ago

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 4 years ago

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 4 years ago

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

brodycj commented 4 years ago

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 4 years ago

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 4 years ago

https://github.com/prettier/prettier/pull/6702#issuecomment-546436751

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 4 years ago

Thanks for your reply on that pr

On Fri, Oct 25, 2019 at 1:24 PM Chris Brody notifications@github.com wrote:

prettier/prettier#6702 (comment) https://github.com/prettier/prettier/pull/6702#issuecomment-546436751

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 https://github.com/composi/core/issues/5?email_source=notifications&email_token=AAL42UE4SKE3SL3SR6C3QITQQMTU3A5CNFSM4IXH6RCKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOECJAICA#issuecomment-546440200, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAL42UFYPQSQPVPYVLCB45DQQMTU3ANCNFSM4IXH6RCA .

-- Sent from my mobile

brodycj commented 4 years ago

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

brodycj commented 4 years ago

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 4 years ago

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 notifications@github.com 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 commented 4 years ago

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