A few things I've come to personally believe after spending years developing web and robotics software in Python/JavaScript then spending years having to maintain while constantly adding new features and dealing with company pivots:
- The types exist whether you write them down or not.
- If they're not written down, they're written down in your head.
- Your head is very volatile and hard for others to access.
- Typing is an incredibly good form of documentation.
- JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
- Make informed decisions on how you'll describe your types, and then be consistent and unsurprising.
- A type checker is the computer saying, "okay then, prove it" about your program's type validity.
- Not every program benefits from the same amount of "prove it."
- Too much can be as bad as too little. You're wasting resources proving throwaway code.
- I like languages that let you decide how much you need to "prove it."
> - I like languages that let you decide how much you need to "prove it."
Rust is known for being very "prove it," as you put it, but I think that it is not, and it exposes a weakness in your perspective here. In particular, Rust lets you be lax about types (Any) or other proved constraints (borrow checker bypass by unsafe, Arc, or cloning), but it forces you to decide how the unproven constraints are handled (ranging from undefined behavior to doing what you probably want with performance trade-offs). A langauge that simply lets you not prove it still must choose one of these approaches to run, but you will be less aware of what is chosen and unable to pick the right one for your use case. Writing something with, for example, Arc, .clone(), or Any is almost as easy as writing it in something like Python at the start (just arbitrarily pick one approach and go with it), but you get the aforementioned advantages and it scales better (the reader can instantly see (instead of dredging through the code to try to figure it out) "oh, this could be any type" or "oh, this is taken by ownership, so no spooky action at a distance is likely").
In practice, though, writing stuff with `Arc` or `.clone()` or `Any` is not as easy as it would be in Python because you've got to write a bunch of extra boilerplate. It's much easier to have local `i64` values that you can pass around as `Copy`. So if all you need are local i64s, then you'll take the easier option and do that.
The same is true at multiple levels. `.clone()` is relatively easy to use, although once you learn the basic rules for referencing, that also becomes easier. `Arc` solves a specific problem you run into at a certain point sharing data between threads, but if you're not sharing data between threads (and most of the time you're not), it's just boilerplate and confusing, so you might avoid it and at worst use `Rc`. `Any` is rarely an obvious choice for most contexts, you really are going to only use it when you need it.
The result is that for most simple cases, the precise and "proven" option is typically the easiest to go for. When you deal with more complicated things, the more complicated tools are available to you. That seems exactly what the previous poster described, where you can decide yourself how much you need to prove a given thing.
> JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
Agreed. Just to clarify, my intentions with this post weren't to advocate for one over the other. Just to point out that they are the same thing. They are both TypeScript.
I don't know how anyone can agree with this, because it pivots on this outrageous claim:
"Like any tools, they both have advantages and disadvantages"
You cannot make any argument based on such a position. Putting aside anyone's views on TS or JSDoc, tooling is of extremely variable quality, and lots of tools ARE objectively much worse than other tools.
It we can't point at tools and say this one is better than that one, we might as well give up.
I always remember a scene in Will & Grace where Will is trying to get his boss to say one thing is better than the other. He's brought a lovingly hand-crafted sandwich made with amazing, bread, fillings, etc. and a store bought sandwich made with cheap bread/fillings. He asks his boss to try both and say which one he likes more.
His boss says something like the store bought one reminds him of his grandma's sandwiches, so invokes nostalgia, and still can't make a decision.
I don't understand how this an outrageous claim. You might say a luxury sports car is objectively better than a cheap minivan, but that is no good to someone who needs to transport around a family.
Or is you problem with the word any instead of many?
I take issue with this position because this seems to imply "PureScript and JavaScript are both JavaScript" is a true statement merely because one of them turns into the other with tooling.
TypeScript is indeed Javascript, all you have to do is remove the type annotations. They are not code.
TS does have some minor things like enums that need to be transformed and are actual code, but those are very few, and leftovers from early days of TS, and the TS authors regret having implemented them. For many years now the TS philosophy has been that the CODE part of TS is 100% ECMAscript, and only annotations, which are not code, are added.
The initial Babel transpiler for TS => JS, and still the most part of the current one, simply removes annotations.
It is recommended not to use the few parts that are actual code and not standard JS. They are certainly not needed any more since ES6.
People may get confused because the type syntax itself is almost like a programming language, with conditions and all. But none of that ends up as code, it's not used at runtime.
One of the IMHO worst design decisions of TS was to bundle type checking and transpiling into one tool. That caused sooo many misunderstandings and confusion.
I think the point here is that all the TS tooling works with JSDoc without any friction. As long as you don't look into the file, from the tooling perspective, a .ts file and a .js file with proper JSDoc annotations are practically the same.
Except the js files can work in the browser as is.. not the ts one (fortunately I might add, I find ts syntax very loaded at times)
Either one is superseding the other one, or they are simply distant cousins, but this is not interchangeable.
TS from JSDoc requires a generative pass to. This is a (expected) level of indirection. (unless some tooling does it automatically)
Yeah. I learned this lesson 25 years ago in university. SQL, Lisp, and whatever scripting language I was learning at the time were always much harder to reason about vs statically typed languages— particularly in team projects. Over the years, I’ve gotten comfortable with SQL, but I always prefer static typing when I can get it.
> The types exist whether you write them down or not
That's easy to say when we're talking about primitive arguments in private functions, or primitive local variables, but let's not ignore the fact that it takes much more work to write a C# program than a Ruby program for instance.
We can see that by looking at a vanillajs library's typescript typings that were created after the js library when typescript didn't exist. The types are insanely complex and if you get one type wrong you can break compilation of some library user's program (its happened to me).
That being said I'm aware that dynamic programming languages are a "use at your own risk" type of language.
are dynamic languages really a "use at your own risk" ? or it's about changing frame of mind ?
my take is if you treat your program as a series of data flows - then use primitives such as maps | arrays - then you don't need as much typing or typing at all. a map doesn't need to take a shape or a Person | Manager - either the keys exist or they don't and almost every language has guards to ensure you can safely navigate existence of keys.
but then again my realm is mostly around - web | data systems - if I was dealing with OS level systems and needed to make sure i have i64 ints then yeah typing would be crucial.
And if your boss is the type to pivot way too often and want it done yesterday, then they don’t deserve code that is prove in the right places so you just get an LLM to add typing to everything after the fact…
Typed code is significantly more cumbersome to change (because there's more code to change). At least until you reach a certain size of your spaghetti bowl. Then both typed and untyped are cumbersome and people endlessly discuss which one is more.
I don’t think so. With a good editor, you change the type and run the compiler which will warn you with all the locations you’ll need to edit. Then you can quickly navigate to those locations.
> which will warn you with all the locations you’ll need to edit
This is true, but with a program built with a dynamic language, taking advantage of the fact that it's written in a dynamic language, doesn't need to make those changes at all.
I'm fan of static typing in many situations, but it's hard to deny it doesn't lead to more changes as you need to properly propagate changes.
I don't find that dynamic typing reduces the number of places I need to update stuff. It just changes when the error occurs.
If I change the shape of some data (such as renaming object properties), I'll need to update all the code that used that data, regardless of the type system. Static typing just ensures that I catch those cases at compile time, not runtime.
Just one simple and contrived example I could come up with the five minutes I had available:
JavaScript:
// rename host -> hostname, update ONE place
function connect(opts) {
const host = opts.hostname ?? opts.host; // compat shim
return `tcp://${host}:${opts.port}`;
}
// old call sites keep working
connect({ host: "db", port: 5432 });
connect({ host: "cache", port: 6379 });
// new call sites also work
connect({ hostname: "db", port: 5432 });
TypeScript:
// same compat goal, but types force propagation unless you widen them
type Opts = { port: number } & ({ host: string } | { hostname: string });
function connect(opts: Opts) {
const host = "hostname" in opts ? opts.hostname : opts.host;
return `tcp://${host}:${opts.port}`;
}
// If instead you "just rename" the type to {hostname; port},
// EVERY call site using {host; port} becomes a compile error.
Again, this is just a simple example. But multiply 100x + way messier codebases where everything are static types and intrinsically linked with each other, and every change becomes "change -> compile and see next spot to change -> change" until you've worked through 10s of files, instead of just changing it in one place.
Personally, I prefer to spend the extra time I get from dynamic languages to write proper unit tests that can actually ensure the absence of specific logic bugs, rather than further ossifying the architecture with static types while changes are still ongoing.
In your Typescript example, the solution would be to use your IDE to refactor hosts to hostnames, a process that takes like 2 seconds. You might have problems if the change exists at a service boundry, but in that case I'd just put the transformation at the service boundry, and keep everything the same internally.
> Personally, I prefer to spend the extra time I get from dynamic languages to write proper unit tests that can actually ensure the absence of specific logic bugs, rather than further ossifying the architecture with static types while changes are still ongoing.
I'd argue static typing makes this much easier, because I know any input types (or output types from other components) will be enforced by the type system. So I don't need to bother writing tests for "what if this parameter isn't set" or "what if this function returns something unexpected". The type system handles all of that, which eliminated a lot of tedious boilerplate tests.
> In your Typescript example, the solution would be to use your IDE to refactor hosts to hostnames
Yeah, sure, and with LLMs you can do this, and you can do that. But if we're talking about languages and their features, relying on IDE features feels slightly off-topic.
But regardless, changes is changes, no matter if you, your IDE or your LLM made them. So even if your IDE makes the changes, it seems at least you can now agree that there are more changes needed, it's just that with TypeScript you have a editor who can help you refactor, and with JavaScript you haven't yet found an editor that can do so.
> So I don't need to bother writing tests for "what if this parameter isn't set" or "what if this function returns something unexpected".
Yeah, those unit tests does nothing, and people who write in dynamic languages don't write tests like that either. You test actual logic, in unit tests, and you rely on the signals that gives you.
In fact, I could bet you that if you and me both sat down and wrote the exact same application, one in JS and one in TS, we'd end up with more or less the same amount of unit tests, yet the JS codebase will be a lot more flexible once product requirements start to change.
But again, YMMV and all that, it's a highly personal preference. I don't think there is a ground truth here, different minds seem to prefer different things. I mostly work in environments where the requirements can change from day to day, and being able to adopt to those without introducing new issues is the most important thing for me, so with JS I stay.
> Yeah, sure, and with LLMs you can do this, and you can do that. But if we're talking about languages and their features, relying on IDE features feels slightly off-topic.
Refacoring tools (such as renaming properties) have been supported by IDEs for decades. And in Typescript specifically, the language is designed with these tools in mind, which are developed and distributed directly by the Typescript team. For all intents and purposes, IDE integration using the Typescript language server is a feature of Typescript.
And if somehow these tools don't work, the compiler will catch it immediately! This means I can refactor with confidence, knowing any type issues will be caught automatically.
It seems like you're vastly overestimating the time and effort it takes to change types in Typescript. In my experience it's something that takes basically no time and effort, and has never caused me any issues or headaches.
You're changing the point though, you claimed "I don't find that dynamic typing reduces the number of places I need to update stuff", which just because your editor makes the change, doesn't suddenly make the change not show up in the diff for you and others. A change is a change, regardless of how it's made, unless you don't keep your code in a SCM that is, which I'm assuming most of us do.
I'm not saying it's hard to change types in TypeScript, I understand that your IDE is connected with the language and they're used together, but again my argument was that having types leads to having to change things in more places. Which is true too, and it's a good thing, it's on purpose, and the tools you use help with that, so yay for that! But it's still more changes, and at least for me it's important to be honest about the tradeoffs our choices leads us to.
As I mentioned earlier, I'm fan of static typing in many situations, just not all of them. And I'm not blind to the negatives they can bring too, I guess I just see more nuance in the static typing vs dynamic debate.
Regardless of how dynamic typing is, the contract being enforced stays the same. It's just less enforced by tools. So with dynamic typing, you will have to change the same amount of code if you want your code to stay correct. The only variation in code changes comes from the annotation for the type system.
> So with dynamic typing, you will have to change the same amount of code if you want your code to stay correct.
No, because if a piece of data is pushed through multiple layers you can just change its type at the source and the destination and not in all the layers the data is pushed through. And you can still be correct.
Imagine you have a thing called target which is a description of some endpoint. You can start with just a string, but at one point decide that instead of string you'd prefer object of a class. In dynamic language you just change the place where it originates and the place where it's used. You don't need to change any spot in 3 layers that just forearded target because they were never forced assumed it's a string.
You can achieve that in staticly typed language if you never use primitive types in your parametrs and return types or if you heavily use generics on everything, but it's not how most people write code.
Tools can help you with the changes, but such refactors aren't usually available in free tools. At least they weren't before LLMs. So the best they could do for most people was to take them on a journey through 3 layers to have them make manual change from string to Target at every spot.
In some type systems, you don't need to change it either. Errors will happens only if you've written code that assumes that `target` is a string. If I write a function with the following signature:
fn split(str: string) => string[]
And you called it with
const first_el = split(target)[0]
If you decide `target` to suddenly be an object, then the code you wrote is incorrect, because semantically, `split` only makes sense when the argument is a string. Which is why, even with dynamic typing, you'll see that the documentation of a function will state what kind of parameters it expects.
If you a call chain like `fn1 | fn2 | fn3 | fn4 | split`, Then yeah you need to ensure what reaches `split` is in fact a string. If you're against updating fn[1-4]'s signature, let's say that it's harder to find which function needs to change in a dynamic typing systems.
Dynamic typing is useful for small programs and scripts because they are easy to iterate upon. But for longer programs, I'll take static typing anytime.
Not really. Strongly typed languages don't usually support not having any types in your code (or any amount of gradual typing). At least not with any convenient syntax. There's usually some one clumsy "dynamic" type that doesn't interact with the rest of the system well and you'd be crazy to start writing your code using only this dynamic type.
I can't just write C++ like:
any a = 1;
a = "Hi!";
I also can't tell JS this shouldn't be allowed. But I can tell this to TS, at any stage of evolution of my program.
I'll take a more definite position. Build pipelines are the devil. Every square inch of surface complexity you add to whatever you're doing, you will pay for it. If there's a way to get the benefits without the build step, that's your choice. You may need runtime type enforcement, so that's not JSDoc, and you're doing that with... JS so that's already suspicious but the use case def exists. JS, the DOM, HTTP, this whole stack is garbage at this point so arguing about the type system is a little idk hard to care about personally. I have a solution that lets you discard most of the web stack, that's more interesting to me.
I'm a fan of anything that allows me to build with javascript that doesn't require a build step.
Modern HTML/CSS with Web Components and JSDoc is underrated. Not for everyone but should be more in the running for a modern frontend stack than it is.
On the one hand I can see the appeal of not having a build step. On the other, given how many different parts of the web dev pipeline require one, it seems very tricky to get all of your dependencies to be build-step-free. And with things like HMR the cost of a build step is much ameliorated.
Any kind of downleveling, though that's less important these days most users only need polyfills, new syntax features like `using` are not widely used.
Minification, and bundling for web is still somewhat necessary. ESM is still tricky to use without assistance.
None of these are necessary. But if you use any of them you've already committed to having a build step, so adding in a typescript-erasure step isn't much extra work.
No Lit Element or Lit or whatever it's branded now, no framework just vanilla web components, lit-html in a render() method, class properties for reactivity, JSDoc for opt-in typing, using it where it makes sense but not junking up the code base where it's not needed...
No build step, no bundles, most things stay in light dom, so just normal CSS, no source maps, transpiling or wasted hours with framework version churn...
Such a wonderful and relaxing way to do modern web development.
I love it. I've had a hard time convincing clients it's the best way to go but any side projects recently and going forward will always start with this frontend stack and no more until fully necessary.
This discussion made me happy to see more people enjoying the stack available in the browser. I think over time, what devs enjoy using is what becomes mainstream, React was the same fresh breeze in the past.
I have not written a line of JavaScript that got shipped as-is in probably a decade. It always goes through Vite or Webpack. So the benefit of JS without a build step is of no benefit to me.
I've built Solarite, a library that's made vanilla web components a lot more productive IMHO. It allows minimal DOM updates when the data changes. And other nice features like nested styles and passing constructor arguments to sub-components via attributes.
It's ok now, at least for me. There are still challenges around theming and styling because of styling boundaries (which makes Web Components powerful, but still). A part of it is about tooling, which can be easier to improve.
It's a shame Surplus (Adam Haile's, not my succession of it) isn't cited nor is he mentioned, given that at least two of the listed frameworks were heavily and directly inspired by his work. S.js is probably one of the most incredible JavaScript libraries I've used that should be the reference for a signal API, in my opinion.
Agreed on native HTML+CSS+JSDoc. An advantage in my use-cases is that built-in browser dev tools become fluid to use. View a network request, click to the initiator directly in your source code, add breakpoints and step without getting thrown into library internals, edit code and data in memory to verify assumptions & fixes, etc.
Especially helpful as applications become larger and a debugger becomes necessary to efficiently track down and fix problems.
No, because layers of abstraction come at a cost and we have created a temple to the clouds piled with abstractions. Any option to simplify processes and remove abstractions should be taken or at least strongly considered.
Code written for a web browser 30 years ago will still run in a web browser today. But what guarantee does a build step have that the toolchain will still even exist 30 years from now?
And because modern HTML/CSS is powerful and improving at a rapid clip. I don't want to be stuck on non-standard frameworks when the rest of the world moves on to better and better standards.
> Code written for a web browser 30 years ago will still run in a web browser today.
Will it? - My browser doesn't have document.layers (Netscape) It seems to still have document.all (MSIE), but not sure it's 100% compatible to all the shenanigans from the pre-DOM times as it's now mapped to DOM elements.
Having all your code go through a multi-step process that spits out 30 different files makes it impossible to know what’s really happening, which I’m uncomfortable with.
So, some history. When SPA's started to boom on the web JSDoc was a life saver for typing. Application state was getting more complex. We needed more guard rails.
Then Google Closure Compiler came along which added type safety via JSDOC and TS came along with (TS)JSDoc support and it's own TS syntax.
The community chose native TS and Google Closure compiler slipped away into the background.
So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
Today I use TS. I also use plain JSDoc for documentation. e.g. @link and @see for docs. Or @deprecated when I'm flagging a method to be removed. @example for a quick look up of how to use a component.
TS and plain JSDoc are both important together. But (TS)JSDoc alone, is a relic of the past.
> Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
This was my main impetus for writing this article. Modern JSDoc uses the TypeScript language service. You can use generics, utility types, typeguards (including the `is` keyword), regex parsing, etc all with just JSDoc.
I used these features extensively (especially generics) in a personal project and managed to do it all in JSDoc.
JSDoc is missing a lot of basic capabilities. For example a TypeDef is automatically exported which can cause collisions and forces you to repeat or inline types.
Types for classes are poor and often you'll find yourself creating a `.d.ts` file or `.ts` file to export non trivial types - however the target file doesn't know how to consume them.
You cannot replicate `import type { x } from './foo'` without also re-exporting that import - which causes collisions.
The alternative is to do an inline `const foo = /** @type {import('./foo').x} */ ({})` however this gets messy, repetitive and it's difficult to use algebraic types (e.g. `Event & { detail: string }`)
JSDoc does not understand typescript syntax though? The typescript language server just kinda plows through/over JSDoc sure, but try getting JSDoc to parse some of the TS-ified things that JSDoc has alternatives for.
You are attempting to generate documentation from jsdoc comments using an npm package that is also called "jsdoc". Ofc in this case "JSDoc is not TypeScript". That package only supports the subset of JSDoc that is relevant to it. Though I believe you can use TypeDoc instead if you want to generate documentation from JSDoc that contains typescript types.
In the post I made it explicit that I'm talking about intellisense, developer tooling, type checking etc. You can run `tsc` to do typechecking on a project typed with JSDoc like the examples I've given throughout this thread just fine.
I guess the difference here is I'm coming at this from the perspective of "what is TypeScript used for. Can JSDoc comments substitute that". And the answer is almost completely yes.
Apologies, my first draft of that comment got deleted on a refresh (mobile) and my posted one left out how I'm probably being too pedantic: the official JSDoc is not TypeScript.
Your post is actually one of the more accurate ones compared to others that say "you don't need typescript" with the big caveat that you actually need a whole lot of the typescript ecosystem to make JSDoc work.
I just wish there was an official handover, or a more clear delineation between JSDoc and Typescript JSDoc Extensions.
I think you have a valuable point. I kinda purposely avoided explicitly defining what JSDoc is. Instead I'm relying on "the JSDoc we're all familiar with". I said in the post that if your IDE is giving you intellisense from JSDoc comments then you are almost certainly already using TypeScript. That's about as close as I got to defining the JSDoc I'm talking about
But given that JSDoc doesn't have any sort of formal spec, I think the distinction you're making is more of a historical than a technical one.
This was an interesting and useful post but you’re kind of losing the plot here in these comments defending against what should be a straightforward minor correction.
JSDoc has been around for more than twenty years and most implementations have never had most of the capabilities you’re describing.
It is actively misleading for you to say that JSDoc has these capabilities when you’re referring specifically and exclusively to TypeScript’s implementation of JSDoc, or you could say TypeScript’s alternative JSDoc syntax. Closure always used language like that in their documentation, and explicitly called out that they had diverged from standard JSDoc, as they should have. TypeScript’s own documentation sometimes refers to it as their superset of JSDoc, again recognizing that “JSDoc” actually does mean something specific and different.
The fact that there may not be a formal technical spec doesn’t mean you’re not wrong and it’s preposterous to suggest that.
There was established tooling and documentation going back 25 years, and it doesn’t somehow not count just because they didn’t give you a formal grammar…
I’m curious how type checking is possible in a JDoc project. As far as I’m aware there’s no way to get type checking to work without tsc or a TypeScript LSP plugin.
That is exactly how it works. Any IDE providing you intellisense is using the TypeScript language service. That's why this article is called "JSDoc is TypeScript". If you see a red squiggly because of your JSDoc comment, you are almost certainly already using TypeScript (without any .ts files)
Ha! I see I elicited the copy/paste response I’ve seen elsewhere. The gp comment I was replying to implied a JSDoc only solution (“all in JSDoc”), but given the response, clearly they’re still relying on the TypeScript language service (aka lsp plugin) to achieve type checking inside their IDE.
Wishful thinking on my part that an alternative solution for JSDoc based type checking exists :)
Generally, no. Only in the case you had a requirement to exclusively use JavaScript as the programming language you might be in for an awkward time justifying that you added type checking to the project via the type checker component of TypeScript with JSDoc :)
Depends on your definition of "using" JavaScript. The main difference between common TypeScript and TS-based JSDoc is the need for an additional build step. Being able to ftp-upload your `.js` files and then be done with it is a remarkable advantage over Vite/Webpack/whatever in small to medium-sized projects. If editor based type support is sufficient to you (i.e. no headless checks), you won't need to install any TS packages at all, either. tsserver is still used in the background, but so are thousands of other binaries that keep your editor, OS and computer running, so I don't see that as an argument.
> So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
> Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
None of that is true! Please don't share misinformation without looking it up first.
1. there are plenty things you can't express in jsdoc but can in typescript, flow did the right thing here where you have access to full language, not sure why typescript never did it, they could, with the same syntax flow is using
2. you can have navigation that goes to typescript file instead of definition, just arrange your exports in package.json correctly (first ones take precedence)
Well I'd love to hear some concrete examples if you have any on hand! I was of the same opinion as you until I refactored a project of mine to use JSDoc.
Since any TypeScript type can be expressed in JSDoc, I imagine you're mostly thinking of generics. At least that was my main sticking point. JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive but involves typing the return type. E.g. for a function it'd look like this:
I don't understand why someone would opt for "write Typescript, but add a bunch of extra characters, make the syntax clunkier, and throw away all the benefits of compile-time errors because we'd rather have runtime errors" in order to save, what, a microsecond stripping typescript out of TS files?
Everyone's complaining about "the build step" but the build step is just an eye blink of stripping out some things that match a regex.
> throw away all the benefits of compile-time errors because we'd rather have runtime errors
This is inaccurate on multiple counts. First of all, you can still run tsc with JSDoc if you want a hard error and you can still use strict mode with JSDoc. Your tsconfig file governs JSDoc-typed code just the same as it governs .ts-typed code. In both cases you can also ignore the red squigglies (the exact same red squigglies) and end up with runtime errors.
Nobody is advocating for reduced type safety or increased runtime errors.
I also think there are many valid reasons to loathe a build step (like not dealing with the headache that is the discrepency between the way the TS compiler deals with import paths vs js runtimes).
All that being said, I'm not really trying to convince anyone to stop using TypeScript. I'm simply pointing out that using JSDoc is using TypeScript. It's the same language service.
Things like type star imports, destructured imports or satisfies operator don't work in jsdoc.
All non erasable constructs won't work as well of course but playing devil's advocate you could explicitly state that you're interested in erasable constructs only because ie. 1) that's what typescript should be doing from day 1 and/or 2) it seem to be the future with ie. nodejs adopting built in type erasure support.
Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved. Things that work fine in TypeScript trigger errors even though they are syntactically the same.
Because AirBnB's ESLint config has been burned into my brain I almost only use arrow functions. I also use generics extremely often. It's definitely a little more clunky but I haven't run into anything you can do in TypeScript that you can't do in JSDoc.
JSDoc also allows you to type stuff in-line. For example I often have to type an empty array like so:
(I had to make it a little bit different from the JS code to make it compile)
(Well, this is not exactly about arrow function I guess. I remembered that part wrong.)
Note that I cannot make the type check in JS code to pass. Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.
Try this out. I think it's a much more faithful representation of your TypeScript example too. JSDoc just wants you to be explicit about the default for generic slots (which is `unknown` in TypeScript).
Ah I see. Looks like you avoided using the "@callback" tag but instead used the "@typedef" tag directly. Thanks!
I do think it illustrates a problem with TypeScript's support for JSDoc though. You see, I started with the code in JS and could not make it work, after which I translated it to TS. In JS/JSdoc, "@callback" is the "idiomatic" way of defining a function callback type with JSDoc. (It also makes it easier to add documentation for each parameter if necessary.) And indeed, @callback works the most of the time, except in such cases where these JSDoc tags don't work nicely together, and these alternatives become necessary.
This is absolutely a fair point. JSDoc predates TypeScript by over a decade. It's not until more recently that the syntaxes have started to converge.
My brain definitely works in TypeScript so I tend to translate from there. I definitely consider myself more familiar with TypeScript than with JSDoc, but sometimes (e.g. here) that's a benefit not a weakness
that's not "jsdoc is typescript" anymore because you're falling back to something else - type definition files where you do have access wider typescript functionality.
also not a full solution - for .d.ts types to be available globally without explicit import the .d.ts file itself cannot use any imports/exports. this means you can't reuse types from other places to construct your types. you can workaround this by explicitly importing .d.ts in jsconfig/tsconfig but you're still left with other issues.
those types do actually become globally visible everywhere polluting global namespace which is bad in itself
there are no guarantees about them being in sync with actual code, which violates the whole point of using type safety.
they don't solve cases where you need typescript inlined functionality locally in your code or to perform assertion with satisfies operator etc.
Having JSDoc-like syntax isn't the same as it being fully supported. If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
> If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
You keep repeating this throughout the thread. Can you give an example?
Thanks for the example, I had a good play around with it.
The second part of my comment is a value yes, but it's implicitly typed by typescript automatically. I was asking about how to use that type (and it's internals) in jsdoc.
it is possible to do many of these with @typedef, but it gets difficult with JSDoc very quickly. In TypeScript you can easily create multi-line type aliases. Not quite so in JSDoc.
TypeScript's type system is Turing complete so you have access to essentially unlimited expressivity (up to the typechecking termination depth): https://news.ycombinator.com/item?id=14905043
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
ok i didn't think about this, that's an underrated benefit
It doesn't. You might be thinking of libraries that you wrote, not packages from e.g. npm, which are distributed as JavaScript + type definition files not as TypeScript code.
In real IDEs, not glorified text editors like VSCode, it does. I use this often in IDEA, it's muscle memory so I'm not even completely sure what to press, but it's likely "go to definition" and by default is tied to ctrl+alt+b.
IDEA adds its own analysis on top of that provided by the language server.
Works on JS + every variant of type definitions I've ever seen, among many other things (not only programming languages, but also database objects, etc).
> IDEA adds its own analysis on top of that provided by the language server.
IDEA implements its own analysis and doesn't use tsserver at all. Its semantics diverge in subtle ways, I believe in both directions (some code that tsserver considers valid IDEA will consider invalid and vice versa).
5 years ago I was at a meet up and the guy talking was saying how if you don't like typescript these jsdocs are the way to go. Had to explain to my employer attending that it is still typescript. Didn't seem to believe me and was super against typescript but not jsdocs lol
> Had to explain to my employer attending that it is still typescript
"is" is doing a lot of heavy lifting there: JSDoc and TypeScript are two different ways to explicit prescribe typing in a way that tooling can use to determine correctness. The TS syntax is _far_ more powerful, but JSDoc can do most of the common TS use cases, for folks who want to stay in JS land while still benefiting from type tooling (either invoked or straight up built into the IDE).
> in a way that tooling can use to determine correctness.
As I pointed out in the article, the "tooling" is exactly TypeScript language services. If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
You can copy-paste basically any bit of TypeScript into a JSDoc comment and it will work. JSDoc supports any non-runtime feature of TypeScript (so not enums). Even generics! You can even reference TypeScript utility types!
The whole point of this article was to correct the idea that JSDoc is not TypeScript. It absolutely is! There's almost nothing you can't define in JSDoc that you can't define in a .ts file. Albeit with a sometimes clunkier syntax
By "JSDoc is TypeScript", culi means "JSDoc syntax and TypeScript syntax are two alternative ways to describe types to the TypeScript compiler/language services, and the two syntaxes have nearly-identical expressive power".
> If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
This is true in the same way you are "using" C++ if you are on Windows. When most people say "use XYZ language" they mean "are personally writing code in XYZ language" rather than "under the hood my code is transpiled to this other language I don't write in"
In practice today JSDoc 100% completely and utterly always is Typescript.
It might not have been so originally. It might still be possible to do differently. But in practice today you are getting Typescript in your JSDoc with the out of the box tooling that is everywhere.
I tried making a library this way and lacking control over the visibility of the exported types was really painful; it made my intellisense awful because every type I defined at the root was exported from the library
I really like it for web components. Lately I have many "my-component.js" files and it's quite nice to just be able to copy them to new projects and have it all work without a build step. But I'm not sure I would use JSDoc over typescript syntax in a large project.
> Take it from a massive TypeScript nerd: JSDoc is not an anti-TypeScript position to take. It is the same powerful static analysis without the build step.
Technically there's still a build step happening under the hood! But another benefit of shifting TS into JSDoc comments is that it also works in browsers. That being said, while I understand the aversion to unnecessary complexity, I'm personally fine with a build step to remove TS. It's a much nicer syntax IMO. And with tools like `swc` for type stripping, it's pretty snappy too.
I'm actually using JSTypes in app, I don't mind it.
I choose to use it because I didn't want to deal with a build step for a smaller project. The project has grown and I am looking at adding a build step for bundling but still not too worried about using JSDoc over TS.
This might be my config, but one thing that does annoy me is whenever I define a lambda, I need to add an doc type. I guess if that's disincentivising me from writing lambdas maybe I should just add a TS compile step lol.
These days you can run TypeScript files as-is (type stripping) for testing in many runtimes, and for bundling, most bundlers support using a ts file as the entry point directly.
yep! However this is a website I made for hosting my own notes in the browser browser (sorry for the load times, no bundler so each file is a seperate request)
JSDoc is great. But remember, JSDoc is used for well trained developer. For those junior programmer, they will totally ignore it and write lots of shxt code. At least TypeScript can force them to use correct type like forcing them not to use "any" type.
Thanks, I use JSDoc for several years, and also validate it with Typescript.
So I just write plain Javascript with JSDoc, with no build step.
Typescript only validates the types, and not transforming the code.
Did you also know that you can import Typescript types/interfaces in JSDoc?
So for me typescript is not a language anymore, I use only the tool to validate the types.
Best thing for me was not removing the code transformation (convert ts to js), but separate runtime code with documentation code, like the types.
Gives you much more clear insight that the types you write to describe what you expect the type will be is not forced on runtime, but is just for you as developer to know it.
And when you validate the input is the right type, it is much more clear that it is the runtime type validation.
You can still use JSDoc in your typescript files, but why do you want to do that? There is no reason to do that.
So using JSDoc or Type Annotation, both works the same, same benefits, it is only personal preferences. Both have its pros and cons.
For me the JSDoc has more benefits.
Some other people prefer annotations.
But there is not 1 that is better in controlling the types, has more options.
(Also the enum can be done if you are using JSDoc, but is a little different)
I work in a codebase that unfortunately does not support TypeScript. I use JSDoc extensively, although not with type check enabled (due to various limitations). I also work on other projects with TypeScript. My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc, without question. JavaScript with JSDoc is much more verbose, with a lot of limitations when types get long or complex compared to TypeScript. The official TypeScript language service also does not provide the same level of support in very subtle ways.
Basically, the fact that it works does not mean it works well, and I don't recommend anyone going in this other direction unless they understand what they are getting into.
Not a limitation in language service, but an issue with the codebase itself -- legacy codebase with a lot of missing/incorrect typing from upstream JavaScript code (owned by other teams), making it practically impossible to actually run type check.
Been there, tried that. When starting to write JavaScript in anger 3 or 4 years ago, I started out with JSDoc, because my impression was also, hey, that is like TypeScript, but closer to the metal and maybe with less magic. A few months in I realised that TypeScript is just a better and more well-rounded implementation of what JSDoc has to offer (I don't remember now, but there were annoying things that you would expect would work in JSDoc, but didn't quite).
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
More broadly, this is the default behavior of JS even without JSDoc blocks, and it ought to be the default behavior everywhere, including TS. I'm not alone in this sentiment, but it's incredibly contentious. There's been an open GH issue about it with hundreds of replies for years. I have no idea why they can't just pick a different shortcut for viewing types and call it a day. They'd be doing the entire ecosystem a favor.
To be honest, I find Ryan Cavanaugh's argument against this quite convincing. It's weird to have something documented if you import the .ts file, but not if you import a .d.ts generated from it. If you want to show the value of the default argument of a function, you should probably just add it to the doc comment — not the type.
JSDoc works great for buildless application setups! One downside is that if you publish a library to npm you still need a build step to generate .d.ts files from your JSDoc type annotations so that npm shows a "TS" badge on the npm package page. This also seems to apply to VSCode's intellisense which keeps trying to poke you to "try to install @types/jsdoc-typed-package to get type information". Other JS ecosystem tooling also doesn't seem to process JSDoc types at all such as jsdocs.io or tsdocs.dev. So for libraries we're stuck with .d.ts generation via "tsc --allowJs --checkJs --declaration ..." even if it's all JS.
A somewhat related thing programmers must understand is that whether you write typescript, JSX, .astro or .svelte files, you are technically not writing JavaScript.
You should occasionally look at the build artifacts of your framework but also ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Lately I just use vite with no starter template but with web components and css modules. It at least feels more convenient than using any framework or library.
This seems like an issue but in all my practical experience it really isn't. TypeScript becomes JavaScript with the types removed. Then you tree-shake, minify, and whatever is executed is no where near what you actually wrote but at the same it totally is the same because that's no different than any other compilation process.
Occasionally, I have to remember that JavaScript has no types at runtime but it's surprisingly not that often.
I mean what makes it more acceptable is that you have HMR and instant preview during development. So, all the transformations and bundling aside, you do see how it runs during development.
However I have been in a few situations at work where all of a sudden we did have issues that required us to dig deeper. There were also some bundling related issues that caused problems in production deployments. At that point many co workers had no idea how to even approach it to be honest.
I've had similar experiences with compiled languages in one form or another throughout my career as well. I don't think JavaScript is particularly special that we need to call it out for things like TypeScript, minification, or bundling.
That's correct, however I would say there is a small difference in that most of this code still seems just like JavaScript, sometimes it even feels as though it is JavaScript running in the same context when it then gets compiled to run on server/client.
I think the point I'm trying to make is that this can be confusing or even dangerous especially for new developers. It just doesn't hurt to actually look at the Vite plugins transforming it all to understand it instead of making assumptions if we work with it on the daily.
Yeah it’s a silly line of reasoning. The transformations of TS -> JS are a lot smaller and simpler than C-> asm / machine code; it’s basically just removing type annotations. Now minification and optimization can make the output a lot more terse, but that can be done for JS too. And it’s not as complicated and detached from the source as an optimizing compiler is.
Let's not act like it's the same thing. I'm not strictly talking about just Typescript, I'm saying that if you work with these technologies every day it would be wise to go look at their Vite plugins to see how they transform your code and be sure to understand it. It's nice to have magic but it's nicer to use the magic if we have demystified it first.
And I don't know about you, but I occasionally do open compiled ELF files in a hex editor and I certainly did at first when I was learning more. That's a good practice also.
Somewhat. I could still use framework agnostic state management libraries/patterns and most are (e.g. svelte signals, jotai, zustand, etc.).
I've even used Proxies directly to implement some reactivity before. However as for the "declarative" parts, I think it's just a little bit of a different way to work but you get used to it and imo it pays off. Knowing the web APIs should be a requirement anyway and it doesn't hurt to work with them directly as much as possible.
Many of us don't encounter the sort of problems Typescript offers to solve. As most programming languages, most of the bugs I create when using JS is logic bugs, and those are solves by unit testing, not "more types". It was a long time ago I managed to push broken frontend code because of assuming the wrong types, so personally I don't find TS that valuable. But obviously others seem severely impacted by those types of issues, otherwise TS wouldn't be so popular in the first place. People be different :shrug:
I still think that JS is very much not TS. Most TS code assumes you never need to check for errors because the type checker proves they can't happen.
Then, paradoxically, with no error checking at runtime, it becomes fully possible for JS code to call into TS code in a way that breaks the shit out of the TS compiler's assumptions. In philosophy then TS and JS are as incompatible as GPL and EULA
It doesn't matter if a library is written in TS or JS; you cannot meaningfully protect against other code calling you incorrectly.
Sure, you can check if they gave you a string instead of a number. But if you receive an array of nested objects, are you going to traverse the whole graph and check every property? If the caller gives you a callback, do you check if it returns the correct value? If that callback itself returns a function, do you check that function's return type too? And will you check these things at every single function boundary?
This kind of paranoid runtime type-checking would completely dominate the code, and nobody does it. Many invariants which exist at compile-time cannot be meaningfully checked at runtime, even if you wanted to. All you can do is offer a type-safe interface, trust your callers to respect it, and check for a few common mistakes at the boundary. You cannot protect your code against other code calling it incorrectly, and in practice nobody does. This is equally true for JS and TS.
Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though. Dealing with external input requires type assertions (since Typescript doesn't know what the program is getting at compile-time) and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
However, if your point is that Typescript can lull people into a false sense of safety, then sure, I take your point. You have to understand where type assertions are coming into play, and if that's obscured then the type safety can be illusory. The benefits of Typescript require you to make sure that the runtime inputs to your program are sufficiently validated.
> Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though.
If it's a service, yes, and that's true no matter what technology the service is using. If it's a library, no, because...
> and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
That's on whoever is using the library, not the library author. If the library author provides type definitions, and you as the consumer choose to ignore them, then it's on you.
Sure, but if the caller is Javascript then you're running Javascript, not Typescript*, so it makes sense that you're not going to get type safety.
I'm also not sure we're actually disagreeing on anything, so perhaps my reply was pointless. I agree that if you mix JS and TS in the way you describe, you'll have problems. My reply was just to say "yes, and that's not really Typescript's fault", but perhaps you weren't implying that to begin with.
* I'm aware that you can't run Typescript directly, but I hope my point here is clear... you're running a program that wasn't type-checked by TS.
I don't think we're disagreeing either. I didn't mean to suggest that it was Typescript's fault, just that the relationship between TS and JS in theory is something like "TS is a superset of JS" but once you get down to the practice of writing idiomatic reusable code it's more like TS and JS are fully different languages.
The type checker can only prove what is known at compile time and only if you're disciplined.
To bridge runtime and compile time (as your application will likely get some external data) you've got to use a proper parser such as zod[1] or if you want to stretch it even further effect-schema[2].
What's the difference here? I've only used Zod but I typically think of Zod as a runtime validation library. AFAIK arktype is a full-featured replacement for Zod
I don't think I understand the difference you're drawing on here? It parses data and validates its structure, and is a replacement for all my uses of Zod?
This is how I develop web software, and I've found it productive and maintainable.
A bonus of this approach is that it clearly delineates what type information is available at runtime, vs what type information is just a comment. (especially useful when working with serialized data).
I also like that it generally means all of the preconditions and postconditions for functions are in a single place (both the prose and the technical information are in the JSDoc comment), keeping the code itself low-noise and boiled down to its essence, and providing a natural place to write example inputs and outputs to guide usage.
As for generic types, I use them extensively, and this is made less verbose e.g. on function calls by using an @type annotation on the function which accepts a TypeScript signature without needing separate @template + @param annotations.
It's awesome stuff, and I'm happy that TypeScript works so well with JSDoc!
I'm a big advocate for explicit type annotations in code. Likewise, either or is good with me. However, these days I lean towards using JSDoc only because I prefer not to add typescript lib and an additional build step just to get type safety in a project.
Also, you can use both (if that's what you prefer).
Yes. As described in the article, the TypeScript compiler understands type annotations that are written in JSDoc syntax. So you can use `tsc`, just like you would to check `.ts` files.
Personally, given the limitations of JSDoc, I'd like to see a header-file like definition system for build-less applications (like libraries).
/
index.js
index.d.ts
Where values in `index.js` can be typed in the header file with complete TypeScript syntax and those types are present in the target file via intellisense and type checking
// index.js
function useStr(x){} // has intellisense for "string"
useStr("Hello")
useStr(42) // IDE and type checker error
And
// index.d.ts
declare function useStr(x: string): void
This can be done, and is done in some projects, but the problem is that you need to manually maintain both sets of files, which can easily go out of sync if you're not careful. You also lose out on the ability to check your own code - using the header file you've written there, you can't really check the implementation of `useStr` to check that it works.
The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code, which means you've still got access to type checking inside your functions.
One thing I've seen in a few places is still to have DTS files that declare all sorts of types that are used in the application, and then have those files imported by JSDoc comments. That way, you've got TypeScript syntax for your types, which tend to get bulky and difficult to read in JSDoc syntax, but you still don't need a build system because the DTS imports are ignored completely at runtime.
You can define a declaration file alongside its target however the target does not use the types defined within its declaration within itself - only consumers see the types.
There are three issues with that.
The first is that JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining (like typedef causes collisions, there's no importing a type without also re-exporting it from the importing file unless you inline the import)
The second is that JSDoc isn't picked up from imported libraries (or at least I don't think it is?)
Lastly, you still need a transpiler to remove the comments and build d.ts files.
In the end, JSDoc isn't practical for projects. The header file strategy means you don't need to transpile ever (only a typechecker) and you'd get the full suite of TypeScript functionality - at the cost of synchronization overhead.
For a project using JSDoc, you'll graduate to TypeScript when there is sufficient complexity anyway. Migrating from a d.ts file is way easier (potentially automatable) than migrating from JSDoc.
The problem with the header file strategy is that TypeScript doesn't have total type inference. That approach works e.g. in OCaml, where you can (optionally) type the boundaries of the function and everything inside the function can always be inferred. But TypeScript works differently and doesn't support that approach. So fundamentally, what you're describing isn't really possible without using a very restrictive subset of TypeScript that can be totally inferred or having very broad type definitions.
So even if TypeScript did check the header file against the implementation, you'd still need additional annotations inside the implementation file. At that point, why not put all the annotations inside the implementation file directly?
Regarding your points:
1. JSDoc does support everything that TypeScript supports (that's the point of this article), although it does not necessarily support it as cleanly, hence why projects like Svelte typically use DTS files to define the project's types, and have those be imported inside JSDoc annotations. It's not perfect, but it gets you a long way.
2. You're right, JSDoc isn't picked up from imported libraries, but if you're publishing a library, you'll have a build script there, and at that point it's typical to generate the DTS files and pack those with the source code. That seems fairly reasonable to me — while developing, you don't need to worry about building files, but then when packaging and releasing you do.
3. You don't need a transpiler with JSDoc, the point behind JSDoc is that it's literally just the pre-existing JS documentation syntax. You can (and should) leave the comments in. Even if you're using TypeScript syntax, you should have JSDoc annotations (although adding the types to those annotations is redundant in that case). You can also just include the DTS files. As long as they're only imported from JSDoc, the runtime won't see them.
Personally, having tried out JSDoc-based TypeScript, I'd rather just use the native type stripping in Node for development, and keep with TS syntax, but there are large projects that have made the opposite choice, most noticeably Svelte. So I don't think it's a given that JSDoc users will inevitably graduate to TypeScript (especially when projects have gone in the opposite direction).
Yes, all of these are supported in JSDoc because they are supported in TypeScript. Because JSDoc is TypeScript. You can either define your types in JSDoc comments or in .ts files.
I really mean it. You can even use the @satisfies operator like so
/** @satisfies {Type} */
Discriminated unions, conditional types, mapped types, template literal types, etc work exactly the same way if you define them in a JSDoc comment as if you define them in a .ts file
You mean a TypeScript project without strict mode? Sure. Again, whether you're defining types in JSDoc comments or in .ts files, the behavior is entirely governed by a tsconfig file
Oh man, the mention of ScriptSharp brought back memories. I started my career at MSFT on SharePoint and the front end was an ungodly mix of ScriptSharp and other stuff.
I vividly remember being in a meeting with the Exchange team (about building shared frontend components) arguing for us to adopt TS instead as it had a better experience and very rapidly growing popularity (that was about 10 years ago). Plus, as strong as Nikhil [0] was, he was basically the only person behind ScriptSharp while TS had a whole team.
Of course, this being MSFT, this effort went no where. While true that the TS toolchain lacked the tree-shaking that ScriptSharp had, I was just annoyed that we had to build stuff using what was obviously an dead-ish language with limited support, many flaws, and no resources to improve it.
From what I've read, many of TypeScript's design regrets have political origins. Enums and other features that oppose TS's structural type system were added as compromises with C# developers in MS and similar negotiations with the Angular team in order to increase adoption of TypeScript over alternatives
Oh gosh, I don't think I can recall a specific source. I've listened to many interviews with the TypeScript team and in Q&A they're often asked about their "biggest regrets". Early on TypeScript's adoption was far from a sure thing. After convincing Microsoft their biggest threat was Angular's own AtScript (and maybe even Flow). TypeScript was extremely beholden to whatever Microsoft or Angular devs wanted to be added to the language in order for them to agree to push TypeScript as the future
It's certainly more verbose but certainly not a limited subset. You can copy paste any typescript Type or Interface in a jsdoc @typedef. As I stated in the article, it's still the TypeScript language service that's analyzing either JSDoc-defined types or TypeScript defined types. It's typescript all the way down
But JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript (e.g. enums, namespaces, etc). Even generic slots are supported
The list of things jsdoc cannot do is long but a simple example is overloading, you cannot express this[1] in jsdoc, and if you need to reference .d.ts files you're back at using TypeScript, so the point of JSDoc was...?
If you need precise return typing, conditional types, literal values, etc, you aren't going far if anywhere with JSDoc.
But not properly documented (https://www.typescriptlang.org/docs/handbook/jsdoc-supported...), which shows how much Microsoft neglects JS + JSDoc workflow. Github issues have been created a long time ago, but nothing has been done so far. Apparently Microsoft is too busy with their AI slop to work on actually useful stuff.
Eh. I agree with the principle. I’ve written personal projects with JSDoc because I truly love the idea of finally being done with build systems and just serving the files I write without a step in between.
But it’s more annoying than just writing TypeScript. There are ways to express just about everything TypeScript can but they’re all more difficult and convoluted (generics are a great example). For a project of any reasonable size I’m still going to advocate to use TypeScript.
Care to give an example? In another reply I pointed out how advanced JSDoc syntax's support for generics is.[0] Even allowing for `extends` and default values for generic slots.
The clunkiest part is in the way you "pass in" a generic to a slot. But this is solved by typing the return type.
I use generics pretty extensively and I've not yet come across a use-case JSDoc couldn't handle
JSDoc doesn't have a formal spec. Most modern development on JSDoc syntax happens by the TypeScript team. Every release of TypeScript also includes notes about JSDoc syntax.
Almost any modern IDE is also parsing JSDoc comments through the TypeScript language service. So many people don't realize they are already using TypeScript (hence the name of this post).
I don't think it's particularly controversial to say that the form of JSDoc that the majority of developers are familiar with IS JSDoc. The distinction is more of a historical one than a technical one (since there is no formal JSDoc spec)
Agree. It’s superior. I arrived at this about 2 years ago no regrets. Type safety matters on the tooling side anyway. Unless you’re testing for the runtime I guess?
I'm glad to hear you've had a good experience with JSDoc but I want to reiterate that my position isn't that JSDoc is superior. Just that it is TypeScript
Yes I’m saying, starting from equality Id add on to say it’s actually the better form. TypeScripts extra enforcement adds complexity without usefulness.
Once we get it, there is still a solid decade before runtimes support it, and optimistically, still more 10 years minimum having to deal with an interpreted language that has acquired an unecessary build step.
I absolutely hated when PHP switched from a phpDoc culture with static analysis (and IDE inconsistencies that would click-take you to stubs as well) to actual types. Not because I hate types, but because of the transition period. Once it's gone, it's such a relief to get rid of unecessary docblocks.
The proposal is to introduce a whole slew of syntax to JS that according to the proposal will have no meaning. This is a paradox. You have only created a language if you can use it to convey meaning
Unless I say it's meaning is to be optionally reflected upon during runtime!
Look, I understand the purism and mostly, I agree. But this is not a clean slate language, it will never be perfect and it's going to become more and more idiosyncratic as times go by.
Comments are a kind of freedom in code. You're completely free to use them precisely because (in a plain execution environment) they cannot influence the result of evaluation
If comments /can/ change the result of evaluation then you simply are not (completely) free to use them. (And yes I know that this is a simplification in JS where you can already get the source code of a function with toString... Ugh)
Something needs to change. I don't care about one specific proposal.
It's miserable having a de-facto build step for an interpreted language. Worst of both worlds.
Maybe just TS is fast, but it encourages developers to put more and more stuff into that build step (and they do, they do that a lot). Culturally, that trend is not going to change unless the main reason for having said build step is removed.
The whole babel/transpiling thing was meant to be temporary. It became temporarily permanent / permanently temporary.
Who cares what some framework guy thinks. When I was writing JavaScript for employment most people doing that work were hyper concerned with how to write code and what other people thought about it. These kinds of opinions and conversations are critically important for beginners, but junior and senior developers never seemed to get past these concerns of basic literacy.
When other developers and non-developers look at JavaScript developers as small children it’s because the maturity difference is very evident from the outside. Once developers get past basic literacy they are free to worry about architecture, performance, scale, platform independence, and more. For most JavaScript developers they just expect some framework to do it for them.
Dunno. Your comment seems pretty immature and strangely emotional. If you think you’re too good for these sorts of articles and this sort of tech, then maybe you’re also too good for the related discussion.
A few things I've come to personally believe after spending years developing web and robotics software in Python/JavaScript then spending years having to maintain while constantly adding new features and dealing with company pivots:
- The types exist whether you write them down or not.
- If they're not written down, they're written down in your head.
- Your head is very volatile and hard for others to access.
- Typing is an incredibly good form of documentation.
- JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
- Make informed decisions on how you'll describe your types, and then be consistent and unsurprising.
- A type checker is the computer saying, "okay then, prove it" about your program's type validity.
- Not every program benefits from the same amount of "prove it."
- Too much can be as bad as too little. You're wasting resources proving throwaway code.
- I like languages that let you decide how much you need to "prove it."
> Your head is very volatile and hard for others to access.
One of the lessons you learn while doing this job is that "others" includes "yourself in the future".
(Of course people will tell you this way before you find out yourself, but what do they know...)
"who wrote this garbage?... oh yeah that was me"
Nothing puts you in your place like a `git blame`.
> - I like languages that let you decide how much you need to "prove it."
Rust is known for being very "prove it," as you put it, but I think that it is not, and it exposes a weakness in your perspective here. In particular, Rust lets you be lax about types (Any) or other proved constraints (borrow checker bypass by unsafe, Arc, or cloning), but it forces you to decide how the unproven constraints are handled (ranging from undefined behavior to doing what you probably want with performance trade-offs). A langauge that simply lets you not prove it still must choose one of these approaches to run, but you will be less aware of what is chosen and unable to pick the right one for your use case. Writing something with, for example, Arc, .clone(), or Any is almost as easy as writing it in something like Python at the start (just arbitrarily pick one approach and go with it), but you get the aforementioned advantages and it scales better (the reader can instantly see (instead of dredging through the code to try to figure it out) "oh, this could be any type" or "oh, this is taken by ownership, so no spooky action at a distance is likely").
In practice, though, writing stuff with `Arc` or `.clone()` or `Any` is not as easy as it would be in Python because you've got to write a bunch of extra boilerplate. It's much easier to have local `i64` values that you can pass around as `Copy`. So if all you need are local i64s, then you'll take the easier option and do that.
The same is true at multiple levels. `.clone()` is relatively easy to use, although once you learn the basic rules for referencing, that also becomes easier. `Arc` solves a specific problem you run into at a certain point sharing data between threads, but if you're not sharing data between threads (and most of the time you're not), it's just boilerplate and confusing, so you might avoid it and at worst use `Rc`. `Any` is rarely an obvious choice for most contexts, you really are going to only use it when you need it.
The result is that for most simple cases, the precise and "proven" option is typically the easiest to go for. When you deal with more complicated things, the more complicated tools are available to you. That seems exactly what the previous poster described, where you can decide yourself how much you need to prove a given thing.
is that not exactly "deciding how much to prove it?"
> JSDoc and TypeScript are standards/formats for typing. Like any tools, they both have advantages and disadvantages. Neither is objectively better than the other.
Agreed. Just to clarify, my intentions with this post weren't to advocate for one over the other. Just to point out that they are the same thing. They are both TypeScript.
I don't know how anyone can agree with this, because it pivots on this outrageous claim:
"Like any tools, they both have advantages and disadvantages"
You cannot make any argument based on such a position. Putting aside anyone's views on TS or JSDoc, tooling is of extremely variable quality, and lots of tools ARE objectively much worse than other tools.
It we can't point at tools and say this one is better than that one, we might as well give up.
I always remember a scene in Will & Grace where Will is trying to get his boss to say one thing is better than the other. He's brought a lovingly hand-crafted sandwich made with amazing, bread, fillings, etc. and a store bought sandwich made with cheap bread/fillings. He asks his boss to try both and say which one he likes more.
His boss says something like the store bought one reminds him of his grandma's sandwiches, so invokes nostalgia, and still can't make a decision.
Don't be that boss.
I don't understand how this an outrageous claim. You might say a luxury sports car is objectively better than a cheap minivan, but that is no good to someone who needs to transport around a family.
Or is you problem with the word any instead of many?
> They are both TypeScript.
I take issue with this position because this seems to imply "PureScript and JavaScript are both JavaScript" is a true statement merely because one of them turns into the other with tooling.
TypeScript is indeed Javascript, all you have to do is remove the type annotations. They are not code.
TS does have some minor things like enums that need to be transformed and are actual code, but those are very few, and leftovers from early days of TS, and the TS authors regret having implemented them. For many years now the TS philosophy has been that the CODE part of TS is 100% ECMAscript, and only annotations, which are not code, are added.
The initial Babel transpiler for TS => JS, and still the most part of the current one, simply removes annotations.
It is recommended not to use the few parts that are actual code and not standard JS. They are certainly not needed any more since ES6.
People may get confused because the type syntax itself is almost like a programming language, with conditions and all. But none of that ends up as code, it's not used at runtime.
One of the IMHO worst design decisions of TS was to bundle type checking and transpiling into one tool. That caused sooo many misunderstandings and confusion.
I think the point here is that all the TS tooling works with JSDoc without any friction. As long as you don't look into the file, from the tooling perspective, a .ts file and a .js file with proper JSDoc annotations are practically the same.
Except the js files can work in the browser as is.. not the ts one (fortunately I might add, I find ts syntax very loaded at times) Either one is superseding the other one, or they are simply distant cousins, but this is not interchangeable.
TS from JSDoc requires a generative pass to. This is a (expected) level of indirection. (unless some tooling does it automatically)
Yeah. I learned this lesson 25 years ago in university. SQL, Lisp, and whatever scripting language I was learning at the time were always much harder to reason about vs statically typed languages— particularly in team projects. Over the years, I’ve gotten comfortable with SQL, but I always prefer static typing when I can get it.
> The types exist whether you write them down or not
That's easy to say when we're talking about primitive arguments in private functions, or primitive local variables, but let's not ignore the fact that it takes much more work to write a C# program than a Ruby program for instance.
We can see that by looking at a vanillajs library's typescript typings that were created after the js library when typescript didn't exist. The types are insanely complex and if you get one type wrong you can break compilation of some library user's program (its happened to me).
That being said I'm aware that dynamic programming languages are a "use at your own risk" type of language.
are dynamic languages really a "use at your own risk" ? or it's about changing frame of mind ?
my take is if you treat your program as a series of data flows - then use primitives such as maps | arrays - then you don't need as much typing or typing at all. a map doesn't need to take a shape or a Person | Manager - either the keys exist or they don't and almost every language has guards to ensure you can safely navigate existence of keys.
but then again my realm is mostly around - web | data systems - if I was dealing with OS level systems and needed to make sure i have i64 ints then yeah typing would be crucial.
And if your boss is the type to pivot way too often and want it done yesterday, then they don’t deserve code that is prove in the right places so you just get an LLM to add typing to everything after the fact…
> then they don’t deserve code that is prove
I don't get it. Types are a way to write code. Nothing to do with how fast/much the code changes.
Typed code is significantly more cumbersome to change (because there's more code to change). At least until you reach a certain size of your spaghetti bowl. Then both typed and untyped are cumbersome and people endlessly discuss which one is more.
I don’t think so. With a good editor, you change the type and run the compiler which will warn you with all the locations you’ll need to edit. Then you can quickly navigate to those locations.
> which will warn you with all the locations you’ll need to edit
This is true, but with a program built with a dynamic language, taking advantage of the fact that it's written in a dynamic language, doesn't need to make those changes at all.
I'm fan of static typing in many situations, but it's hard to deny it doesn't lead to more changes as you need to properly propagate changes.
I don't find that dynamic typing reduces the number of places I need to update stuff. It just changes when the error occurs.
If I change the shape of some data (such as renaming object properties), I'll need to update all the code that used that data, regardless of the type system. Static typing just ensures that I catch those cases at compile time, not runtime.
Just one simple and contrived example I could come up with the five minutes I had available:
JavaScript:
TypeScript: Again, this is just a simple example. But multiply 100x + way messier codebases where everything are static types and intrinsically linked with each other, and every change becomes "change -> compile and see next spot to change -> change" until you've worked through 10s of files, instead of just changing it in one place.Personally, I prefer to spend the extra time I get from dynamic languages to write proper unit tests that can actually ensure the absence of specific logic bugs, rather than further ossifying the architecture with static types while changes are still ongoing.
In your Typescript example, the solution would be to use your IDE to refactor hosts to hostnames, a process that takes like 2 seconds. You might have problems if the change exists at a service boundry, but in that case I'd just put the transformation at the service boundry, and keep everything the same internally.
> Personally, I prefer to spend the extra time I get from dynamic languages to write proper unit tests that can actually ensure the absence of specific logic bugs, rather than further ossifying the architecture with static types while changes are still ongoing.
I'd argue static typing makes this much easier, because I know any input types (or output types from other components) will be enforced by the type system. So I don't need to bother writing tests for "what if this parameter isn't set" or "what if this function returns something unexpected". The type system handles all of that, which eliminated a lot of tedious boilerplate tests.
> In your Typescript example, the solution would be to use your IDE to refactor hosts to hostnames
Yeah, sure, and with LLMs you can do this, and you can do that. But if we're talking about languages and their features, relying on IDE features feels slightly off-topic.
But regardless, changes is changes, no matter if you, your IDE or your LLM made them. So even if your IDE makes the changes, it seems at least you can now agree that there are more changes needed, it's just that with TypeScript you have a editor who can help you refactor, and with JavaScript you haven't yet found an editor that can do so.
> So I don't need to bother writing tests for "what if this parameter isn't set" or "what if this function returns something unexpected".
Yeah, those unit tests does nothing, and people who write in dynamic languages don't write tests like that either. You test actual logic, in unit tests, and you rely on the signals that gives you.
In fact, I could bet you that if you and me both sat down and wrote the exact same application, one in JS and one in TS, we'd end up with more or less the same amount of unit tests, yet the JS codebase will be a lot more flexible once product requirements start to change.
But again, YMMV and all that, it's a highly personal preference. I don't think there is a ground truth here, different minds seem to prefer different things. I mostly work in environments where the requirements can change from day to day, and being able to adopt to those without introducing new issues is the most important thing for me, so with JS I stay.
> Yeah, sure, and with LLMs you can do this, and you can do that. But if we're talking about languages and their features, relying on IDE features feels slightly off-topic.
Refacoring tools (such as renaming properties) have been supported by IDEs for decades. And in Typescript specifically, the language is designed with these tools in mind, which are developed and distributed directly by the Typescript team. For all intents and purposes, IDE integration using the Typescript language server is a feature of Typescript.
And if somehow these tools don't work, the compiler will catch it immediately! This means I can refactor with confidence, knowing any type issues will be caught automatically.
It seems like you're vastly overestimating the time and effort it takes to change types in Typescript. In my experience it's something that takes basically no time and effort, and has never caused me any issues or headaches.
You're changing the point though, you claimed "I don't find that dynamic typing reduces the number of places I need to update stuff", which just because your editor makes the change, doesn't suddenly make the change not show up in the diff for you and others. A change is a change, regardless of how it's made, unless you don't keep your code in a SCM that is, which I'm assuming most of us do.
I'm not saying it's hard to change types in TypeScript, I understand that your IDE is connected with the language and they're used together, but again my argument was that having types leads to having to change things in more places. Which is true too, and it's a good thing, it's on purpose, and the tools you use help with that, so yay for that! But it's still more changes, and at least for me it's important to be honest about the tradeoffs our choices leads us to.
As I mentioned earlier, I'm fan of static typing in many situations, just not all of them. And I'm not blind to the negatives they can bring too, I guess I just see more nuance in the static typing vs dynamic debate.
Regardless of how dynamic typing is, the contract being enforced stays the same. It's just less enforced by tools. So with dynamic typing, you will have to change the same amount of code if you want your code to stay correct. The only variation in code changes comes from the annotation for the type system.
> So with dynamic typing, you will have to change the same amount of code if you want your code to stay correct.
No, because if a piece of data is pushed through multiple layers you can just change its type at the source and the destination and not in all the layers the data is pushed through. And you can still be correct.
Imagine you have a thing called target which is a description of some endpoint. You can start with just a string, but at one point decide that instead of string you'd prefer object of a class. In dynamic language you just change the place where it originates and the place where it's used. You don't need to change any spot in 3 layers that just forearded target because they were never forced assumed it's a string.
You can achieve that in staticly typed language if you never use primitive types in your parametrs and return types or if you heavily use generics on everything, but it's not how most people write code.
Tools can help you with the changes, but such refactors aren't usually available in free tools. At least they weren't before LLMs. So the best they could do for most people was to take them on a journey through 3 layers to have them make manual change from string to Target at every spot.
In some type systems, you don't need to change it either. Errors will happens only if you've written code that assumes that `target` is a string. If I write a function with the following signature:
And you called it withconst first_el = split(target)[0]
If you decide `target` to suddenly be an object, then the code you wrote is incorrect, because semantically, `split` only makes sense when the argument is a string. Which is why, even with dynamic typing, you'll see that the documentation of a function will state what kind of parameters it expects.
If you a call chain like `fn1 | fn2 | fn3 | fn4 | split`, Then yeah you need to ensure what reaches `split` is in fact a string. If you're against updating fn[1-4]'s signature, let's say that it's harder to find which function needs to change in a dynamic typing systems.
Dynamic typing is useful for small programs and scripts because they are easy to iterate upon. But for longer programs, I'll take static typing anytime.
Yeah, tooling for strongly typed languages is way better than 20 years ago. They are getting very being usable.
> I like languages that let you decide how much you need to "prove it."
I love that too. Are there any other languages than TS that have this as a core design feature?
As I understand that is the core design feature of any strongly typed language.
I believe they're talking about gradual typing[0].
[0]: https://en.wikipedia.org/wiki/Gradual_typing
Not really. Strongly typed languages don't usually support not having any types in your code (or any amount of gradual typing). At least not with any convenient syntax. There's usually some one clumsy "dynamic" type that doesn't interact with the rest of the system well and you'd be crazy to start writing your code using only this dynamic type.
I can't just write C++ like:
I also can't tell JS this shouldn't be allowed. But I can tell this to TS, at any stage of evolution of my program.I'll take a more definite position. Build pipelines are the devil. Every square inch of surface complexity you add to whatever you're doing, you will pay for it. If there's a way to get the benefits without the build step, that's your choice. You may need runtime type enforcement, so that's not JSDoc, and you're doing that with... JS so that's already suspicious but the use case def exists. JS, the DOM, HTTP, this whole stack is garbage at this point so arguing about the type system is a little idk hard to care about personally. I have a solution that lets you discard most of the web stack, that's more interesting to me.
I'm a fan of anything that allows me to build with javascript that doesn't require a build step.
Modern HTML/CSS with Web Components and JSDoc is underrated. Not for everyone but should be more in the running for a modern frontend stack than it is.
On the one hand I can see the appeal of not having a build step. On the other, given how many different parts of the web dev pipeline require one, it seems very tricky to get all of your dependencies to be build-step-free. And with things like HMR the cost of a build step is much ameliorated.
I haven't run into any steps that require one, there's always alternatives.
Do you have anything specific in mind?
Anything that uses JSX syntax, for instance.
Any kind of downleveling, though that's less important these days most users only need polyfills, new syntax features like `using` are not widely used.
Minification, and bundling for web is still somewhat necessary. ESM is still tricky to use without assistance.
None of these are necessary. But if you use any of them you've already committed to having a build step, so adding in a typescript-erasure step isn't much extra work.
If there is one thing I don't miss using WebComponents is JSX. lit-html is much, much better.
It's such a lovely and simple stack.
No Lit Element or Lit or whatever it's branded now, no framework just vanilla web components, lit-html in a render() method, class properties for reactivity, JSDoc for opt-in typing, using it where it makes sense but not junking up the code base where it's not needed...
No build step, no bundles, most things stay in light dom, so just normal CSS, no source maps, transpiling or wasted hours with framework version churn...
Such a wonderful and relaxing way to do modern web development.
I love it. I've had a hard time convincing clients it's the best way to go but any side projects recently and going forward will always start with this frontend stack and no more until fully necessary.
This discussion made me happy to see more people enjoying the stack available in the browser. I think over time, what devs enjoy using is what becomes mainstream, React was the same fresh breeze in the past.
I recently used Preact and HTM for a small side project, for the JSX-like syntax without a build step.
I have not written a line of JavaScript that got shipped as-is in probably a decade. It always goes through Vite or Webpack. So the benefit of JS without a build step is of no benefit to me.
Dare to dream and be bold.
Seriously, start a project and use only the standards. You'll be surprised how good the experience can be.
Webcomponents are a pain in the ass to make, though. That is, sufficiently complex ones. I wish there was an easier way.
I've built Solarite, a library that's made vanilla web components a lot more productive IMHO. It allows minimal DOM updates when the data changes. And other nice features like nested styles and passing constructor arguments to sub-components via attributes.
https://github.com/Vorticode/solarite
It's ok now, at least for me. There are still challenges around theming and styling because of styling boundaries (which makes Web Components powerful, but still). A part of it is about tooling, which can be easier to improve.
Try my tiny web components lib if you want to keep JSX but not the rest of React: https://github.com/webjsx/magic-loop
They could have better ergonomics and I hope a successor that does comes out but they're really not that bad.
web components need 2 things to be great without external libraries (like lit-html):
- signals, which is currently Stage 1 https://github.com/tc39/proposal-signals
- And this proposal: https://github.com/WICG/webcomponents/issues/1069 which is basically lit-html in the browser
It's a shame Surplus (Adam Haile's, not my succession of it) isn't cited nor is he mentioned, given that at least two of the listed frameworks were heavily and directly inspired by his work. S.js is probably one of the most incredible JavaScript libraries I've used that should be the reference for a signal API, in my opinion.
Svelte has a pretty nice support for this via https://svelte.dev/docs/svelte/custom-elements
It's not a no-build option though.
Agreed on native HTML+CSS+JSDoc. An advantage in my use-cases is that built-in browser dev tools become fluid to use. View a network request, click to the initiator directly in your source code, add breakpoints and step without getting thrown into library internals, edit code and data in memory to verify assumptions & fixes, etc.
Especially helpful as applications become larger and a debugger becomes necessary to efficiently track down and fix problems.
You don't need a build step anymore with TypeScript since Node 24.
I'm referring to client-side javascript.
> Modern HTML/CSS with Web Components and JSDoc is underrated.
I've been a front end developer for 25 years. This is also my opinion.
This. Or use ts-blank-space if you prefer TypeScript over JSDoc. That's what we do in https://mastrojs.github.io
I was already doing that in 2010, with the JSDoc tooling in Eclipse and Netbeans back then.
However I don't get to dictate fashion in developer stacks.
TS is worth the build step.
JSDoc is TypeScript.
It is TypeScript in the same way my rear end is the Grand Canyon: they are somewhat isomorphic but one is much less pleasant to look at.
Why? The half a second for the HMR is taking up too much your day?
No, because layers of abstraction come at a cost and we have created a temple to the clouds piled with abstractions. Any option to simplify processes and remove abstractions should be taken or at least strongly considered.
Code written for a web browser 30 years ago will still run in a web browser today. But what guarantee does a build step have that the toolchain will still even exist 30 years from now?
And because modern HTML/CSS is powerful and improving at a rapid clip. I don't want to be stuck on non-standard frameworks when the rest of the world moves on to better and better standards.
> Code written for a web browser 30 years ago will still run in a web browser today.
Will it? - My browser doesn't have document.layers (Netscape) It seems to still have document.all (MSIE), but not sure it's 100% compatible to all the shenanigans from the pre-DOM times as it's now mapped to DOM elements.
The Space Jam website from 1996 still renders perfectly almost 30 years later.
https://www.spacejam.com/1996/
Those (document.layers and document.all) were both vendor-specific, neither were part of the w3c. I don't recommend ever writing vendor-specific code.
The w3c and standards have generally won so it's easier than ever to write to the standard.
Having all your code go through a multi-step process that spits out 30 different files makes it impossible to know what’s really happening, which I’m uncomfortable with.
Came here to write this exact sentiment. Not everything needs a massive build pipeline.
So, some history. When SPA's started to boom on the web JSDoc was a life saver for typing. Application state was getting more complex. We needed more guard rails.
Then Google Closure Compiler came along which added type safety via JSDOC and TS came along with (TS)JSDoc support and it's own TS syntax.
The community chose native TS and Google Closure compiler slipped away into the background.
So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
Today I use TS. I also use plain JSDoc for documentation. e.g. @link and @see for docs. Or @deprecated when I'm flagging a method to be removed. @example for a quick look up of how to use a component.
TS and plain JSDoc are both important together. But (TS)JSDoc alone, is a relic of the past.
> Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
This was my main impetus for writing this article. Modern JSDoc uses the TypeScript language service. You can use generics, utility types, typeguards (including the `is` keyword), regex parsing, etc all with just JSDoc.
I used these features extensively (especially generics) in a personal project and managed to do it all in JSDoc.
JSDoc is missing a lot of basic capabilities. For example a TypeDef is automatically exported which can cause collisions and forces you to repeat or inline types.
Types for classes are poor and often you'll find yourself creating a `.d.ts` file or `.ts` file to export non trivial types - however the target file doesn't know how to consume them.
typedefs are indeed automatically exported but that doesn't mean collisions can happen. You would still have to explicitly import a type
Regardless, I hardly consider that a "missing basic capability"
I don't know what you mean about types for classes being "poor". Types for classes work exactly the same way
You cannot replicate `import type { x } from './foo'` without also re-exporting that import - which causes collisions.
The alternative is to do an inline `const foo = /** @type {import('./foo').x} */ ({})` however this gets messy, repetitive and it's difficult to use algebraic types (e.g. `Event & { detail: string }`)
Would `import type { x as y } from `./foo.x` not work?
JSDoc does not understand typescript syntax though? The typescript language server just kinda plows through/over JSDoc sure, but try getting JSDoc to parse some of the TS-ified things that JSDoc has alternatives for.
https://github.com/jsdoc/jsdoc/issues/1917
https://github.com/jsdoc/jsdoc/issues/1917#issuecomment-1250...
tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration. For example:
```js
is the exact equivalent of```ts
For TS-specific keywords like `satisfies`, there's a corresponding JSDoc keyword like @satisfies. Generics use @template.Is there any specific feature you think is not supported? I'm sure I could work up a TS Playground example.
> Is there any specific feature you think is not supported
Yeah, uhm, most of what you've been posting? :). That JSDoc example above gives:
Edit: Also, your first edit says Webpack switched from TypeScript to JavaScript, but Webpack source was never written in TypeScript.We're talking about two different things here. All my examples work perfectly fine with TypeScript
https://www.typescriptlang.org/play/?#code/PQKhCgAIUgBAXAngB...
You are attempting to generate documentation from jsdoc comments using an npm package that is also called "jsdoc". Ofc in this case "JSDoc is not TypeScript". That package only supports the subset of JSDoc that is relevant to it. Though I believe you can use TypeDoc instead if you want to generate documentation from JSDoc that contains typescript types.
In the post I made it explicit that I'm talking about intellisense, developer tooling, type checking etc. You can run `tsc` to do typechecking on a project typed with JSDoc like the examples I've given throughout this thread just fine.
I guess the difference here is I'm coming at this from the perspective of "what is TypeScript used for. Can JSDoc comments substitute that". And the answer is almost completely yes.
Also tbh I've never met anyone that uses that package to generate API docs. I don't think it's a very modern package: https://github.com/jsdoc/jsdoc/issues/2129
Apologies, my first draft of that comment got deleted on a refresh (mobile) and my posted one left out how I'm probably being too pedantic: the official JSDoc is not TypeScript.
Your post is actually one of the more accurate ones compared to others that say "you don't need typescript" with the big caveat that you actually need a whole lot of the typescript ecosystem to make JSDoc work.
I just wish there was an official handover, or a more clear delineation between JSDoc and Typescript JSDoc Extensions.
I think you have a valuable point. I kinda purposely avoided explicitly defining what JSDoc is. Instead I'm relying on "the JSDoc we're all familiar with". I said in the post that if your IDE is giving you intellisense from JSDoc comments then you are almost certainly already using TypeScript. That's about as close as I got to defining the JSDoc I'm talking about
But given that JSDoc doesn't have any sort of formal spec, I think the distinction you're making is more of a historical than a technical one.
This was an interesting and useful post but you’re kind of losing the plot here in these comments defending against what should be a straightforward minor correction.
JSDoc has been around for more than twenty years and most implementations have never had most of the capabilities you’re describing.
It is actively misleading for you to say that JSDoc has these capabilities when you’re referring specifically and exclusively to TypeScript’s implementation of JSDoc, or you could say TypeScript’s alternative JSDoc syntax. Closure always used language like that in their documentation, and explicitly called out that they had diverged from standard JSDoc, as they should have. TypeScript’s own documentation sometimes refers to it as their superset of JSDoc, again recognizing that “JSDoc” actually does mean something specific and different.
The fact that there may not be a formal technical spec doesn’t mean you’re not wrong and it’s preposterous to suggest that.
There was established tooling and documentation going back 25 years, and it doesn’t somehow not count just because they didn’t give you a formal grammar…
I’m curious how type checking is possible in a JDoc project. As far as I’m aware there’s no way to get type checking to work without tsc or a TypeScript LSP plugin.
That is exactly how it works. Any IDE providing you intellisense is using the TypeScript language service. That's why this article is called "JSDoc is TypeScript". If you see a red squiggly because of your JSDoc comment, you are almost certainly already using TypeScript (without any .ts files)
Ha! I see I elicited the copy/paste response I’ve seen elsewhere. The gp comment I was replying to implied a JSDoc only solution (“all in JSDoc”), but given the response, clearly they’re still relying on the TypeScript language service (aka lsp plugin) to achieve type checking inside their IDE.
Wishful thinking on my part that an alternative solution for JSDoc based type checking exists :)
Do you have a particular reason to care about the implementation details of your tooling's type checker?
Generally, no. Only in the case you had a requirement to exclusively use JavaScript as the programming language you might be in for an awkward time justifying that you added type checking to the project via the type checker component of TypeScript with JSDoc :)
Depends on your definition of "using" JavaScript. The main difference between common TypeScript and TS-based JSDoc is the need for an additional build step. Being able to ftp-upload your `.js` files and then be done with it is a remarkable advantage over Vite/Webpack/whatever in small to medium-sized projects. If editor based type support is sufficient to you (i.e. no headless checks), you won't need to install any TS packages at all, either. tsserver is still used in the background, but so are thousands of other binaries that keep your editor, OS and computer running, so I don't see that as an argument.
The article is an explicit response to the point you’re making.
> So (TS)JSDoc support is a relic from when Microsoft was trying to get market share from Google.
> Today in 2025, TS offers so much more than the (TS)JSDoc implementation. Generics, Enums, Utility types, Type Testing in Vitest, typeguards, plus other stuff.
None of that is true! Please don't share misinformation without looking it up first.
1. there are plenty things you can't express in jsdoc but can in typescript, flow did the right thing here where you have access to full language, not sure why typescript never did it, they could, with the same syntax flow is using
2. you can have navigation that goes to typescript file instead of definition, just arrange your exports in package.json correctly (first ones take precedence)
Well I'd love to hear some concrete examples if you have any on hand! I was of the same opinion as you until I refactored a project of mine to use JSDoc.
Since any TypeScript type can be expressed in JSDoc, I imagine you're mostly thinking of generics. At least that was my main sticking point. JSDoc does actually have generic slots with the @template tag. Actually using them in practice is a little unintuitive but involves typing the return type. E.g. for a function it'd look like this:
Last time I checked, there isn't a way to extend types (https://www.typescriptlang.org/docs/handbook/2/objects.html#...) that works exactly like in TypeScript.
JSDoc actually has the @extends tag
But I don't really use that feature in TypeScript. Instead I rely on `&`. This works in exactly the same way in JSDoc.Also if you're curious about the equivalent of `extends` in generic slots, here's an example I have from a different project
The generic slot here, T, is "extended" by Record<string, unknown>. The equivalent in TypeScript would look likethe equivalent in typescript would be "export type" not just "type", since as I pointed out that type is exported without you being able to control it
I don't understand why someone would opt for "write Typescript, but add a bunch of extra characters, make the syntax clunkier, and throw away all the benefits of compile-time errors because we'd rather have runtime errors" in order to save, what, a microsecond stripping typescript out of TS files?
Everyone's complaining about "the build step" but the build step is just an eye blink of stripping out some things that match a regex.
> throw away all the benefits of compile-time errors because we'd rather have runtime errors
This is inaccurate on multiple counts. First of all, you can still run tsc with JSDoc if you want a hard error and you can still use strict mode with JSDoc. Your tsconfig file governs JSDoc-typed code just the same as it governs .ts-typed code. In both cases you can also ignore the red squigglies (the exact same red squigglies) and end up with runtime errors.
Nobody is advocating for reduced type safety or increased runtime errors.
I also think there are many valid reasons to loathe a build step (like not dealing with the headache that is the discrepency between the way the TS compiler deals with import paths vs js runtimes).
All that being said, I'm not really trying to convince anyone to stop using TypeScript. I'm simply pointing out that using JSDoc is using TypeScript. It's the same language service.
You can use `&` operator to combine types. Works for adding fields, making branded types, etc.
which is not the same as "extends".
There's also a slight performance caveat when it comes to interfaces vs intersections (&) to keep in mind: https://github.com/microsoft/Typescript/wiki/Performance#pre...
Things like type star imports, destructured imports or satisfies operator don't work in jsdoc.
All non erasable constructs won't work as well of course but playing devil's advocate you could explicitly state that you're interested in erasable constructs only because ie. 1) that's what typescript should be doing from day 1 and/or 2) it seem to be the future with ie. nodejs adopting built in type erasure support.
Support for generics is limited in JSDoc compared to TypeScript, especially when arrow function is involved. Things that work fine in TypeScript trigger errors even though they are syntactically the same.
Because AirBnB's ESLint config has been burned into my brain I almost only use arrow functions. I also use generics extremely often. It's definitely a little more clunky but I haven't run into anything you can do in TypeScript that you can't do in JSDoc.
JSDoc also allows you to type stuff in-line. For example I often have to type an empty array like so:
If you have a tangible example of a problem you've run into, I'd love to walk through it.JavaScript example:
https://www.typescriptlang.org/play/?filetype=js#code/PTAEAE...
Almost equivalent typescript code:
https://www.typescriptlang.org/play/?#code/C4TwDgpgBA6glsAFg...
(I had to make it a little bit different from the JS code to make it compile)
(Well, this is not exactly about arrow function I guess. I remembered that part wrong.)
Note that I cannot make the type check in JS code to pass. Whatever I do, there is always a error. Meanwhile, it does not take much to TS code to work.
Try this out. I think it's a much more faithful representation of your TypeScript example too. JSDoc just wants you to be explicit about the default for generic slots (which is `unknown` in TypeScript).
https://www.typescriptlang.org/play/?filetype=js#code/PTAEAE...
Hover over the variables and you should see that the type inference is working just the same as in your TypeScript example
Ah I see. Looks like you avoided using the "@callback" tag but instead used the "@typedef" tag directly. Thanks!
I do think it illustrates a problem with TypeScript's support for JSDoc though. You see, I started with the code in JS and could not make it work, after which I translated it to TS. In JS/JSdoc, "@callback" is the "idiomatic" way of defining a function callback type with JSDoc. (It also makes it easier to add documentation for each parameter if necessary.) And indeed, @callback works the most of the time, except in such cases where these JSDoc tags don't work nicely together, and these alternatives become necessary.
This is absolutely a fair point. JSDoc predates TypeScript by over a decade. It's not until more recently that the syntaxes have started to converge.
My brain definitely works in TypeScript so I tend to translate from there. I definitely consider myself more familiar with TypeScript than with JSDoc, but sometimes (e.g. here) that's a benefit not a weakness
and types can be written in .d.ts file(s), which can be used in jsdoc out of the box (no import needed)
that's not "jsdoc is typescript" anymore because you're falling back to something else - type definition files where you do have access wider typescript functionality.
also not a full solution - for .d.ts types to be available globally without explicit import the .d.ts file itself cannot use any imports/exports. this means you can't reuse types from other places to construct your types. you can workaround this by explicitly importing .d.ts in jsconfig/tsconfig but you're still left with other issues.
those types do actually become globally visible everywhere polluting global namespace which is bad in itself
there are no guarantees about them being in sync with actual code, which violates the whole point of using type safety.
they don't solve cases where you need typescript inlined functionality locally in your code or to perform assertion with satisfies operator etc.
You could, but in a large codebase with multiple contributors, it easily becomes messy and confusing.
ReturnType is TypeScript, no? You’re using JSDoc to express but it’s a TypeScript type.
As I stated in the article, JSDoc is TypeScript :P
TypeScript utility types are available in JSDoc. You can pretty much copy-paste any typescript Type/Interface into JSDoc
Isn't that the whole point of the article? For all intents and purposes, JSDoc IS TypeScript
> there are plenty things you can't express in jsdoc but can in typescript
This isn't really true anymore, they have systematically added pretty much every type system feature to the JSDoc-like syntax.
Having JSDoc-like syntax isn't the same as it being fully supported. If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
> If you have a large enough codebase, you'll likely find a few cases where things work in TypeScript but its equivalent somehow fails type check in JSDoc.
You keep repeating this throughout the thread. Can you give an example?
Not that person, but is there an easy way to write something like a basic semver?
export type SemVer = `${number}.${number}.${number}`;
Could you extend it to work with regex groups like:
export const SemVerRegex = /^(?<major>0|[1-9]\d)\.(?<minor>0|[1-9]\d)\.(?<patch>0|[1-9]\d)(?:-((?:0|[1-9]\d|\d[a-zA-Z-][0-9a-zA-Z-])(?:\.(?:0|[1-9]\d|\d[a-zA-Z-][0-9a-zA-Z-]))))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
Could the groups be extracted so you the type back if you ran the regex on a string like: "1.2.3", or "1.2.3-prerelease"?
I don't understand the second part of your comment (that's a value, not a type), but the first part looks like this:
Here's a playground: https://www.typescriptlang.org/play/?filetype=js#code/PQKhAI...Thanks for the example, I had a good play around with it.
The second part of my comment is a value yes, but it's implicitly typed by typescript automatically. I was asking about how to use that type (and it's internals) in jsdoc.
> it's implicitly typed by typescript automatically
What do you mean by this? Can you share an example?
Regular expressions do not act as type guards, and there's no way to express a type that allows one regular expression but rejects another (they're all just `RegExp`): https://www.typescriptlang.org/play/?target=5#code/MYewdgzgL...
it is possible to do many of these with @typedef, but it gets difficult with JSDoc very quickly. In TypeScript you can easily create multi-line type aliases. Not quite so in JSDoc.
https://news.ycombinator.com/item?id=46268701
TypeScript's type system is Turing complete so you have access to essentially unlimited expressivity (up to the typechecking termination depth): https://news.ycombinator.com/item?id=14905043
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
ok i didn't think about this, that's an underrated benefit
could be a customizable behavior in editor/ide though
There is indeed an option in VSCode "typescript.preferGoToSourceDefinition" --
Prefer Go To Source Definition
Makes `Go to Definition` avoid type declaration files when possible by triggering `Go to Source Definition` instead.
This works with Typescript too though?
It doesn't. You might be thinking of libraries that you wrote, not packages from e.g. npm, which are distributed as JavaScript + type definition files not as TypeScript code.
It should work if the library was compiled with deceleration map option. Which most libraries are not and it's a shame.
It was added like 3 years ago which was probably a bit too late, not even sure why it's not the default. (File size?)
In real IDEs, not glorified text editors like VSCode, it does. I use this often in IDEA, it's muscle memory so I'm not even completely sure what to press, but it's likely "go to definition" and by default is tied to ctrl+alt+b.
IDEA adds its own analysis on top of that provided by the language server.
Works on JS + every variant of type definitions I've ever seen, among many other things (not only programming languages, but also database objects, etc).
> IDEA adds its own analysis on top of that provided by the language server.
IDEA implements its own analysis and doesn't use tsserver at all. Its semantics diverge in subtle ways, I believe in both directions (some code that tsserver considers valid IDEA will consider invalid and vice versa).
5 years ago I was at a meet up and the guy talking was saying how if you don't like typescript these jsdocs are the way to go. Had to explain to my employer attending that it is still typescript. Didn't seem to believe me and was super against typescript but not jsdocs lol
The difference is syntax compression imo.
> Had to explain to my employer attending that it is still typescript
"is" is doing a lot of heavy lifting there: JSDoc and TypeScript are two different ways to explicit prescribe typing in a way that tooling can use to determine correctness. The TS syntax is _far_ more powerful, but JSDoc can do most of the common TS use cases, for folks who want to stay in JS land while still benefiting from type tooling (either invoked or straight up built into the IDE).
> in a way that tooling can use to determine correctness.
As I pointed out in the article, the "tooling" is exactly TypeScript language services. If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
You can copy-paste basically any bit of TypeScript into a JSDoc comment and it will work. JSDoc supports any non-runtime feature of TypeScript (so not enums). Even generics! You can even reference TypeScript utility types!
The whole point of this article was to correct the idea that JSDoc is not TypeScript. It absolutely is! There's almost nothing you can't define in JSDoc that you can't define in a .ts file. Albeit with a sometimes clunkier syntax
That's absurd.
JSDoc is a comment formatting standard.
The tooling used to parse it is independent.
In the same vein, a file of ISO C++ (take any version) code is not "GNU C++".
By "JSDoc is TypeScript", culi means "JSDoc syntax and TypeScript syntax are two alternative ways to describe types to the TypeScript compiler/language services, and the two syntaxes have nearly-identical expressive power".
> If you are using JSDoc and you get squigglies or intellisense or any other similar features, you are using TypeScript.
This is true in the same way you are "using" C++ if you are on Windows. When most people say "use XYZ language" they mean "are personally writing code in XYZ language" rather than "under the hood my code is transpiled to this other language I don't write in"
In practice today JSDoc 100% completely and utterly always is Typescript.
It might not have been so originally. It might still be possible to do differently. But in practice today you are getting Typescript in your JSDoc with the out of the box tooling that is everywhere.
counterpoint: JSDoc is not typescript
If you define a type in a file with @typedef, it is automatically exported and there is nothing you can do to control that: https://github.com/microsoft/TypeScript/issues/46011
I tried making a library this way and lacking control over the visibility of the exported types was really painful; it made my intellisense awful because every type I defined at the root was exported from the library
I really like it for web components. Lately I have many "my-component.js" files and it's quite nice to just be able to copy them to new projects and have it all work without a build step. But I'm not sure I would use JSDoc over typescript syntax in a large project.
That's technically a fair complaint but feels like a minor nitpick. Just don't `@import` the types you don't want to use.
TypeScript won over the alternatives, exactly because it is only a type checker, and not a new language.
Granted they initially weren't down that path, but they course corrected it on time, and not much people use stuff like enums in new code.
> Take it from a massive TypeScript nerd: JSDoc is not an anti-TypeScript position to take. It is the same powerful static analysis without the build step.
Ahum https://nodejs.org/en/learn/typescript/run-natively
Technically there's still a build step happening under the hood! But another benefit of shifting TS into JSDoc comments is that it also works in browsers. That being said, while I understand the aversion to unnecessary complexity, I'm personally fine with a build step to remove TS. It's a much nicer syntax IMO. And with tools like `swc` for type stripping, it's pretty snappy too.
that's limited to node. won't work in a browser.
I'm actually using JSTypes in app, I don't mind it.
I choose to use it because I didn't want to deal with a build step for a smaller project. The project has grown and I am looking at adding a build step for bundling but still not too worried about using JSDoc over TS.
This might be my config, but one thing that does annoy me is whenever I define a lambda, I need to add an doc type. I guess if that's disincentivising me from writing lambdas maybe I should just add a TS compile step lol.
----------------------
Here's an example - I got some config typed with this function https://github.com/AKST/analysis-notebook/blob/c9fea8b465317... - Here's the type https://github.com/AKST/analysis-notebook/blob/c9fea8b465317... - And here's something to generate a more complicated type for defining config knobs https://github.com/AKST/analysis-notebook/blob/c9fea8b465317...
These days you can run TypeScript files as-is (type stripping) for testing in many runtimes, and for bundling, most bundlers support using a ts file as the entry point directly.
yep! However this is a website I made for hosting my own notes in the browser browser (sorry for the load times, no bundler so each file is a seperate request)
https://akst.io/vis/20250601-complex-geo/?app=unsw.2102.01-1
That said, when I write tests, I write them in Typescript for that reason.
JSDoc is great. But remember, JSDoc is used for well trained developer. For those junior programmer, they will totally ignore it and write lots of shxt code. At least TypeScript can force them to use correct type like forcing them not to use "any" type.
Thanks, I use JSDoc for several years, and also validate it with Typescript. So I just write plain Javascript with JSDoc, with no build step. Typescript only validates the types, and not transforming the code. Did you also know that you can import Typescript types/interfaces in JSDoc? So for me typescript is not a language anymore, I use only the tool to validate the types.
Best thing for me was not removing the code transformation (convert ts to js), but separate runtime code with documentation code, like the types. Gives you much more clear insight that the types you write to describe what you expect the type will be is not forced on runtime, but is just for you as developer to know it. And when you validate the input is the right type, it is much more clear that it is the runtime type validation.
You can still use JSDoc in your typescript files, but why do you want to do that? There is no reason to do that.
So using JSDoc or Type Annotation, both works the same, same benefits, it is only personal preferences. Both have its pros and cons. For me the JSDoc has more benefits. Some other people prefer annotations. But there is not 1 that is better in controlling the types, has more options. (Also the enum can be done if you are using JSDoc, but is a little different)
> You can still use JSDoc in your typescript files, but why do you want to do that?
JSDoc is more than type annotations. I use it for method and parameter descriptions, deprecation notices, inline examples, etc even in TS files.
I work in a codebase that unfortunately does not support TypeScript. I use JSDoc extensively, although not with type check enabled (due to various limitations). I also work on other projects with TypeScript. My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc, without question. JavaScript with JSDoc is much more verbose, with a lot of limitations when types get long or complex compared to TypeScript. The official TypeScript language service also does not provide the same level of support in very subtle ways.
Basically, the fact that it works does not mean it works well, and I don't recommend anyone going in this other direction unless they understand what they are getting into.
> although not with type check enabled (due to various limitations)
Curious what limitations there are on static type checking. It seems like a matter of your IDE setup
> My own experience is that the DX with "real" TypeScript is much, much better than JavaScript with JSDoc
I agree with the DX point. I would just point out that if you're using JSDoc and getting intellisense from it, you are using TypeScript
Not a limitation in language service, but an issue with the codebase itself -- legacy codebase with a lot of missing/incorrect typing from upstream JavaScript code (owned by other teams), making it practically impossible to actually run type check.
Been there, tried that. When starting to write JavaScript in anger 3 or 4 years ago, I started out with JSDoc, because my impression was also, hey, that is like TypeScript, but closer to the metal and maybe with less magic. A few months in I realised that TypeScript is just a better and more well-rounded implementation of what JSDoc has to offer (I don't remember now, but there were annoying things that you would expect would work in JSDoc, but didn't quite).
Just use TypeScript.
> For packages typed with JSDoc, CTRL/CMD clicking on a function will take you to actual code rather than a type declarations file. I much prefer this experience as a dev.
More broadly, this is the default behavior of JS even without JSDoc blocks, and it ought to be the default behavior everywhere, including TS. I'm not alone in this sentiment, but it's incredibly contentious. There's been an open GH issue about it with hundreds of replies for years. I have no idea why they can't just pick a different shortcut for viewing types and call it a day. They'd be doing the entire ecosystem a favor.
Not when the TS team refuses to fix long standing issues preventing JSDOC from operating properly in VSC, for example https://github.com/microsoft/TypeScript/issues/16665
To be honest, I find Ryan Cavanaugh's argument against this quite convincing. It's weird to have something documented if you import the .ts file, but not if you import a .d.ts generated from it. If you want to show the value of the default argument of a function, you should probably just add it to the doc comment — not the type.
The argument is that it doesn't surface the default written within the jsdoc block comment even when provided by the developer.
JSDoc works great for buildless application setups! One downside is that if you publish a library to npm you still need a build step to generate .d.ts files from your JSDoc type annotations so that npm shows a "TS" badge on the npm package page. This also seems to apply to VSCode's intellisense which keeps trying to poke you to "try to install @types/jsdoc-typed-package to get type information". Other JS ecosystem tooling also doesn't seem to process JSDoc types at all such as jsdocs.io or tsdocs.dev. So for libraries we're stuck with .d.ts generation via "tsc --allowJs --checkJs --declaration ..." even if it's all JS.
npm displays packages with bundled TypeScript declarations https://github.blog/changelog/2020-12-16-npm-displays-packag...
JSDoc-typed node modules require special configuration in consumers to be useful https://github.com/microsoft/TypeScript/issues/19145
A somewhat related thing programmers must understand is that whether you write typescript, JSX, .astro or .svelte files, you are technically not writing JavaScript.
You should occasionally look at the build artifacts of your framework but also ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Lately I just use vite with no starter template but with web components and css modules. It at least feels more convenient than using any framework or library.
This seems like an issue but in all my practical experience it really isn't. TypeScript becomes JavaScript with the types removed. Then you tree-shake, minify, and whatever is executed is no where near what you actually wrote but at the same it totally is the same because that's no different than any other compilation process.
Occasionally, I have to remember that JavaScript has no types at runtime but it's surprisingly not that often.
I mean what makes it more acceptable is that you have HMR and instant preview during development. So, all the transformations and bundling aside, you do see how it runs during development.
However I have been in a few situations at work where all of a sudden we did have issues that required us to dig deeper. There were also some bundling related issues that caused problems in production deployments. At that point many co workers had no idea how to even approach it to be honest.
I've had similar experiences with compiled languages in one form or another throughout my career as well. I don't think JavaScript is particularly special that we need to call it out for things like TypeScript, minification, or bundling.
> ask yourself whether it is worth it to write code that may not represent what actually ends up being executed.
Doesn't this describe every programming language?
When you write C, you are technically not writing machine code.
Even when you write JavaScript, what actually gets executed is V8 bytecode and/or machine code (depending on whether the JIT fires).
That's correct, however I would say there is a small difference in that most of this code still seems just like JavaScript, sometimes it even feels as though it is JavaScript running in the same context when it then gets compiled to run on server/client.
I think the point I'm trying to make is that this can be confusing or even dangerous especially for new developers. It just doesn't hurt to actually look at the Vite plugins transforming it all to understand it instead of making assumptions if we work with it on the daily.
Yeah it’s a silly line of reasoning. The transformations of TS -> JS are a lot smaller and simpler than C-> asm / machine code; it’s basically just removing type annotations. Now minification and optimization can make the output a lot more terse, but that can be done for JS too. And it’s not as complicated and detached from the source as an optimizing compiler is.
Let's not act like it's the same thing. I'm not strictly talking about just Typescript, I'm saying that if you work with these technologies every day it would be wise to go look at their Vite plugins to see how they transform your code and be sure to understand it. It's nice to have magic but it's nicer to use the magic if we have demystified it first.
And I don't know about you, but I occasionally do open compiled ELF files in a hex editor and I certainly did at first when I was learning more. That's a good practice also.
Aren't you loosing a lot of the declarative features like signals or similar, when you do your projects without those frameworks?
(asking to learn)
Somewhat. I could still use framework agnostic state management libraries/patterns and most are (e.g. svelte signals, jotai, zustand, etc.).
I've even used Proxies directly to implement some reactivity before. However as for the "declarative" parts, I think it's just a little bit of a different way to work but you get used to it and imo it pays off. Knowing the web APIs should be a requirement anyway and it doesn't hurt to work with them directly as much as possible.
I’m surprised TypeScript is controversial to some people. Having worked on a large vanilla JavaScript framework, the benefits were pretty clear.
Many of us don't encounter the sort of problems Typescript offers to solve. As most programming languages, most of the bugs I create when using JS is logic bugs, and those are solves by unit testing, not "more types". It was a long time ago I managed to push broken frontend code because of assuming the wrong types, so personally I don't find TS that valuable. But obviously others seem severely impacted by those types of issues, otherwise TS wouldn't be so popular in the first place. People be different :shrug:
Myself and this post are also pro-TypeScript!
I still think that JS is very much not TS. Most TS code assumes you never need to check for errors because the type checker proves they can't happen.
Then, paradoxically, with no error checking at runtime, it becomes fully possible for JS code to call into TS code in a way that breaks the shit out of the TS compiler's assumptions. In philosophy then TS and JS are as incompatible as GPL and EULA
It doesn't matter if a library is written in TS or JS; you cannot meaningfully protect against other code calling you incorrectly.
Sure, you can check if they gave you a string instead of a number. But if you receive an array of nested objects, are you going to traverse the whole graph and check every property? If the caller gives you a callback, do you check if it returns the correct value? If that callback itself returns a function, do you check that function's return type too? And will you check these things at every single function boundary?
This kind of paranoid runtime type-checking would completely dominate the code, and nobody does it. Many invariants which exist at compile-time cannot be meaningfully checked at runtime, even if you wanted to. All you can do is offer a type-safe interface, trust your callers to respect it, and check for a few common mistakes at the boundary. You cannot protect your code against other code calling it incorrectly, and in practice nobody does. This is equally true for JS and TS.
Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though. Dealing with external input requires type assertions (since Typescript doesn't know what the program is getting at compile-time) and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
However, if your point is that Typescript can lull people into a false sense of safety, then sure, I take your point. You have to understand where type assertions are coming into play, and if that's obscured then the type safety can be illusory. The benefits of Typescript require you to make sure that the runtime inputs to your program are sufficiently validated.
> Writing a Typescript program that takes external input but has no runtime error checking is already a mistake, though.
If it's a service, yes, and that's true no matter what technology the service is using. If it's a library, no, because...
> and if you write type assertions without ensuring that the assertions are accurate, then that's on you, not Typescript.
That's on whoever is using the library, not the library author. If the library author provides type definitions, and you as the consumer choose to ignore them, then it's on you.
TS certainly thinks of external input as a boundary requiring safety, but usually that would mean form input or CLI args parsing or something.
Usually there's little if any protection against a JS caller providing wrong-type args to TS functions.
Sure, but if the caller is Javascript then you're running Javascript, not Typescript*, so it makes sense that you're not going to get type safety.
I'm also not sure we're actually disagreeing on anything, so perhaps my reply was pointless. I agree that if you mix JS and TS in the way you describe, you'll have problems. My reply was just to say "yes, and that's not really Typescript's fault", but perhaps you weren't implying that to begin with.
* I'm aware that you can't run Typescript directly, but I hope my point here is clear... you're running a program that wasn't type-checked by TS.
I don't think we're disagreeing either. I didn't mean to suggest that it was Typescript's fault, just that the relationship between TS and JS in theory is something like "TS is a superset of JS" but once you get down to the practice of writing idiomatic reusable code it's more like TS and JS are fully different languages.
Something similar is true for most statically typed languages.
If you write a C library, nothing stops someone from writing an assembly-language program that calls functions in your library with the wrong types.
The type checker can only prove what is known at compile time and only if you're disciplined.
To bridge runtime and compile time (as your application will likely get some external data) you've got to use a proper parser such as zod[1] or if you want to stretch it even further effect-schema[2].
[1] https://zod.dev/
[2] https://effect.website/docs/schema/introduction/
I’m currently in love with Arktype, and as it supports Standard Schema it plugs into most places that can take Zod schemas too :)
https://arktype.io/
That's a validator, not a proper parser, no?
What's the difference here? I've only used Zod but I typically think of Zod as a runtime validation library. AFAIK arktype is a full-featured replacement for Zod
I don't think I understand the difference you're drawing on here? It parses data and validates its structure, and is a replacement for all my uses of Zod?
This is how I develop web software, and I've found it productive and maintainable.
A bonus of this approach is that it clearly delineates what type information is available at runtime, vs what type information is just a comment. (especially useful when working with serialized data).
I also like that it generally means all of the preconditions and postconditions for functions are in a single place (both the prose and the technical information are in the JSDoc comment), keeping the code itself low-noise and boiled down to its essence, and providing a natural place to write example inputs and outputs to guide usage.
As for generic types, I use them extensively, and this is made less verbose e.g. on function calls by using an @type annotation on the function which accepts a TypeScript signature without needing separate @template + @param annotations.
It's awesome stuff, and I'm happy that TypeScript works so well with JSDoc!
I'm a big advocate for explicit type annotations in code. Likewise, either or is good with me. However, these days I lean towards using JSDoc only because I prefer not to add typescript lib and an additional build step just to get type safety in a project.
Also, you can use both (if that's what you prefer).
Can you perform type checking with JSDoc? As in, run type checks in CI/CD, commit hooks, etc?
Yes. As described in the article, the TypeScript compiler understands type annotations that are written in JSDoc syntax. So you can use `tsc`, just like you would to check `.ts` files.
To address point 2 you can enable the VSCode setting: "TypeScript: Prefer Go To Source Definition".
If it's your own library you can add declarationMap: true to your tsconfig.
I almost always want to see the source when I cmd+click.
What I would really like to see is a TS compiler that emits .js libraries with typing information compiled as JSDoc comments.
Webpack is typed using JSDoc and type-checked via TypeScript -- I started this migration a while ago. It works pretty well
Wow I had no idea! Have you written anywhere about your experiences?
Some TypeScript features are only available through JSDoc. The one I encounter most often is `@deprecated`.
What do you mean? Jsdoc has it
https://jsdoc.app/tags-deprecated
I think he’s saying that only JSDoc has it. Vanilla TS doesn’t.
Personally, given the limitations of JSDoc, I'd like to see a header-file like definition system for build-less applications (like libraries).
Where values in `index.js` can be typed in the header file with complete TypeScript syntax and those types are present in the target file via intellisense and type checking AndThis can be done, and is done in some projects, but the problem is that you need to manually maintain both sets of files, which can easily go out of sync if you're not careful. You also lose out on the ability to check your own code - using the header file you've written there, you can't really check the implementation of `useStr` to check that it works.
The advantage of JSDoc is that the TypeScript compiler treats it as equivalent to TypeScript source code, which means you've still got access to type checking inside your functions.
One thing I've seen in a few places is still to have DTS files that declare all sorts of types that are used in the application, and then have those files imported by JSDoc comments. That way, you've got TypeScript syntax for your types, which tend to get bulky and difficult to read in JSDoc syntax, but you still don't need a build system because the DTS imports are ignored completely at runtime.
You can define a declaration file alongside its target however the target does not use the types defined within its declaration within itself - only consumers see the types.
There are three issues with that.
The first is that JSDoc doesn't support everything you need in TypeScript and there is a lot of inlining (like typedef causes collisions, there's no importing a type without also re-exporting it from the importing file unless you inline the import)
The second is that JSDoc isn't picked up from imported libraries (or at least I don't think it is?)
Lastly, you still need a transpiler to remove the comments and build d.ts files.
In the end, JSDoc isn't practical for projects. The header file strategy means you don't need to transpile ever (only a typechecker) and you'd get the full suite of TypeScript functionality - at the cost of synchronization overhead.
For a project using JSDoc, you'll graduate to TypeScript when there is sufficient complexity anyway. Migrating from a d.ts file is way easier (potentially automatable) than migrating from JSDoc.
The problem with the header file strategy is that TypeScript doesn't have total type inference. That approach works e.g. in OCaml, where you can (optionally) type the boundaries of the function and everything inside the function can always be inferred. But TypeScript works differently and doesn't support that approach. So fundamentally, what you're describing isn't really possible without using a very restrictive subset of TypeScript that can be totally inferred or having very broad type definitions.
So even if TypeScript did check the header file against the implementation, you'd still need additional annotations inside the implementation file. At that point, why not put all the annotations inside the implementation file directly?
Regarding your points:
1. JSDoc does support everything that TypeScript supports (that's the point of this article), although it does not necessarily support it as cleanly, hence why projects like Svelte typically use DTS files to define the project's types, and have those be imported inside JSDoc annotations. It's not perfect, but it gets you a long way.
2. You're right, JSDoc isn't picked up from imported libraries, but if you're publishing a library, you'll have a build script there, and at that point it's typical to generate the DTS files and pack those with the source code. That seems fairly reasonable to me — while developing, you don't need to worry about building files, but then when packaging and releasing you do.
3. You don't need a transpiler with JSDoc, the point behind JSDoc is that it's literally just the pre-existing JS documentation syntax. You can (and should) leave the comments in. Even if you're using TypeScript syntax, you should have JSDoc annotations (although adding the types to those annotations is redundant in that case). You can also just include the DTS files. As long as they're only imported from JSDoc, the runtime won't see them.
Personally, having tried out JSDoc-based TypeScript, I'd rather just use the native type stripping in Node for development, and keep with TS syntax, but there are large projects that have made the opposite choice, most noticeably Svelte. So I don't think it's a given that JSDoc users will inevitably graduate to TypeScript (especially when projects have gone in the opposite direction).
Aside from the following, JSDoc is absolutely TypeScript.
Discriminated unions, conditional types, mapped types, template literal types, recursive type aliases, higher-kinded type patterns, generic constraints with conditional inference, the infer keyword, never type exhaustiveness checking, const assertions, readonly tuple and array inference, exact object types, key remapping in mapped types, indexed access types, variance annotations, assertion signatures, strict null checking with flow-sensitive narrowing, definite assignment assertions, the satisfies operator, declaration merging, module augmentation, symbol-typed properties, type-safe enums
…and not written via comments
Yes, all of these are supported in JSDoc because they are supported in TypeScript. Because JSDoc is TypeScript. You can either define your types in JSDoc comments or in .ts files.
I really mean it. You can even use the @satisfies operator like so
Discriminated unions, conditional types, mapped types, template literal types, etc work exactly the same way if you define them in a JSDoc comment as if you define them in a .ts fileSounds like Scala type fetishism all over again.
I am always using JSDocs whenever i am writing a function - i think this is a good practice for every developer - even if it's a simple function.
jsdoc is nice because you don’t have to write the non-helpful types.
---
In WebStorm, jsdoc can be rendered in HTML, which makes the code easier to scan. Here's a side-by-side VSCode vs WebStorm:
https://x.com/efortis/status/1989776568676221137
---
And in jsdoc you can have an inline description:
> you don’t have to write the non-helpful types
This entirely depends on your tsconfig setup. You can run a JSDoc-typed project in strict mode exactly the same way you would a *.ts-typed project.
Do you know if it's possible to do that the other way around?
You mean a TypeScript project without strict mode? Sure. Again, whether you're defining types in JSDoc comments or in .ts files, the behavior is entirely governed by a tsconfig file
Oh man, the mention of ScriptSharp brought back memories. I started my career at MSFT on SharePoint and the front end was an ungodly mix of ScriptSharp and other stuff.
I vividly remember being in a meeting with the Exchange team (about building shared frontend components) arguing for us to adopt TS instead as it had a better experience and very rapidly growing popularity (that was about 10 years ago). Plus, as strong as Nikhil [0] was, he was basically the only person behind ScriptSharp while TS had a whole team.
Of course, this being MSFT, this effort went no where. While true that the TS toolchain lacked the tree-shaking that ScriptSharp had, I was just annoyed that we had to build stuff using what was obviously an dead-ish language with limited support, many flaws, and no resources to improve it.
But hey, at least it wasn’t GWT.
[0] https://github.com/nikhilk
From what I've read, many of TypeScript's design regrets have political origins. Enums and other features that oppose TS's structural type system were added as compromises with C# developers in MS and similar negotiations with the Angular team in order to increase adoption of TypeScript over alternatives
I would love to know where you read this!
Oh gosh, I don't think I can recall a specific source. I've listened to many interviews with the TypeScript team and in Q&A they're often asked about their "biggest regrets". Early on TypeScript's adoption was far from a sure thing. After convincing Microsoft their biggest threat was Angular's own AtScript (and maybe even Flow). TypeScript was extremely beholden to whatever Microsoft or Angular devs wanted to be added to the language in order for them to agree to push TypeScript as the future
Not really, at best it's a verbose and limited subset.
https://github.com/tc39/proposal-type-annotations?tab=readme...
It's certainly more verbose but certainly not a limited subset. You can copy paste any typescript Type or Interface in a jsdoc @typedef. As I stated in the article, it's still the TypeScript language service that's analyzing either JSDoc-defined types or TypeScript defined types. It's typescript all the way down
But JSDoc lets you do pretty much everything that isn't a runtime feature of TypeScript (e.g. enums, namespaces, etc). Even generic slots are supported
You just haven't worked in a complex enough project yet.
I found several limitations and already opened several issues on github.
Although it's more verbose, it makes code less dense because it lives outside the function parameters.
Also, it's not a super limited subset. For instance, you can write types in .d.ts the IDE uses those types in jsdoc out of the box.
The list of things jsdoc cannot do is long but a simple example is overloading, you cannot express this[1] in jsdoc, and if you need to reference .d.ts files you're back at using TypeScript, so the point of JSDoc was...?
If you need precise return typing, conditional types, literal values, etc, you aren't going far if anywhere with JSDoc.
[1] https://shorturl.at/pg5dL
There a few points in favor of TS types in jsdoc (in order):
1. not having to type everything (many types are not helpful)
2. makes code less dense (and they can be rendered in HTML) https://x.com/efortis/status/1989776568676221137
3. not needing a compiler (browsers don't support TS)
I think the main jsdoc caveat is around private types.
About 1, IDK if there’s a way to set up TS for that.
This specific one is actually supported since TypeScript 5.0:
https://devblogs.microsoft.com/typescript/announcing-typescr...
But not properly documented (https://www.typescriptlang.org/docs/handbook/jsdoc-supported...), which shows how much Microsoft neglects JS + JSDoc workflow. Github issues have been created a long time ago, but nothing has been done so far. Apparently Microsoft is too busy with their AI slop to work on actually useful stuff.
Eh. I agree with the principle. I’ve written personal projects with JSDoc because I truly love the idea of finally being done with build systems and just serving the files I write without a step in between.
But it’s more annoying than just writing TypeScript. There are ways to express just about everything TypeScript can but they’re all more difficult and convoluted (generics are a great example). For a project of any reasonable size I’m still going to advocate to use TypeScript.
No it isn’t, otherwise Closure Compiler would (still) be running MS365
“There’s nuance” yeah as much in my comment as the headline at the top of the article
I like the mention to someone from the React team as it seems TypeScript/type safety did not help them create better, safer software.
Writing better, safer software is more of a cultural problem than a language problem. Languages can only do so much.
And in fact, this what the Closure Compiler does…typecheck based on JSDoc.
However, the precision and completeness is not nearly what can be expressed in TypeScript. With generics particularly.
Care to give an example? In another reply I pointed out how advanced JSDoc syntax's support for generics is.[0] Even allowing for `extends` and default values for generic slots.
The clunkiest part is in the way you "pass in" a generic to a slot. But this is solved by typing the return type.
I use generics pretty extensively and I've not yet come across a use-case JSDoc couldn't handle
[0] https://news.ycombinator.com/item?id=46267810
Ah.....you're putting TypeScript in JSDoc annotations.
Which is a lot different than vanilla JSDoc [1].
I understand.
[1] https://jsdoc.app/
JSDoc doesn't have a formal spec. Most modern development on JSDoc syntax happens by the TypeScript team. Every release of TypeScript also includes notes about JSDoc syntax.
Almost any modern IDE is also parsing JSDoc comments through the TypeScript language service. So many people don't realize they are already using TypeScript (hence the name of this post).
I don't think it's particularly controversial to say that the form of JSDoc that the majority of developers are familiar with IS JSDoc. The distinction is more of a historical one than a technical one (since there is no formal JSDoc spec)
Agree. It’s superior. I arrived at this about 2 years ago no regrets. Type safety matters on the tooling side anyway. Unless you’re testing for the runtime I guess?
I'm glad to hear you've had a good experience with JSDoc but I want to reiterate that my position isn't that JSDoc is superior. Just that it is TypeScript
Yes I’m saying, starting from equality Id add on to say it’s actually the better form. TypeScripts extra enforcement adds complexity without usefulness.
The sooner we get https://github.com/tc39/proposal-type-annotations, the better.
Once we get it, there is still a solid decade before runtimes support it, and optimistically, still more 10 years minimum having to deal with an interpreted language that has acquired an unecessary build step.
I absolutely hated when PHP switched from a phpDoc culture with static analysis (and IDE inconsistencies that would click-take you to stubs as well) to actual types. Not because I hate types, but because of the transition period. Once it's gone, it's such a relief to get rid of unecessary docblocks.
That proposal is a nonstarter. It cannot and will not ever be accepted
Please elaborate!
The proposal is to introduce a whole slew of syntax to JS that according to the proposal will have no meaning. This is a paradox. You have only created a language if you can use it to convey meaning
That's not entirely true. Ideally, there would be a follow up with a reflection API.
Also, comments are syntax and they're mostly meaningless. By your reasoning, programming languages should have no comments.
So, it's not really a qualitative issue (presence of meaningless syntax) but a quantitative one (presence of lots of parsing complexity).
If you say that whatever data is put there doesn't matter at all, the one thing you definitely cannot ever do later is give it meaning.
Unless I say it's meaning is to be optionally reflected upon during runtime!
Look, I understand the purism and mostly, I agree. But this is not a clean slate language, it will never be perfect and it's going to become more and more idiosyncratic as times go by.
I don't see how it's optional.
Comments are a kind of freedom in code. You're completely free to use them precisely because (in a plain execution environment) they cannot influence the result of evaluation
If comments /can/ change the result of evaluation then you simply are not (completely) free to use them. (And yes I know that this is a simplification in JS where you can already get the source code of a function with toString... Ugh)
Makes sense. I'm excited for your solution, despite not having seen it. If you can solve that, it would be awesome.
Something needs to change. I don't care about one specific proposal.
It's miserable having a de-facto build step for an interpreted language. Worst of both worlds.
Maybe just TS is fast, but it encourages developers to put more and more stuff into that build step (and they do, they do that a lot). Culturally, that trend is not going to change unless the main reason for having said build step is removed.
The whole babel/transpiling thing was meant to be temporary. It became temporarily permanent / permanently temporary.
I'm the person who is developing a permanent solution.
Which is?
A standard environment in which to run code that extends the builtin parser.
Why?
In short, we can do much better. I'm building a full syntax extension/macro evaluation mechanism for JS.
Where is it? What is it called?
It's called BABLR as it takes concepts from Babel (transpiling) and ANTLR (parsing arbitrary syntax). https://github.com/bablr-lang/
I'm currently in the process of trying to pull together our first big release.
The proposal likely won't go anywhere. The first sentence in README says enough about it.
Who cares what some framework guy thinks. When I was writing JavaScript for employment most people doing that work were hyper concerned with how to write code and what other people thought about it. These kinds of opinions and conversations are critically important for beginners, but junior and senior developers never seemed to get past these concerns of basic literacy.
When other developers and non-developers look at JavaScript developers as small children it’s because the maturity difference is very evident from the outside. Once developers get past basic literacy they are free to worry about architecture, performance, scale, platform independence, and more. For most JavaScript developers they just expect some framework to do it for them.
Dunno. Your comment seems pretty immature and strangely emotional. If you think you’re too good for these sorts of articles and this sort of tech, then maybe you’re also too good for the related discussion.
I guess you are only looking for praise or pity. If that is the case then yes, I am too good/mature for your work and discussions.