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

[GregTheGreek]

Ah sorry i misread the OP.

[technicallyty]

Would it be possible to use something other than 🍎, 🍏? Finding it hard to distinguish between the two as a color deficient individual

[vasco-santos]

Hello @technicallyty ,
You are right about it! I will modify this to text, thanks for reaching out

[vasco-santos]

As an update here, we have libp2p types being generated for core since libp2p@0.30. Slowly we will be adding types for each libp2p modules. The support is not fully complete, specially in the libp2p config side of things but we will iterate on that over the next months.

Let me know if you hit issues

[nazarhussain]

@vasco-santos I will be working on adding typescript support to js-peer-id next. Please assign it to me here to avoid collision.

[BigLep]

Resolving in favor of #1021