Hacker News Reader

Comment by dobladov | Hacker News Reader

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.

View on HN

[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)

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

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

The auto-export of declared types was what killed it for me

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.

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.

Reply on news.ycombinator.com