jsDoc Evangelism

#javascript #typescript #jsdoc #webdev

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]);
};