JSDoc is TypeScript
48 comments
·December 14, 2025mirekrusin
creatonez
> 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.
measurablefunc
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
akst
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...
zackify
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
sntxcmp
[dead]
pjmlp
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.
llimllib
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
sureglymop
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.
efortis
Besides less dense code, and not needing compilation, jsdoc is also nice because you can omit the needless types.
Also, 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:
@prop {number} width Video width in pixelscrummy
> 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
agumonkey
could be a customizable behavior in editor/ide though
IshKebab
This works with Typescript too though?
filleduchaos
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.
conartist6
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
md224
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.
conartist6
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.
epolanski
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/
neallindsay
Some TypeScript features are only available through JSDoc. The one I encounter most often is `@deprecated`.
sureglymop
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.
wvenable
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.
kaufmann
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)
sureglymop
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.
umanwizard
> 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).
vlovich123
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.
sureglymop
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.
sureglymop
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.
austin-cheney
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.
mohsen1
Webpack is typed using JSDoc and type-checked via TypeScript -- I started this migration a while ago. It works pretty well
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)