Hacker News Reader

Comment by murmansk | Hacker News Reader

[flagged]

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.

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.

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.

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.

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.

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”.

JSDoc is also helpful in dealing with multiple argument option types for a function or constructor, which won't show in TS alone.

You can do it in TS.

https://www.typescriptlang.org/docs/handbook/2/functions.htm...

Jsdoc is honestly fine for simple and smaller projects. But yeah, it’s definitely not nearly as expensive while being anywhere as succinct.

JSDoc is for docs, TypeScript is a static type checker. How can these tools be used interchangeably?

You can configure tsconfig.json to read JSDoc and error on invalid types so that you effectively get the same behavior as writing typescript.

You can write TypeScript types in JSDoc.

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)

Reply on news.ycombinator.com