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

[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!