Discussion on: TypeScript Might Not Be Your God: Case Study of Migration from TS to JSDoc

[teamradhq]

The issue with JSDoc is that you end up writing TypeScript in your docblocks anyway. Your code examples are full of TypeScript annotations, so it's not that you're moving away from TypeScript, it's just that you're putting it somewhere else.

In your example screenshot of commit changes, the fundamental difference between the new version and the old version is that you've made a single use type declaration into a reusable one. The aesthetics don't matter, it's the fact that you've made a reusable type declaration that's important.

Putting all your types in docblocks leads you to a situation like this:

/**
 * @param {number} num
 * @param {string} str
 * @param {Record<string, string>} rec
 * @param {{ id: number, title: string, items: ({ id: number, name: string})}} obj
 * @returns {number}
 */

It's fine if obj is of a type that's only used in this one place. But in reality it the type of obj will be used multiple times, so it's simpler to declare the type once:

type Item =  { id: number; name: string };

type Rec = Record<string, string>;

type Obj = {
  id: number;
  title: string;
  items: Item[];
};

Even if your codebase is JS using docblocks, this is a much neater solution:

/**
 * @param {number} num
 * @param {string} str
 * @param {Rec} rec
 * @param {Obj} obj
 * @returns {number}
 */

Even better if you move your types into the function declaration, then you can use the docblocks for the actual documentation:

/**
 * @param num A number to do something with.
 * @param str A string to label the result with.
 * @param rec A record of properties interacted with.
 * @param obj An object containing the data to work with.
 */
function someFunction(
  num: number,
  str: string,
  rec: Rec,
  obj: Obj,
): number

This was a simple example... If you have functions with multiple shapes, union types, optional arguments, default values, or destructured arguments, then the docblock version becomes even more unwieldy.

For instance, are you prepared for the possibility that your project build, which took tens of seconds in pure JavaScript, might suddenly start taking tens of minutes when using TypeScript? Of course, it depends on your project's size, your pipeline configuration, etc., but these scenarios are not fabricated.

I'm not so sure if this is accurate.

In my experience, the difference in build time between the two is negligible. The additional time you refer to is the time it takes to perform type checking. If you don't check types when you build, then a project that uses Vite / Webpack / Babel etc will take roughly the same time to build.

If TypeScript build times were really much larger as you say, we wouldn't see people using TypeScript in large projects. But we do, because when you save a TS / JS file and HMR kicks in, the build time is negligible in both cases.

Again, it's not the build it's the type checking that takes time, and you should consider type check as a separate step to build.

See ts-loader documentation here for example:

You probably don't want to give up type checking; that's rather the point of TypeScript. So what you can do is use the fork-ts-checker-webpack-plugin. It runs the type checker on a separate process, so your build remains fast thanks to transpileOnly: true but you still have the type checking.

If you follow this advice and disable type checking at the build stage, regardless of your tooling, you'll get faster builds. Personally, I only do type checking once I am ready to integrate my changes into an upstream branch.

TypeScript does not care whether you define types using TypeScript's keywords and syntax or JSDoc tags supported by TypeScript. This principle also applies to ESLint and its plugins, including the typescript-eslint plugin. This means that we can use this plugin and its powerful rules to check typing even if the entire code is written in .js files (provided you enabled the appropriate parser).

This just means that you're using TypeScript. :)

[Vladyslav Zubko]

Hey @teamradhq !

Thank you for your comment, and especially for your code snippets! Let's go step by step 🙂

It's fine if obj is of a type that's only used in this one place. But in reality it the type of obj will be used multiple times, so it's simpler to declare the type once:

I completely agree that it's better to extract such types into separate files. This applies to both JSDoc and TypeScript, as well as the programming language in general. Making the code more readable and decomposing it is independent of any particular language, and, of course, it's always better to do so whenever possible (though unfortunately not always feasible).

Also, I would like to add that I can declare these types using JSDoc syntax in .js files without the need for .ts files. Here's an example of how it can look:

// obj.js

/**
 * @typedef {{
 *  id: number
 *  title: string
 *  items: Item[]
 * }}
 */
let Obj

export { Obj }

// some-function.js

import { Obj } from './obj.js'

/**
 * @typedef {{
 *  num: number
 *  str: string
 *  obj: Obj
 * }}
 */
let SomeFunction

export { SomeFunction }

The issue with JSDoc is that you end up writing TypeScript in your docblocks anyway. Your code examples are full of TypeScript annotations, so it's not that you're moving away from TypeScript, it's just that you're putting it somewhere else.

I use TypeScript syntax in JSDoc simply because I chose it. However, it doesn't prevent me from using, for example, the Closure Compiler syntax as well.

I'm not so sure if this is accurate.
In my experience, the difference in build time between the two is negligible. The additional time you refer to is the time it takes to perform type checking. If you don't check types when you build, then a project that uses Vite / Webpack / Babel etc will take roughly the same time to build.

Trust me 🙂

Here are two screenshots from one of my presentations where the build took a whopping 17 minutes. It's quite an old presentation that uses create-react-app (yes, with various ENV options like CI=false and others). Without .ts files, the build took around 2 minutes.

Btw, the presentation itself is about migrating to Vite. Eventually, after all the optimizations, the build started taking around 1 minute (even with .ts files). But that's because I have experience and know what to do. For most people, doing such optimizations for the first time will be a significant journey.

This just means that you're using TypeScript. :)

This means that I am currently using TypeScript now, and I will gladly replace it if I can in the future. I hope tools like quick-lint-js.com/ will continue to evolve in this direction.

[teamradhq]

Thank you for your well thought out and informative reply. I appreciate you taking the time :)

I'm a big fan of docblocks, which is why I enjoyed your article (and brilliant reply) to my comment so much. If you look at my work, you'll find plenty of docblocks. I practise document driven development (DDD) so it's a no-brainer. The only way you and I differ here is that I use a type system to document my types and docblocks to document my implementation.

I trust that you know what you know. Please trust me in return when I say that you're making my point for me here:

Here are two screenshots from one of my presentations where the build took a whopping 17 minutes. It's quite an old presentation that uses create-react-app (yes, with various ENV options like CI=false and others). Without .ts files, the build took around 2 minutes.

Out of the box, CRA doesn't skip type checking. I'm also pretty sure that it uses tsc to transpile TS > JS. TypeScript isn't slower than JavaScript when you built with CRA because it takes longer to transpile. It's slower because transpileOnly is set to false, so types are being checked.

With that in mind, your slide screenshot isn't making a fair comparison because it's comparing apples to apples and oranges (where oranges = static type checking). I guarantee you that if you configured CRA to skip type checking, there wouldn't be such a large discrepancy between the two.

I say this as seasoned Webpack user (CRA without the abstraction) who's both transitioned projects from JavaScript to TypeScript and from Webpack to Vite. My initial experience with TypeScript and Webpack aligns with your experience with CRA. Build times were off the hook. That's when I learned that type checking is a laborious process and all that was needed to speed up the build was to skip this step.

Even without your and my extensive knowledge of the dark arts (that's what how I refer to build process configuration) everybody will see drastic results switching from CRA/Webpack to Vite. It's much faster out of the box because it transpiles with esbuild instead of tsc, and Vite skips type checking by default (emphasis mine):

The reason Vite does not perform type checking as part of the transform process is because the two jobs work fundamentally differently. Transpilation can work on a per-file basis and aligns perfectly with Vite's on-demand compile model. In comparison, type checking requires knowledge of the entire module graph. Shoe-horning type checking into Vite's transform pipeline will inevitably compromise Vite's speed benefits.
Vite Features

This is what I mean when I say it's comparing apples to apples and oranges yeah? This documentation is spot on to say that we should consider type checking as a separate step from build, because they are totally different things.

When a file is transpiled, it's only concerned with itself and its direct dependencies. When a file is type checked, it's concerned with every dependency in the graph. It's the difference between touching one file and n files which is why it's slower.

From the same docs page:

For production builds, you can run tsc --noEmit in addition to Vite's build command.

If you look at Vite starter templates, their package.json provides this script for builds:

{ 
  "scripts": {
    "build": "tsc --noEmit && vite build"
  }
}

Now a production build takes many times longer to complete due to the type checking stage, but it also won't build if there are type errors. This means you can reduce the likelihood of misused types in production, which (as far as I know) you can't achieve without static type analysis.

My point is that you want your production build to take as long as possible, performing any and all checks possible to minimise the risk of catastrophic failure. Going back to your screenshot, if deploying to production results in downtime, then instead of avoiding long running tasks, switch to a different deployment method like blue green deployments, or containerisation or similar. That is, build your system outside of your operating environment and only deploy the built files upon success.

Also, I would like to add that I can declare these types using JSDoc syntax in .js files without the need for .ts files. Here's an example of how it can look:

I'm curious to know what the equivalent of overloading a function would be in docblock:

function someFunction(a: number): number;
function someFunction(a: number, b: string): string;
function someFunction(a: number, b: number, c: Record<string,string>): Record<string, string>;
function someFunction(
  a: number, 
  b?: string|number, 
  c?: Record<string,string>
): number | string | Record<string, string> {
 // ...
}

someFunction(1, 'string', {}); 

That is to say, a is always a number, b is a string unless c is provided, in which case it's a number.

So calling someFunction(1, 'string', {}) should show an error:

Argument of type 'string' is not assignable to parameter of type 'number'.(2345)
The call would have succeeded against this implementation, but implementation signatures 
of overloads are not externally visible.

Similarly, within the function body itself I would see errors:

• if b is undefined it would give me an error if I try to use c as a record
• if c is defined it would give me error if I try to use b as a string

Obviously, this is a contrived example, but it's not an uncommon pattern to encounter in a less abstract way in the wild. I don't think this is possible to achieve with JSDoc alone:

/**
 *
 * @param {number} a
 * @param {string | number | undefined} b
 * @param {Record<string, string> | undefined} c
 * @returns {number | string | Record<string, string>}
 */
function someFunction(a, b, c) {
  // ...
}

Everything that's returned from this function has the type number | string | Record<string, string> which makes the annotation kind of pointless. This is what the types should be:

someFunction(a);        // number
someFunction(a, b);     // string
someFunction(a, b, c);  // Record<string, string>

If there's a way to achieve this with JSDoc, I'd love to know more about it. Perhaps this can be achieved with Closure syntax, which I've never used.

This means that I am currently using TypeScript now, and I will gladly replace it if I can in the future.

I'd never tell someone what tools they should or shouldn't use, and I really hope that this discussion is coming across as informative and not confrontational.

I'm not trying to convince you to use or not use TypeScript or suggest that you're entirely wrong. I just want you to know that transpiling TypeScript is not slower than JavaScript. Type checking is the slow part, and it's really only necessary when integrating your change upstream :)

And again, thanks for your great reply :)

[Vladyslav Zubko]

Hello @teamradhq !

Cool that you also like JSDoc!

Thanks for providing such a detailed guide on how type checking works during the build! I hope everyone reading this article will also go through the comments since there is a lot of useful information here.

Regarding react-create-app, even if it's deprecated and everyone prefers Vite now, it is still used in many old projects. Actually, I've been a react-create-app hater since its creation, always preferring to configure Webpack myself, or at least eject the react-create-app to have control over my app's build. Disabling type checking during build is usually the first thing I did. But the problem is not everyone is as curious as we are. Unfortunately, many still use the "standard" react-create-app, where type checking happens before the build. Although this has become less common lately because Vite is doing its job 👍

I'm curious to know what the equivalent of overloading a function would be in docblock:

To be honest, I try not to use overloads in production applications. In applications, I find it better to use multiple functions. Overloads, in my opinion, are more suitable for libraries.

If anything, I'm not making excuses 😄 You can create overloads with JSDoc just as conveniently as in TypeScript using the @overload tag. You can learn more about it here - devblogs.microsoft.com/typescript/...

Example:

/**
 * @overload
 * @param {string} value
 * @return {void}
 */

/**
 * @overload
 * @param {number} value
 * @param {number} [maximumFractionDigits]
 * @return {void}
 */

/**
 * @param {string | number} value
 * @param {number} [maximumFractionDigits]
 */
function printValue(value, maximumFractionDigits) {
    if (typeof value === "number") {
        const formatter = Intl.NumberFormat("en-US", {
            maximumFractionDigits,
        });
        value = formatter.format(value);
    }

    console.log(value);
}

I'm not trying to convince you to use or not use TypeScript or suggest that you're entirely wrong. I just want you to know that transpiling TypeScript is not slower than JavaScript. Type checking is the slow part, and it's really only necessary when integrating your change upstream :)

I completely understand and agree with you! However, not everyone grasps this concept, and that's the gist of my article. Everything described in the first paragraph. I have to work with many teams, and each has its reasons for adopting or not adopting TypeScript. I'm just highlighting that going all-in with TypeScript (using .ts files) is not the sole solution to type checking in a project. Action is needed, not just praying to the TypeScript-God!

Thank you so much for your comments! I'm sure they added value to the article!