When TypeScript?

[ukstv]

Considering lot of JS IPFS codebase is in TypeScript, when do you expect multiformats to be converted to TypeScript? What are the blockers?

[rvagg]

No, would this unblock something for you though? We should be exporting type definitions that are accurate as it's built into the build, testing and linting toolchain here so they're not just handcrafted. So I'd be interested to know what the advantage would be to users of us doing a TypeScript conversion here.

[ukstv]

So I'd be interested to know what the advantage would be to users of us doing a TypeScript conversion here.

When something weird happens in IPLD codebase, eventually you end up going through all the relevant code. Once in a while it leads to bunch of tabs open with TS code, and multiformats (and some others) in JS, which requires quite a context switch to grok.

[wemeetagain]

I'm in favor of converting this library to typescript. Several reasons:

• Many of the downstream libp2p and ipfs libraries have been rewritten recently in typescript. The developer base overlaps a lot, and as @ukstv pointed out, the inconsistency and context switch is not necessary and moving to typescript would be helpful for these developers.
• Would-be contributors may have to wrangle with the autogenerated types tooling. I know personally I don't care to maintain a type autogenerator tool and would prefer to contribute directly to a typescript codebase.
• Community-maintained projects should use community standards. Non-standard tooling is sufficient in hobby and personal projects, but when catering to a larger community, standardization and consistency is key. Like it or not, typescript is the standard for all large-scale javascript codebases. Using typescript here aligns with other protocol labs-maintained code and also with the direction of the wider javascript community.

[achingbrain]

My experiences of converting the js-libp2p stack to TypeScript have been a net positive, with some exceptions as to how we release changes to interfaces in external modules.

I don't think we could release changes with any real degree of confidence across so many modules without TypeScript. Obviously tests are king in all this but simple type checking has removed a whole class of bugs.

Doubling down on that using JSDoc to generate types places a lot of limits on what you can do, for example, interface support isn't there so you normally end up with some typescript in your project anyway.

JSDoc is also full of weird gotchas like when you use @typedef {import('./foo.').Bar} Baz if you check the generated .d.ts file you get a new type rather than reusing the existing one. This is fine for TypeScript as the new type has 100% overlap with the old one but it causes problems for documentation generators since they document both types.

The type contortions we regularly do with JavaScript aren't possible with TypeScript, at least, it's possible if you try really hard but generally it's much less effort to just do the simple thing, then you end up with a codebase that is much easier to follow and everyone wins.

Finally the type annotations proposal has reached stage 1 so this stuff might be coming anyway, we'd just get slightly ahead of the curve.

[rvagg]

ugh, well, I suspect @Gozala would be on board with this so that would leave me as the lone holdout in terms of who's left maintaining this stuff, so I suppose I won't be a blocker if someone wants to take on the task of converting this and making it 1:1 compatible with what we publish now.

[p-shahi]

@rvagg I believe @wemeetagain has already done the conversion here #251

[Gozala]

ugh, well, I suspect @Gozala would be on board with this so that would leave me as the lone holdout in terms of who's left maintaining this stuff, so I suppose I won't be a blocker if someone wants to take on the task of converting this and making it 1:1 compatible with what we publish now.

Here are my sentiments in no particular order tl;dr While I won't fight for this, I do find context switching to be worthwhile tradeoff for:

1. Keeping run / eval without compilation flow
2. Not affecting less TS inclined contributors (like @mikeal and @RangerMauve) productivity

Here is the longer version:

1. 💚 TS syntax is more concise, easier to read and write
2. 💔 Having a compilation step while fairly common is still annoying especially if you frequently use of the REPL, I often do and I think pure JS camp folks de also.
   • If we nodejs was more like deno this probably would not matter
3. 💔 I find debugging compiled TS code in browsers to always be inferior to debugging the code that simply used JSDoc annotations.
   • I'm sure there is some way to resolve this, but in practice it usually is a problem
   • I find this context switch to be a lot more pain than switching between TS syntax and JSDoc syntax
4. 💔 Error stacks traces are not accurate
   • Again can be resolved, but in my experience for one reason or another I do find myself having to figure where errors actually occured.
5. 💚 TS syntax, unlike JSDoc is free of the gotchas that @achingbrain has outlined.
   • For what it's worth those can be addressed, more on that later

At the end of the day I personally care about benefits type checker brings and not about the new notation that TS team has invented. If I have to deal with compilation, I would much rather write in more proper typed language like Rust.

Dealing with all the TS in JSDoc quirks

Doubling down on that using JSDoc to generate types places a lot of limits on what you can do, for example, interface support isn't there so you normally end up with some typescript in your project anyway.

Yeah you can't define interface next to implementation. I do however think that forcing you to separate interface definition from implementation is a nudge into right direction. Our team settled on pattern where we define interfaces in a separate api.ts file providing interface definitions, which is then imported from the file defining implementation claiming compliance via @implements tag.

• Here is an example of api.ts file defining an interface

• Which is then a class claims to implement in js file

JSDoc is also full of weird gotchas like when you use @typedef {import('./foo.').Bar} Baz if you check the generated .d.ts file you get a new type rather than reusing the existing one. This is fine for TypeScript as the new type has 100% overlap with the old one but it causes problems for documentation generators since they document both types.

That is annoying indeed and TS team seems to have no interest fixing (probably they are more focused on type annotations syntax proposal).

We address above issue by not doing import typedefs, instead we just import api.ts file as a module, which unfortunately at runtime requires empty js files but not a big deal in practice.

I believe that also avoids doc generation issues.

The type contortions we regularly do with JavaScript aren't possible with TypeScript, at least, it's possible if you try really hard but generally it's much less effort to just do the simple thing, then you end up with a codebase that is much easier to follow and everyone wins.

Again jsdoc syntax is definitely not as pleasant to read / write but I'm not sure if I've encountered a case where I could not express something I needed and would be curious to know the examples. I think TS jsdoc syntax is not as well documented, but feature wise other than interface and abstract classes I don't think they're really apart.

Conclusion

I don't think switching to TS syntax is a clear win, at leas not until type annotations syntax extension has shipped in JS engines (and when that happens I highly suspect some TS syntax will also change or get deprecated).

I would suggest carefully weighting tradeoffs before going ahead with this. Either way I'm not going to stand in they way.

As an aside this might be a good opportunity to exercise community driven collective decision making

[Gozala]

I think we should also let @hugomrdias weave in on this, who used to advocate for TS in JSDoc, (and convinced me it was better tradeoff than TS which I used to be in favor of) yet more recently had to work with pure TS code base, unless I'm mistaken.

[matthewkeil]

I tend to agree with @wemeetagain and @achingbrain. TS is pretty much the industry standard such that its syntax is being incorporated (almost the same) into base JS with the type annotations proposal (that I am very much looking forward to!!). It will bring consistency to what most large projects already use. While it is a hurdle to initially get over, it is well worth it for both community inclusion, developer experience and modernization of syntax. +1 vote for TS.

[nazarhussain]

I personally believe Typescript vs JS+JSDoc debate should be over by now.

There were so many known issues in vanilla JS, because of which Tyepscript was eventually inevitable, and not all those issues can be addressed by adding up a few JSDoc comments on top of JS code. If that were the case community would have evolved more towards it, instead of adopting the TS ecosystem. If one wants to go with the generic evolution of the ecosystem, then one must move to TS to make projects future-proof. The benefits it would bring to contributors are also not hidden a simple Google search can list thousands.

That was all from the contributor's side of view, how about the consumer? What do consumers need? Ultimately three things 1) Stable library 2) Better Typesafety 3) Best Documentation. For the first two points, TS can be very helpful to achieve for later points TS can provide a better value addition with less maintainability for mismatch types.