TLDR;
Work with a legacy code base - many of us don't able to dodge time by time - lead me to try the jsDoc instead of Typescript. I have to reveal the surprising truth!
First off all let's clean: jsDoc or TS just means under developer time ( included later review, reusing, look at that code in any environment: git web page, random editor, chrome, firefox, ...:devtool, vim, cat ... );
The First Movement
Just open your editor, write a proper remark to test jsDoc is working or not.
/** @typedef { 'JS' | 'JQuery' | 'TS' | 'jsDoc' } Phase; */
/**
* On typing ' editor will popup string list.
*
* @type {Phase}
*/
const badCase = 'React'; // !!!! lint alert !!!!
/** @type {Phase} */
const goodCase = 'JQuery';
jsDoc vs. Typescript
In my experience the jsDoc able to replace the TS code, bonus the wormhole between these two exists.
The biggest jsDoc feature imho: this is using a standard JS comment system, so don't break any JS code, this code will rune everywhere where JS capable to run.
| feature | jsDoc | Typescript |
|---|---|---|
| compiling freedom | Do not need compiling the code. | mandatory to compile |
| dependency freedom | Can working without any dependency | at least TS is your dependency |
| namespace freedom | Don't interfere Types and other imports names. You can use same name of component and component Type in React for example. | Typesript names are identical including as any other referenct |
| rework freedom | Don't need to change existing code, just insert a comment. | at least some part in your code need to be turn to TS |
| legacy freedom | Can be use even transform to Typescript the project is not option. Many legacy projects affected this situation. | need to push management to allow that modification |
| Maximalism freedom | Don't need to use every where. Even you can use on a new commits, and after easy to search which is the new or reworked parts. | also enough to turn build system, and just part of code to TS |
| future freedom | Later can easy trasnlate to TS. Under the hood this is use same technic, just different way. | need to work if decide to use JS instead TS |
| mindset freedom | Because this is a comment your know well this is don't made any type check at runtime for you as TS also. | TS is noising your code |
jsDoc editors experience
I can write jsDoc in any editor, but rare which is understand it.
node module experience
I also created a npm module: jsdoc-duck: a jsDoc coded module. This highlighted that without TypeScript, it is not possible to create a jsDoc npm module. Maybe if I am speend more time to figure out vite building parameters then can be found a right solution. But the good news, if don't use that modul with npm, instead borrowing to our code: just copy index.js to a place - then we are save use to insert a new dependency to our program, and don't happen nothing if module owner turn the module to something else.
Wormhole between jsDoc <-> Typescript
The good news the Typescript and jsDoc are compatible each other, just the jsDoc use a bit different syntax. But you can use jsDoc module types in a typescripts and you can also use typescript module types in javascript / js+jsDoc program also. So the final decision is in your hand.
Follow the yellow brick road
VS code example show how nicely saw your Types in jsDoc code, in my opinion this is surprising fewer noise give to your code.
Bonus
:: VS-Code snippets
"@type": {
"prefix": ["ty"],
"body": ["/** @type {$0} */"],
"description": "jsdoc type"
},
"@typedef": {
"prefix": ["td"],
"body": ["/** @typedef {$1} Foo */"],
"description": "jsdoc typedef"
},
:: jsdoc-duck code
( in this view syntax highlight don't help to understund the Types ). But this short program is good example the jsDoc can use TS advanced features also.
import { useMemo, useReducer } from "react";
/**
* @template T - Payload Type
* @typedef {T extends { type: infer U, payload?: infer P } ? { type: U, payload?: P } : never} ActionType
*/
/** @template AM - Actions Map @typedef {{ [K in AM['type']]: K }} Labels */
/** @template AM - Actions Map @typedef {{ [T in AM["type"]]: Extract<AM, { type: T }> extends { payload: infer P } ? (payload: P) => void : () => void }} Quack */
/**
* @template ST - State
* @template AM - Actions Map
* @typedef {(state: ST, action: AM) => ST} Reducer
*/
/**
* Factory function to create a typed action map.
* @template AM - Actions Map
* @param {Labels<AM>} labelsObject - The keys representing action labels.
* @param {function} dispatch - The dispatch function for actions.
* @return {Quack<AM>} The resulting typed action map.
*/
export const quackFactory = (labelsObject, dispatch) => Object
.keys(labelsObject)
.reduce(
/**
* @arg {Quack<AM>} acc
* @arg {keyof Labels<AM>} type
* @return {Quack<AM>}
*/
(acc, type) => ({
...acc,
[type]: (payload) => {dispatch({ type, payload });}
}), {});
/**
* A factory hook to create a state and a typed dispatch functions\
* @exports useDuck
* @template AM - Actions Map
* @template ST - State Typer
* @param {(st: ST, action: AM) => ST} reducer - The reducer function to manage the state.
* @param {ST} initialState - The initial state value.
* @return {[ST, Quack<AM>]} The current state and a map of action dispatch functions.
*/
export const useDuck = (reducer, initialState, labels) => {
const [state, dispatch] = useReducer(reducer, initialState);
const quack = useMemo(
() => quackFactory(labels, dispatch),
[dispatch, labels]
);
return ([state, quack]);
};
happy coding, burrowing instead add dependency
Top comments (1)
Nice. These are the reasons I left TS for JsDoc. Simple comments, no transpiling. Thanks.
Seems like English isn't your first language though. You could pass your post through an AI to fix your grammar next time.