Why are yjs types writen with jsdocs and not typescript?


All libraries by dmonad are written in a way that creates the .d.ts files from JSDoc comments instead of using TypeScript files themselves. I would love to understand why you would do it this way. Could someone please explain it to me?


My guess: Yjs existed long before TS was useful enough, and in the meantime JSDoc was perfectly fine. Rewriting things in TS takes some time. I suppose that if someone offers to rewrite everything in a PR, it might get accepted though.

Interesting question…

The simple reason why everything is written in pure JavaScript is that I don’t like code transpilation. I can run my tests in nodejs or using 0serve (part of lib0), which imports modules by compiling an importMap, but doesn’t transform the source code at all. Also, my debugging experience is flawless because it doesn’t have to use source maps. I heavily depend on a good debugging experience.

Have you ever tried debugging async code in Typescript using the node debugger? It’s awful. The debugger jumps around to random places. Sometimes you can’t set breakpoints at specific lines. Code is “optimized” without you noticing, which makes debugging a headache. That alone is a good reason not to use Typescript. Source maps still are too unreliable for me.

As you probably noticed, all my modules are fully typed. There is no reason to convince me to use typescript. I already do. JSDoc comments are a fully compatible alternative to writing the custom TypeScript language that needs to be transpiled. The Typescript compiler understands JSDoc comments. I you run tsc in any of my projects, it will report type errors as if the source code was written in typescript. I haven’t heard any good arguments for switching to the TypeScript language yet, so I’m sticking to JSDoc comments.

Why even invent a whole new language for creating types? Typescript does so much more (too much) than transpiling types. I don’t want typescript to polyfill my code.

Personally, I don’t like the type system in TypeScript much. I find the flowtype language more interesting than typescript. But we probably can do a lot better. I bet that we gonna get a cool new (native) type system directly embedded in the JavaScript language in the next few years. The javascript runtime can use this information to make our code more performant. Until then, I’m gonna use JS + JSDoc. (w3c proposal: GitHub - tc39/proposal-type-annotations: ECMAScript proposal for type syntax that is erased - Stage 1)

I suppose that if someone offers to rewrite everything in a PR, it might get accepted though.

Please don’t! I rejected multiple PRs that transform my modules to typescript. I will also reject PRs that add semicolons - they are superfluous as well :wink: