13 ms·

JSDoc is TypeScript

• zwb2324550 11mo ago
  [dead]
• zackify 11mo ago
  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 11mo ago
    The difference is syntax compression imo.
  • TheRealPomax 11mo ago
    > 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).
    • Sammi 11mo ago
      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.
      • TheRealPomax 11mo ago
        Welcome to the "a cat [1] has four legs [2], and therefore everything with four legs [3] is a cat [1]" fallacy. That's not how that works. JSDoc is its own spec, and is not typescript, and is absolutely not at type annotation parity with typescript. Plenty of things that are hard to type in TS that are impossible to annotate use JSDoc. So: just because tsc, the tool, can read in typing information that was written in JSDoc, does not make JSDoc typescript. tsc simply supports JSDOc. Very handy! Not the same thing in the slightest. 1. "typescript" 2. "can be read by tsc" 3. "anything that tsc can read"
        • Sammi 11mo ago
          You are mixing theory with practice. In theory felines can be both cats and tigers. In practice the felines walking around your neighborhood are all cats.
          • TheRealPomax 11mo ago
            ...what? No of course not, that's an absolutely ridiculous thing to say. ∀A -> B does not mean ∀B -> A, it only means ∃B -> A. tsc, the executable, not only supports TypeScript, the language, but also knows how to read JSDoc when you're not giving it TypeScript. It supports JSDoc for code that isn't TypeScript. I'd repeat that a few more times but hopefully twice is enough to make the point obvious.
            • deleted 11mo ago
              [deleted]
            • Sammi 11mo ago
              Sure. In theory people could be doing that. But for the third time: what is happening in practice? What people _could_ be doing vs what they _are_ doing was explicitly my point, so please stop pretending it wasn't, less we have to repeat this merry go round.
              • TheRealPomax 11mo ago
    • culi 11mo ago
      > 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
      • KPGv2 11mo ago
        > 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"
      • anovick 11mo ago
        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++".
        • matt_kantor 11mo ago
          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".
          • anovick 11mo ago
            I understood it that way too. Only that it fails in that interpretation. Just because currently the most popular method for parsing JSDoc utilizes TypeScript-related tooling doesn't mean we should associate them with each other. To my previous example, an ISO C++ can be compiled by GCC but also can be compiled by Clang (and many other compilers).
• llimllib 11mo ago
  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 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 11mo ago
    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.
  • culi 11mo ago
    That's technically a fair complaint but feels like a minor nitpick. Just don't `@import` the types you don't want to use.
• pjmlp 11mo ago
  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.
• user3939382 11mo ago
  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?
  • culi 11mo ago
    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
    • user3939382 11mo ago
      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.
• gaigalas 11mo ago
  The sooner we get https://github.com/tc39/proposal-type-annotations 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.
  • conartist6 11mo ago
    That proposal is a nonstarter. It cannot and will not ever be accepted
    • botten 11mo ago
      Why?
      • conartist6 11mo ago
        In short, we can do much better. I'm building a full syntax extension/macro evaluation mechanism for JS.
        • herpdyderp 11mo ago
          Where is it? What is it called?
          • conartist6 11mo ago
            It's called BABLR as it takes concepts from Babel (transpiling) and ANTLR (parsing arbitrary syntax). https://github.com/bablr-lang/ https://github.com/bablr-lang/ I'm currently in the process of trying to pull together our first big release.
    • 11mo ago
• sureglymop 11mo ago
  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.
  • School-Cotton 11mo ago
    > 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 11mo ago
      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 11mo ago
        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.
    • 11mo ago
• crummy 11mo ago
  > 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 11mo ago
    could be a customizable behavior in editor/ide though
    • g947o 11mo ago
      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.
  • IshKebab 11mo ago
    This works with Typescript too though?
    • filleduchaos 11mo ago
      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.
      • sthuck 11mo ago
        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?)
      • homebrewer 11mo ago
        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).
• conartist6 11mo ago
  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
  • epolanski 11mo ago
    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/ https://zod.dev/ [2] https://effect.website/docs/schema/introduction/ https://effect.website/docs/schema/introduction/
    • girvo 11mo ago
      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/ https://arktype.io/
      • epolanski 11mo ago
        That's a validator, not a proper parser, no?
        • culi 11mo ago
          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
        • girvo 11mo ago
          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?
• strongpigeon 11mo ago
  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 https://github.com/nikhilk
  • culi 11mo ago
    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
    • pavo-etc 11mo ago
      I would love to know where you read this!
      • culi 11mo ago
        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
• paulddraper 11mo ago
  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.
  • culi 11mo ago
    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 https://news.ycombinator.com/item?id=46267810
    • paulddraper 11mo ago
      Ah.....you're putting TypeScript in JSDoc annotations. Which is a lot different than vanilla JSDoc [1]. I understand. [1] https://jsdoc.app/ https://jsdoc.app/
      • culi 11mo ago
        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)
• mirekrusin 11mo ago
  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)
  • measurablefunc 11mo ago
    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 https://news.ycombinator.com/item?id=14905043
  • creatonez 11mo ago
    > 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.
    • g947o 11mo ago
      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.
      • trekz 11mo ago
        > 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?
        • g947o 11mo ago
          https://news.ycombinator.com/item?id=46268701 https://news.ycombinator.com/item?id=46268701
• austin-cheney 11mo ago
  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.
  • christophilus 11mo ago
    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.
    • austin-cheney 11mo ago
      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.
• akst 11mo ago
  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/c9fea8b465317f41da2a10d7c1d493c811803e32/lib/app/sec-unsw/sec-2102/sec-05-3/util.js#L11-L14 https://github.com/AKST/analysis-notebook/blob/c9fea8b465317... - Here's the type https://github.com/AKST/analysis-notebook/blob/c9fea8b465317f41da2a10d7c1d493c811803e32/lib/app/sec-unsw/sec-2102/sec-05-3/type.ts#L18-L36 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/c9fea8b465317f41da2a10d7c1d493c811803e32/lib/base/runtime/config/type.ts#L52-L60 https://github.com/AKST/analysis-notebook/blob/c9fea8b465317...
  • g947o 11mo ago
    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.
    • akst 11mo ago
      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 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.
• epolanski 11mo ago
  Not really, at best it's a verbose and limited subset. https://github.com/tc39/proposal-type-annotations?tab=readme-ov-file#limits-of-jsdoc-type-annotations https://github.com/tc39/proposal-type-annotations?tab=readme...
  • efortis 11mo ago
    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.
    • epolanski 11mo ago
      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 https://shorturl.at/pg5dL
      • g947o 11mo ago
        This specific one is actually supported since TypeScript 5.0: https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#@overload-support-in-jsdoc https://devblogs.microsoft.com/typescript/announcing-typescr... But not properly documented (https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html 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.
      • efortis 11mo ago
        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 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.
• mohsen1 11mo ago
  Webpack is typed using JSDoc and type-checked via TypeScript -- I started this migration a while ago. It works pretty well
  • culi 11mo ago
    Wow I had no idea! Have you written anywhere about your experiences?
• deleted 11mo ago
  [deleted]
• efortis 11mo ago
  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 https://x.com/efortis/status/1989776568676221137 --- And in jsdoc you can have an inline description: @prop {number} width Video width in pixels
  • culi 11mo ago
    > 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.
    • efortis 11mo ago
      Do you know if it's possible to do that the other way around?
      • culi 11mo ago
        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
• neallindsay 11mo ago
  Some TypeScript features are only available through JSDoc. The one I encounter most often is `@deprecated`.
  • pyrolistical 11mo ago
    What do you mean? Jsdoc has it https://jsdoc.app/tags-deprecated https://jsdoc.app/tags-deprecated
    • christophilus 11mo ago
      I think he’s saying that only JSDoc has it. Vanilla TS doesn’t.
    • neallindsay 11mo ago
      Isn't that what I said?
• emseetech 11mo ago
  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.
  • auxiliarymoose 11mo ago
    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.
  • bobbylarrybobby 11mo ago
    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.
    • emseetech 11mo ago
      I haven't run into any steps that require one, there's always alternatives. Do you have anything specific in mind?
      • webstrand 11mo ago
        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.
• deleted 11mo ago
  [deleted]
• casmn 11mo ago
  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.
• afavour 11mo ago
  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.
• g947o 11mo ago
  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.
  • culi 11mo ago
    > 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
    • g947o 11mo ago
      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.
• auxiliarymoose 11mo ago
  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!
• sgammon 11mo ago
  No it isn’t, otherwise Closure Compiler would (still) be running MS365
  • sgammon 11mo ago
    “There’s nuance” yeah as much in my comment as the headline at the top of the article
• sgammon 11mo ago
  [flagged]
• etoxin 11mo ago
  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.
  • culi 11mo ago
    > 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.
    • c-hendricks 11mo ago
      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 https://github.com/jsdoc/jsdoc/issues/1917#issuecomment-1250760267 https://github.com/jsdoc/jsdoc/issues/1917#issuecomment-1250...
      • culi 11mo ago
        tuples, `&` operator, and even generics all work perfectly well inside a `@type` declaration. For example: ```js /** * @type {{ * slug: `${string}_${number}`; * id: number; * } & { status?: [code: number, text: string]; }} */ const example = { slug: 'abc_34', id: 34 }; is the exact equivalent of ```ts const example: { slug: `${string}_${number}`; id: number; } & { status?: [code: number, text: string] } = { slug: 'abc_34', id: 34 }; 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.
• jcbhmr 11mo ago
  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-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 https://github.com/microsoft/TypeScript/issues/19145
• Brysonbw 11mo ago
  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).
• CSSer 11mo ago
  > 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.
• Waterluvian 11mo ago
  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."
  • culi 11mo ago
    > 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.
    • KPGv2 11mo ago
      > 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.
      • egeozcan 11mo ago
        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.
• eezing 11mo ago
  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
  • culi 11mo ago
    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
  • cutler 11mo ago
    Sounds like Scala type fetishism all over again.
• brazukadev 11mo ago
  I like the mention to someone from the React team as it seems TypeScript/type safety did not help them create better, safer software.
  • jason_oster 11mo ago
    Writing better, safer software is more of a cultural problem than a language problem. Languages can only do so much.
• notpushkin 11mo ago
  What I would really like to see is a TS compiler that emits .js libraries with typing information compiled as JSDoc comments.
• apatheticonion 11mo ago
  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
  • MrJohz 11mo ago
    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.
    • apatheticonion 11mo ago
      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.
• auggierose 11mo ago
  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.
• Lorin 11mo ago
  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 https://github.com/microsoft/TypeScript/issues/16665
  • n2d4 11mo ago
    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.
    • Lorin 11mo ago
      The argument is that it doesn't surface the default written within the jsdoc block comment even when provided by the developer.
• tobyhinloopen 11mo ago
  > 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 https://nodejs.org/en/learn/typescript/run-natively
  • eevilspock 11mo ago
    that's limited to node. won't work in a browser.
    • tobyhinloopen 11mo ago
      Oh right I forgot Javascript also runs in a browser
  • spoiler 11mo ago
    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.
• w3news 11mo ago
  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)
  • supernes 11mo ago
    > 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.
• Hrun0 11mo ago
  I’m surprised TypeScript is controversial to some people. Having worked on a large vanilla JavaScript framework, the benefits were pretty clear.
  • embedding-shape 11mo ago
    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:
  • culi 11mo ago
    Myself and this post are also pro-TypeScript!
• Merad 11mo ago
  Can you perform type checking with JSDoc? As in, run type checks in CI/CD, commit hooks, etc?
  • matt_kantor 11mo ago
    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.
• columk 11mo ago
  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.
• hilarycheng 11mo ago
  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.
• braebo 11mo ago
  JSDoc is ugly, clumsy, and leads to worse types on average over time. Typescript can be executed directly these days just use Bun and build steps are instant.