Should @web3-storage/api have a more uniform style guide around how to author typescript types?

[gobengo]

Motivation:

• @gobengo started using a .ts file in this pr. Previously we mostly just use jsdoc @typedefs
  • @vasco-santos suggest a team discussion on whether we should adopt a uniform way of authoring types

Notes:

• could apply to api package or whole repo

[gobengo]

Would be great to uniform how we want to proceed with the whole team.

Personally I think it's not that important to be fully uniform about this. The jsdocs @typedefs are useful to create type aliases in the js files for intra-file use (it cuts down on many big import(...) in the jsdocs). But the jsdoc syntax is kludgy and not always able to express the whole type system, so then it makes sense to use .ts files. Even though there are ts files for some types, because those ts files are only linked to from jsdocs, all the js should run without transpilation still.

I don't mind at all establishing some kind of more strict norm, just presenting the case for incrementalism/agility over uniformity. I can be down with anything, especially if we have ci robots enforce all style policies (e.g. by a linter or other static analysis).

[vasco-santos]

Thanks for raising this @Bengo.

We use jsdocs in most of our projects to have types while dev, as well as to generate types on client releases. But recently, for things like bindings in CF Workers we have been moving to use a bindings.ts file, which personally have been super helpful for me while developing.

Having extra types as needed declared in types files rather than jsdocs is something that I am ok with, but don’t know if it brings a lot of value. For defining interfaces though, that is super valuable.

I feel like we can start using more typescript files for types/interface declarations, but would like to define a standard to use by the whole team, instead of having all project differently.

[hugomrdias]

What we do now is a mix of jsdoc for simple stuff and a .ts (not .d.ts) file for complex types definition and that works pretty well.
examples:
https://github.com/web3-storage/ucan-protocol
https://github.com/web3-storage/ucanto

if you want to avoid the bigger import(..) @Gozala has a trick for it, just create a empty .js file with the same name as the .ts file and then you can just do import * as Types from 'types.js at the top of your files.

I also have been crafting for a long time a stable, 0 conflicts config for ts, eslint, standard and prettier here https://github.com/hugomrdias/hd-scripts