{"id":44,"date":"2024-07-31T09:59:24","date_gmt":"2024-07-31T07:59:24","guid":{"rendered":"https:\/\/thomaswormann.com\/?p=44"},"modified":"2026-05-08T12:25:39","modified_gmt":"2026-05-08T10:25:39","slug":"typescript-vs-jsdoc","status":"publish","type":"post","link":"https:\/\/thomaswormann.com\/?p=44","title":{"rendered":"TypeScript vs. jsDoc"},"content":{"rendered":"

In a recent Javascript project I was part of, the team was given a lot of freedom regarding the choice of tech stack. We knew we didn’t want Node\/NPM because our app would be part of a suite of apps in a high-security environment, and there had been a recent flare-up of security incidents with NPM packages.<\/p>\n

So we actively researched alternative JS runtimes for testing and running scripts. Bun wasn\u2018t ready then, so we quickly settled on Deno<\/a>. Deno has a great out-of-the-box experience, being everything from a runtime, linter, formatter, all in a single binary.<\/p>\n

One notable feature is the TypeScript support, making TypeScript a first-class option. So we took a close look at TypeScript, and I was especially delighted, as I had some experience with C# and its static typing and prefer it over dynamic typing.<\/p>\n

Around the same time, I learned that TypeScript is actually designed by the same guy who also made C#, Anders Hejlsberg<\/a>, who also<\/strong> happened to design Turbo Pascal, the first programming language I learned in school. It’s a bit crazy how full circle this feels.<\/p><\/blockquote>\n

But the team lead after a couple of weeks decided against TypeScript, much to my dismay. So we compiled everything down to Javascript, made some manual modifications and moved on. But after having had a taste of static typing in the Javascript context and witnessing the power of Intellisense in my IDE, I just couldn’t let go of it. What had originally been a tidy workspace felt like it was quickly deteriorating into spaghetti code.<\/p>\n

So I did some more research on alternatives for static typing in Javascript and discovered jsDoc<\/a> and Flow<\/a>. I found jsDoc to have better tool-integration than Flow, so I went that route.<\/p>\n

In its simplest form, decorating an ES class with TypeScript looks something like this.<\/p>\n

\/**\n * Foo class\n * @class\n * @extends Bar\n * @description Does things\n *\/\nclass Foo extends Bar {\n  \n  \/** @type number *\/\n  amount;\n\n  \/**\n   * @constructor\n   * @param {number} amount \n   *\/\n  constructor(amount) {\n    this.amount = amount;\n    this.doThing(amount); \/\/ <- throws warning for type mismatch\n  }\n\n  \/**\n   * @method\n   * @param {string} name\n   * @description Does things\n   *\/\n  doThing(name) {\n    console.log(\"Doing things \" + name);\n  }\n  \n}\n<\/code><\/pre>\n
As you can see in the following screenshot, in an IDE like Webstorm<\/a>, this gives us some nice visual type hints and a warning regarding type mismatch.<\/p>\n
\"\"<\/figure>\n
In Visual Studio Code<\/a> you have to add \/\/@ts-check<\/a> to the top of the file to enable type-checking (which uses TypeScript under the hood). It doesn’t give you the visual hints Webstorm<\/a> does, but it also recognises the type mismatch and gives you some Intellisense.<\/p>\n
\"\"<\/figure>\n
I think with these simple annotations, jsDoc can give you 90% of the editor user experience that TypeScript gives you, without requiring a build step<\/a>.<\/p>\n
After dropping TypeScript in the aforementioned project, I became quite happy with this solution, as it doesn’t require a build step or any special tooling.<\/p>\n","protected":false},"excerpt":{"rendered":"
Can jsDoc provide a similar editor experience while ditching the build step?<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"webmentions_disabled_pings":false,"webmentions_disabled":false,"activitypub_content_warning":"","activitypub_content_visibility":"","activitypub_max_image_attachments":4,"activitypub_interaction_policy_quote":"anyone","activitypub_status":"federated","footnotes":""},"categories":[1],"tags":[2],"class_list":["post-44","post","type-post","status-publish","format-standard","hentry","category-uncategorized","tag-javascript"],"_links":{"self":[{"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/posts\/44","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=44"}],"version-history":[{"count":1,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/posts\/44\/revisions"}],"predecessor-version":[{"id":46,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=\/wp\/v2\/posts\/44\/revisions\/46"}],"wp:attachment":[{"href":"https:\/\/thomaswormann.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=44"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=44"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/thomaswormann.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=44"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}