Page MenuHomePhabricator

Investigate use of JSDoc for type safety
Closed, ResolvedPublic

Description

In the existing WVUI library code, there is little use of TypeScript features beyond typing. As we evaluate whether to continue using Typescript (T282835), we should consider alternatives that could replicate all or most of the benefits we get from TypeScript. JSDoc may be sufficient for our needs, at least for error highlighting in the IDE.

To investigate this, we should:

  • Experiment with a file or two: replace types with JSDoc equivalents and see if there's a workflow that would help us effectively catch type-related errors
  • Inspect type hints on the end user side and confirm whether they're adequate compared to what we get with TypeScript

Event Timeline

This is an approach I successfully tried with VSCode. You can use IDE's type checking support in javascript files without any typescript at all. JSDoc annotations facilitate this.

This can be done in two ways.

  1. "javascript.implicitProjectConfig.checkJs": true in VSCode configuration
  2. create a jsconfig.json in the project repository with checkJs as true.

Reference: https://medium.com/@trukrs/type-safe-javascript-with-jsdoc-7a2a63209b76

My recent experience has been similar to @santhosh's – I wrote a longer summary of my approach in a comment to the sibling ticket about Typescript: https://phabricator.wikimedia.org/T282835#7345366.

Here's another good blog post about the JSDoc way of using Typescript: https://austingil.com/typescript-the-easy-way/

I think we should seriously consider adopting this approach in our new library.

Just in case it's not well known, my team has been using this form of type checking in various web extensions and are using https://github.com/wikimedia/typescript-types to document mediawiki core types.

AnneT claimed this task.

We've moved forward with full TypeScript in Codex, so I'm closing this