"Freedom from types" = "freedom from seatbelts".

Simply horrible advice.

I have worked on many 10k+ line projects the past 6 years, and the only time typescript has presented issues is when trying to use libraries that dont have typings og bad typings ... The compile step was also never an issue. Most frameworks alredy kinda have one through rollup and webpack anyway. The type system has never given me more challenge than i set myself up for. If i decided to do it the hard way for some kind of crazy auto mapped tooling obviously the level of difficulty increases, but if you are unhappy with that and going to delete the types anyway just take the easier routes. Quite frankly this movement is weird and i would like to see some more specific examples of why people are upset. All i hear is the generic compile step excuse but it never was a problem for me until i heavily abused the type system.

I knew I'd find someone to ask 😁

What are JSDoc capabilities for genetics? I.e. what would be the proper way to convert the following generic type into JSDoc annotations?

type DeepReadonly<T> = Readonly<{
  [K in keyof T]: 
    // Is it a primitive? Then make it readonly
    T[K] extends (number | string | symbol) ? Readonly<T[K]> 
    // Is it an array of items? Then make the array readonly and the item as well
    : T[K] extends Array<infer A> ? Readonly<Array<DeepReadonly<A>>> 
    // It is some other object, make it readonly as well
    : DeepReadonly<T[K]>;
}>

This is a hot topic right now and bound to cause some controversy on both sides of the camp. I started using JSDoc recently and I am getting comfortable with it, however I find the documentation challenging and the lack of tutorials frustrating (try searching for how to correctly type React state using JSDoc).

That post by DHH is just the ramblings of a butthurt developer who is no longer relevant. If you want to prototype something quickly, use whatever tools you need and leave out anything you don't want. But the minute a codebase needs additional developers, TS shines. You shouldn't make blanket statements about how TS isn't productive when numerous enterprise developers are all saying that it's tremendously helpful.

For a long time nobody writes plain JS without at least some compilation or transpilation step, especially on the frontend.
Transpilation or comment/type stripping is certainly much faster than (typescript) compilation.
Therefore for a long time most build tools don’t use typescript compiler anymore but just use transpilation with type stripping.
If you want to continue using types, and I think you should, then I believe that is the much better middle ground than verbose and noisy comments. Then the only use for comments remains commenting the code.

One of the primary reasons I choose TypeScript is for its robust null and error checking capabilities. When I have a function that can either return valid data upon successful execution or an error in case of failure, TypeScript significantly reduces the chances of overlooking error handling when invoking the function. This is crucial for maintaining the reliability and stability of a production system.

When multiple team members are collaborating on a project, ensuring proper error handling becomes paramount. TypeScript's strict typing and type checking help enforce error handling practices across the codebase. While it may require a bit more effort during development, the peace of mind knowing that my code is less prone to runtime errors and is thoroughly handling potential issues is well worth it

I agree with compilations overhead, due to wrong conversions we have to use babel for code to work correctly. And typescript team doesn’t care to correct it.

But commenting JSDoc is also an overhead, code becomes less cleaner. Comment about logic and comment about the type gets mixed.

The totally wrong thing is the @types namespace as you try to investigate the symbol, it takes you to declaration. You don’t see the source code which is terrible.

I hate @types declaration. Either it should take to typescript source or JavaScript source.

We are using typescript but always with declarations along with map to original source code.

Non accessible source code is against web development ecosystem.

I guess you can ignore some of typescript’s default compilation config to still stay in typescript and make it easy to work with.

1. No .d.ts without source map.
2. To fix compilation issues, you can use switches as ts-ignore
3. Keep JSDoc clean for explanation
4. Transpiled JS should contain JSDoc with the types.

I tried using JSDoc for a contract job I was working on where the person I was working with wasn't used to working with TypeScript. I found it pretty painful TBH without TypeScipt.

I don't want to bash JSDoc, in fact I love using JSDoc for utility functions I build (with TypeScript) purely for the handy extra information I can add for intellisense, but abandoning TypeScript altogether for that job felt counter productive, everything I built took longer to build properly...

The problem with the jsdoc types is duplication of code. If you want to change function arguments, you have to do so in two places. And thus makes the code vulnerable to all problems associated with duplicated code. I can see some merit in the case where you want to use type inference but not strongly type anything, but for strongly typing your own code typescript is still king imho.

I don't understand why people keep bringing up the compilation step... I haven't seen any serious JavaScript project without a compilation step in the past decade... Moreover, it's not like you're recompiling every line of code in your project when you change one thing, the typescript compiler is actually pretty smart about that :) recompilation is pretty much instant.

Yes I agree that TypeScript could be complex but it is like that for one reason, maybe we haven't invested enough time learning it. I can't imagine working in a project with 50 or 100 developers without TypeScript.

Maybe because we learned JavaScript without strong typing we always will find much more easier to trow TypeScript away the typical "hugrrr this code should work in JavaScript, why I have this error!!!" The same way you can't remove strong typing from C# or Java, if you are chosing TypeScript as your "Language" is because the size of your project require it, how many developers will work in there? A few? Only me?

Would be something horrible to have a huge block of JSDoc above each function you declared, I'm a huge fan of JSDoc but just to describe and provide concise instructions and @examples about how to use a Generic function or utility function that all our team will be using. Something that TypeScript can't say by itself. It is awesome the time that you can save in virtual calls asking other developer how that huge function can be applied to your case just hovering the function and seeing the description provided by JSDoc

Why should you use JSDoc to describe what an argument is supposed to do and be? when the argument name and a TypeScript speak by themselves?

Nonetheless, as it is often said, comments are for cases when the code can't speak by itself and DO NOT trust in comments because very often you update your code but also forget to update the comment.
And this could and will happen if using JSDoc as source of truth is the way to document your code, your function will say one thing and your JSDoc another.

I wouldn't think that the problem that can be implemented with Typescript can be solved with JSDoc. Specifically, how a function declared with user-defined state and action union types, returns a collection of actions equipped with dispatch, which assigns the appropriate types to the appropriate labels. This provides a type-safe useReducer solution for programmers.

import { FC } from "react";
import { useStateFactory } from "react-state-factory";
import { reducer, initialState, labels } from "@foo/reducer";


export const FooComponent:FC = () => {
  const [state, put] = useStateFactory(reducer, initialState, labels);

  // state and put types defined by user with initialState and labels state
  // in this example one of put actions is put.INSERT_CONTENT(content: number)
  // VSCode or any typescript friendly editor help to list all aviable commands, 
  // with proper parameter(s) type.

  return (
    <section>
      <button onClick={() => put.INSERT_CONTENT(Date.now())}></button>
      <pre>{JSON.stringify(state, null, 2)</pre>
   </section>
  );
}

About this npm module: react-state-factory

Thus, working with JSDoc in this way may entail too much additional effort and make the codebase much more difficult to maintain.

No. You don't just get to call people mean names like zealots just so you don't have to learn something essential. Type safe languages prevent countless bugs and save thousands of hours on the life of projects.

We should not forget, that missing types are not the only thing that distinguishes Javscript from a compiled language. If you write some code in C++ or Pascal, all parts of the code are visited during compilation. So, the compiler is able to find errors that are hidden somewhere in the code, even if this code is not actually executed. Same is true for tree shaking, that can be done by the Linker automatically.

In Javascript, things are different. Many errors stay hidden somewhere in the code, until it is finally executed. So, the ability to do code checks is limited anyway. Typescript may help a bit, but the result is still different from what we have been used to.

So for me the effort using typescript does not pay back most of the time. Adding some more type checks to the code helps, to keep things running.

I definitely fully agree with @mellis481. Article sounds as a joke. TypeScript is the one of the best things which happen with JavaScript world for last 10 years. JSdoc looks like a weird workaround, while typescript gives many great mechanisms and utilities to supply codebase with advanced types including generics. Not that much time ago I heard about Bun. It’s a promising game changer that hopefully will decrease amount of “setup” work of typescript and will greatly speed up (hopefully). And even with all the cons of TypeScript - it’s one of the best (and proven to be the best) tools which everyone should use.