TS to JSDoc Conversion

It's not 1:1 in features though, but because you can import definitions https://www.typescriptlang.org/docs/handbook/jsdoc-supported... you can use a file a part whenever you encounter any of those advanced features / edge cases current JSDoc does not support.

Like other said, it's still TS after all, and there are escape hatches when needed.

In so many projects I use JSDoc TS, the amount of projects that ended up needing a manual .d.ts file not utomatically generated via `tsc` can be counted in half hand.

Maybe people could give it a try, after all if you comment a method, beside its signature and return types, you can as well just move types in there ;-)

This is surprisingly true in a way. TypeScript is not a language(1), it's primarily a linter-assisting overlay atop of an actual language, JavaScript. Also, there's a linter that outputs and bundles JS, shedding the alien type annotations and also injecting its own, very partial runtime.

So, JSDoc is just a linter/documenter aid. And so is TypeScript.

(1) TS is not a language: it has no spec, no reference documentation. It defines no behaviors, in particular, no runtime behaviors. It sits atop of various JS versions, layering over them in unspecified ways. TS is a linting layer, and also is a hack.

Well, it adds up, if you're doing multiple projects.

Doing a quick scan of my work desktop, I find 43,237 filenames matching ".js.map". The biggest is at ~10,000 KB, the smallest at 1KB. If we assume the average is just 200KB, in total they represent ~8.6 gigabytes (200 kilobytes 43237). That's not nothing.

> And bandwidth? Like we don't have several cache systems - including npm's - that can help?

Being conservative with bandwidth is a good thing for most. Not only will everything download faster because less is needed, but it'll probably be cheaper for you to run your application as serving less bandwidth either gives you a small bill if you use cloud, or requires less hardware if you're going the dedicated route.

Not to mention not everyone sits with the latest maxxed out Apple hardware for working, especially outside the SV bubble. These people deserve to be able to have a good development environment as well.

Overall, everything gets faster and cheaper if you save bandwidth.

> Ok, is there someone who can explain in details how would that help?

It's easy, the lesser moving parts your application has in the abstraction ladder, the safer and easier it gets to change things in the future.

Transpiling from one language to another to get a benefit you can also get by not transpiling a language from one to another, seems like a no-brainer to me in most cases.

First, to ensure a focused discussion, I think it's a good idea to separate out TypeScript the transpiler, TypeScript the language, TypeScript the type-checker, and by extension, TypeScript 'types'.

Personally, I don't like transpilers. I never liked CoffeeScript and I hate not being able to see the 'actual' code when looking inside a Docker image in a K8s cluster. I also don't like using non-standard features in a language; I'd far rather live without something that is TS-specific, and if it turns out that this feature has legs, then just wait for it to be included in vanilla JS. (Not to mention that it smacks too much of vendor lock-in, for not much benefit.)

But I do get that this is to some extent because I'm primarily coding to Docker images, rather than multiple browsers. If I want to bump the version of Node to get some new feature, it's pretty easy. So I do recognise that for people working on the client side, where bundling and source maps and all that other chaos is the norm, then transpiliation is no big deal.

(Having said that, back in the day we all used to love that you could hack away on a web app using files on a file system, just loading HTML, JS, and CSS... It's a shame that we seem to have lost the 'vanilla first' approach to software, and leap to preprocessors for everything.)

Anyway... my first point is simply that TypeScript as a _transpiler_ doesn't have any appeal to me.

But I'm not about to throw the baby out with the bath water.

As with the original post, I love types! I think TS types are the best thing to happen in years. Where possible I like to use declaration files as the single source of truth (type first development). From there you can generate GraphQL and OpenAPI schemas, use them to drive contracts for implementation, share the files with other developers using other languages, and so on. And as with this post, I make the connection between the types in the declaration files and the code in the JS files, primarily through inference, and then as necessary through JSDoc.

As with many things, there is going to be a lot of personal preference to this. Since I like the way that Haskell puts type information on a separate line to the function that is being described, it's probably no surprise that I also find the JSDoc approach of putting the types in separately more intuitive.

And since it's easy to configure an editor/IDE to use TSC to lint and provide intellisense on JS files, you can get all of the advantages of TypeScript without having to transpile.

That seems like I pretty good deal to me!