Support for Typescript users

[vasco-santos]

Taking into account the adoption of js-libp2p by several typescript projects and the previous discussions around this topic, we decided to create a plan to better enable typescript users.

We will be following the same ideas gathered by the IPFS team in ipfs/js-ipfs#2945. Like IPFS, libp2p modules use ipfs/aegir for the project building. Aegir will be supporting typescript with jsdoc (ipfs/aegir#568) 🎉

We want to start by using JSDoc to declare types for the top level API first and internally we will add types incrementally where we feel it adds value.

A TS config will be added to the repo to enable type declaration generation from JSDoc comments.

We will provide:

• a type declaration files published inline with the source files
• always up-to-date declarations for the public api
• documentation generated with typedoc

The typescript community has previously tried to contribute for getting this support in libp2p, but unfortunately we did not have a plan at the time and we did not get much progress. The libp2p core team will not be able to tackle this over the next months, as we will be working on protocol level improvements, but the contributions of everyone interested in having a better support for libp2p in typescript are welcome!

Let us know if you have questions, and fill free to claim a module by commenting in this issue :)

Status	Package	Owner	PR
DONE	libp2p-interfaces	@vasco-santos	libp2p/js-libp2p-interfaces#74 -- Needs follow up
DONE	js-libp2p	@vasco-santos	#802 -- Needs follow up #830
DONE	js-libp2p-utils	@vasco-santos	libp2p/js-libp2p-utils#16
DONE	js-libp2p-bootstrap	@acolytec3	libp2p/js-libp2p-bootstrap#111
TODO	js-libp2p-crypto
TODO	js-libp2p-crypto-secp256k1
TODO	js-libp2p-delegated-content-routing
TODO	js-libp2p-delegated-peer-routing
TODO	js-libp2p-floodsub	@vasco-santos	libp2p/js-libp2p-floodsub#114
DONE	js-libp2p-kad-dht	@achingbrain	libp2p/js-libp2p-kad-dht#214
TODO	js-libp2p-mdns
TODO	js-libp2p-mplex
DONE	js-libp2p-record	@achingbrain	libp2p/js-libp2p-record#25
WIP	js-libp2p-rendezvous	@vasco-santos	libp2p/js-libp2p-rendezvous#6
DONE	js-libp2p-tcp	@nazarhussain	libp2p/js-libp2p-tcp#145
TODO	js-libp2p-webrtc-star
TODO	js-libp2p-webrtc-direct
TODO	js-libp2p-webrtc-star
TODO	js-libp2p-websockets
TODO	js-peer-id	@nazarhussain

Note that with this effort, we also aim to get #308 to the finish line, thanks to the documentation being generated by typedoc.

[vasco-santos]

cc everyone who interacted regarding typescript support:
@wemeetagain @mpetrunic @carsonfarmer @samparsky @jacogr @IwraStudios @GregTheGreek @Mikerah @patwhite

[mpetrunic]

For lodestar, we are using: https://github.com/chainsafe/libp2p-ts which can be useful to compare generated types or port directly if it's difficult to generate typings.

Note: we haven't yet updated to latest version of libp2p, so some stuff might be different.

[GregTheGreek]

I wonder if it makes sense to merge the types upstream? Unless you're goal is to write native typescript files?

[vasco-santos]

I wonder if it makes sense to merge the types upstream? Unless you're goal is to write native typescript files?

@GregTheGreek the goal is to write jsdocs with typedef that will enable aegir to generate types declarations inline with the source files on build. This will provide the types declarations for the users. They will not be written, but generated by aegir. ipfs/aegir#568 will allow this to happen