JSDoc is TypeScript

Original Article ↗ Hacker News Discussion ↗

What “JSDoc is TypeScript” Means

  • Pro side: In modern tooling, JSDoc comments are parsed by the TypeScript language service.
    • The same engine provides squiggles, IntelliSense, and can be run via tsc --checkJs.
    • Many TS features work in JSDoc: generics (@template), utility types (ReturnType, etc.), conditional/mapped/template literal types, @satisfies, @overload, intersections, @extends, etc.
    • You can often copy–paste TS type declarations into @typedef blocks.
  • Counter side: Conceptually JSDoc is “just comments”; using TS tools on it doesn’t make it the same language.
    • Analogy: running on Windows doesn’t mean you are “using C++”; JSDoc is a format, TS is a language and type system.

Limitations and Rough Edges of JSDoc

  • Some capabilities behave differently or are missing in practice:
    • @typedef types are always exported and can’t be scoped, which pollutes libraries’ public surface and IntelliSense.
    • Certain combinations of tags (@callback, generics, arrow functions) are fragile or require non‑obvious workarounds.
    • Some TS constructs (type‑only imports, satisfies, complex overload sets, some “extends” patterns, private/internal types) either don’t map cleanly or need .d.ts sidecars.
    • Official jsdoc doc‑generator does not understand newer TS-style annotations that the TS server accepts.
    • Several people report that large JSDoc‑typed codebases expose edge cases and poorer DX vs equivalent TS.

Build Step vs “Just JavaScript”

  • JSDoc advocates:
    • No transpile step for browsers or Node; files run as-is.
    • Useful for small or “buildless” stacks (native HTML/CSS, web components, lit‑html, etc.).
    • Clearer separation of runtime behavior from static documentation/types.
  • TS advocates:
    • Once you already bundle/minify/HMR, a TS erase step is trivial cost.
    • TS syntax is less verbose and clearer for complex types; better tooling and documentation; easier to manage large projects.
    • Node now supports native TS type-stripping; for libraries you often need .d.ts anyway, which reintroduces a build step for JSDoc users.

Type Safety, Interop, and Philosophy

  • Consensus that static typing (via either JSDoc+TS or TS files) is valuable documentation and prevents many classes of bugs.
  • Multiple comments stress that types don’t replace runtime validation, especially with external input or JS→TS boundaries.
  • Some argue TS and JS feel like different languages in practice; others see JSDoc and TS annotations as two front ends to the same TypeScript type system, chosen based on project size and build‑pipeline tolerance.