4 ms·

You can have this now adding types with JSDoc and validating them with typescript without compiling, you get faster builds and code that works everywhere withou

You can have this now adding types with JSDoc and validating them with typescript without compiling, you get faster builds and code that works everywhere without magic or need to strip anything else than comments. The biggest pain point of using JSDoc at least for me was the import syntax, this has changed since Typescript 5.5, and it's now not an issue anymore.

murmansk 2y ago
[flagged]
- adhamsalama 2y ago
  You can write TypeScript types in JSDoc.
  - sureIy 2y ago
    You can’t write complex TypeScript types in JSDoc, which is what GP said. The moment you need to declare or extend a type you’re done, you have to do so in a separate .ts file. It would be possible to do so and import it in JSDoc, but as mentioned before it’s a huge PITA on top of the PITA that writing types can already be (e.g. function/callbacks/generics)
- dobladov 2y ago
  You should write complex types in interfaces files where they belong, and there's full typescript support. I use this approach professionally in teams with many developers, and it works better for us than native TS. Honestly give it a try, I was skeptical at first.
  - rty32 2y ago
    In general JSDoc is just much more verbose and has more friction, even outside complex types. I recently finished a small (20 files/3000 lines), strictly typed JS project using full JSDoc, and I really miss the experience of using the real TypeScript syntax. Pain points: annotating function parameter types (especially anonymous function), intermediate variable type and automatic type-only import, these are the ones that I can remember. Yes you can get 99% there with JSDoc and .d.ts files, but that's painful.
    - dobladov 2y ago
      I use snippets to write those, yes it's more verbose there's not denying that. For me the advantages of just having JS files and not worrying about more complex source-maps, build files, etc definitely makes it worth it.
      - FractalHQ 2y ago
        Source maps and build files are automatically generated when bundling which you need to do with or without typescript… so this argument always confuses me. There is no tangible downside in my experience.. either way it’s just typing “pnpm build”.
- afavour 2y ago
  I’ve had a lot of success combining JSDoc JS with .d.ts files. It’s kind of a Frankenstein philosophically (one half using TS and one half not) but the actual experience is great: still a very robust type system but no transpiling required. In a world where ES modules are natively supported everywhere it’s a joy to have a project “just work” with zero build steps. It’s not worth it in a large project where you’re already using five other plugins in your build script anyway but for small projects it’s a breath of fresh air.
  - flanbiscuit 2y ago
    I do this as well. JSDoc is great for simple definitions, but as soon as you want to do something more complicated (generics, operators, access types, etc) you get stuck. The .d.ts are ignored because you're only importing them within JSDoc comments.
- Waterluvian 2y ago
  Jsdoc is honestly fine for simple and smaller projects. But yeah, it’s definitely not nearly as expensive while being anywhere as succinct.
  - yard2010 2y ago
    JSDoc is for docs, TypeScript is a static type checker. How can these tools be used interchangeably?
    - styfle 2y ago
      You can configure tsconfig.json to read JSDoc and error on invalid types so that you effectively get the same behavior as writing typescript.
- meiraleal 2y ago
  [flagged]
- tracker1 2y ago
  JSDoc is also helpful in dealing with multiple argument option types for a function or constructor, which won't show in TS alone.
  - sroussey 2y ago
    You can do it in TS. https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads https://www.typescriptlang.org/docs/handbook/2/functions.htm...
itsmeste 2y ago
I strongly agree, but JSDoc isn't "the cool thing". So it's left to be used by us, who care (and read their docs).
- llimllib 2y ago
  The auto-export of declared types was what killed it for me
epolanski 2y ago
JSDoc absolutely does not scale and allows for very limited type programming. It's fine on toy projects, and somewhat I would say, for 99% of users that don't even know what a mapped or intersection type is.
- mablopoule 2y ago
  JSDoc does not scale, but some projects are just better when they aren't scaled. JSDoc is indeed fine on toy project, or in fact any project (even prod-ready ones) that doesn't warrant the trouble of adding NPM packages and transpilation steps. Although they are rare, those type of small, feature-complete codebases do exists.
eezing 2y ago
Good for annotating js files here and there, but lousy dx.

murmansk 2y ago

[flagged]

adhamsalama 2y ago
You can write TypeScript types in JSDoc.
- sureIy 2y ago
  You can’t write complex TypeScript types in JSDoc, which is what GP said. The moment you need to declare or extend a type you’re done, you have to do so in a separate .ts file. It would be possible to do so and import it in JSDoc, but as mentioned before it’s a huge PITA on top of the PITA that writing types can already be (e.g. function/callbacks/generics)
dobladov 2y ago
You should write complex types in interfaces files where they belong, and there's full typescript support. I use this approach professionally in teams with many developers, and it works better for us than native TS. Honestly give it a try, I was skeptical at first.
- rty32 2y ago
  In general JSDoc is just much more verbose and has more friction, even outside complex types. I recently finished a small (20 files/3000 lines), strictly typed JS project using full JSDoc, and I really miss the experience of using the real TypeScript syntax. Pain points: annotating function parameter types (especially anonymous function), intermediate variable type and automatic type-only import, these are the ones that I can remember. Yes you can get 99% there with JSDoc and .d.ts files, but that's painful.
  - dobladov 2y ago
    I use snippets to write those, yes it's more verbose there's not denying that. For me the advantages of just having JS files and not worrying about more complex source-maps, build files, etc definitely makes it worth it.
    - FractalHQ 2y ago
      Source maps and build files are automatically generated when bundling which you need to do with or without typescript… so this argument always confuses me. There is no tangible downside in my experience.. either way it’s just typing “pnpm build”.
afavour 2y ago
I’ve had a lot of success combining JSDoc JS with .d.ts files. It’s kind of a Frankenstein philosophically (one half using TS and one half not) but the actual experience is great: still a very robust type system but no transpiling required. In a world where ES modules are natively supported everywhere it’s a joy to have a project “just work” with zero build steps. It’s not worth it in a large project where you’re already using five other plugins in your build script anyway but for small projects it’s a breath of fresh air.
- flanbiscuit 2y ago
  I do this as well. JSDoc is great for simple definitions, but as soon as you want to do something more complicated (generics, operators, access types, etc) you get stuck. The .d.ts are ignored because you're only importing them within JSDoc comments.
Waterluvian 2y ago
Jsdoc is honestly fine for simple and smaller projects. But yeah, it’s definitely not nearly as expensive while being anywhere as succinct.
- yard2010 2y ago
  JSDoc is for docs, TypeScript is a static type checker. How can these tools be used interchangeably?
  - styfle 2y ago
    You can configure tsconfig.json to read JSDoc and error on invalid types so that you effectively get the same behavior as writing typescript.
meiraleal 2y ago
[flagged]
tracker1 2y ago
JSDoc is also helpful in dealing with multiple argument option types for a function or constructor, which won't show in TS alone.
- sroussey 2y ago
  You can do it in TS. https://www.typescriptlang.org/docs/handbook/2/functions.html#function-overloads https://www.typescriptlang.org/docs/handbook/2/functions.htm...

itsmeste 2y ago

I strongly agree, but JSDoc isn't "the cool thing". So it's left to be used by us, who care (and read their docs).

llimllib 2y ago
The auto-export of declared types was what killed it for me

epolanski 2y ago

JSDoc absolutely does not scale and allows for very limited type programming. It's fine on toy projects, and somewhat I would say, for 99% of users that don't even know what a mapped or intersection type is.

mablopoule 2y ago
JSDoc does not scale, but some projects are just better when they aren't scaled. JSDoc is indeed fine on toy project, or in fact any project (even prod-ready ones) that doesn't warrant the trouble of adding NPM packages and transpilation steps. Although they are rare, those type of small, feature-complete codebases do exists.

eezing 2y ago

Good for annotating js files here and there, but lousy dx.