[BOUNTY] Community Improvement Bounty - libp2p - TypeScript bindings for js-libp2p-*

[raulk]

TypeScript bindings for js-libp2p-*

We want to make js-libp2p pleasurable to use from TypeScript. Get the TypeScript definitions in order, and run with 1000 EUR! 🤑

This will not only help TypeScript developers, but also plain old JavaScript developers who use VSCode or other IDEs that support TypeScript-sourced autocompletion for plain JS.

See devgrant 8 in the libp2p/devgrants tracker: libp2p/devgrants#8

The brief for this bounty can be found here: https://github.com/libp2p/devgrants/blob/master/008-typescript-bindings.md.

How to qualify

Check out the existing TypeScript definition files maintained by the Polkadot project.

Start with the libp2p entrypoint, and browse the imports.

We would like to port these over to the js-libp2p-* repos, so they can be maintained there, for the benefit of the entire community. You should:

1. Test those definitions, and make sure they're current, accurate and correct with regards to the current js-libp2p code.
2. Adjust the definitions that aren't on par with reality.
3. Create any new definitions that are missing.
4. Write TypeScript definition tests, similar to the ones in the DefinitelyTyped repo, e.g. express-tests.ts.
5. Add a build step to the package.json file in all affected repos to trigger the TS definition tests. We'd like the build to break loudly and dramatically if we make changes to the API that break the definition files.

Submit pull requests to each js-libp2p-* repo as you progress.

Resources

Definitely start with the definition files under the polkadot-js repo.

Check out these past discussions:

• libp2p (and friends) index.d.ts for TypeScript libp2p/js-libp2p#208
• Typescript: partial declaration files libp2p/js-libp2p#346
• https://github.com/ipfs/js-ipfs-http-client/issues/864
• https://discuss.ipfs.io/t/typescript-type-definitions-for-ipfs-api/2057/3

Feel free to use @raulk as a walking encyclopedia for all things libp2p.

Judging Criteria

1. Completeness, correctness, cleanliness and maintainability of code.
2. Definition tests.
3. Documentation / code comments.
4. It actually works, and you can demo it.

Prizes

1. 500 EUR via the Community Improvement Bounties fund.
2. 500 EUR via Protocol Labs.

[mariapaulafn]

Note - The Community Improvement Bounties are funded by the ETHBerlin fundraising efforts - if your project needs these bounties to work better with libp2p - consider helping out. High incentives make happy hackers

[raulk]

The reward for this hack project is 1000 EUR. Good luck!

[samparsky]

@raulk I am interested in working on this, I am at ETHBerlin
I am planning on using autogenerated typescript definitions via JsDoc

[raulk]

@samparsky I didn’t know that was possible. Mind sharing a link to a page that describes this feature? Feel free to start working on it. Make sure you start off with the existing definitions, as noted in the bounty! Good luck 👍

[alxroyer]

Hi all. Really interested in this feature.
@samparsky: Smart approach. If you need help for this, I'd be pleased contributing. Let me know.

[samparsky]

@Alexis-ROYER Are you at ETHBerlin?

[samparsky]

@Alexis-ROYER Yeah I could use some help. Can you reach out via telegram, my telegram username is geekou

[samparsky]

@raulk I wasn't able to complete everything during the hackathon,

I have opened a PR here for js-libp2p-bootstrap

libp2p/js-libp2p-bootstrap#95

And a draft PR to the js-libp2p repository

libp2p/js-libp2p#449

[philipstanislaus]

@samparsky are you going to finish these? Otherwise I’ll have a shot later. Thanks!

[samparsky]

@philipstanislaus Yeah I am going to, do you wanna work on it together?

[samparsky]

@philipstanislaus It was quite much to finish up during the hackathon as there are 13 repositories requiring types addition. Also, types generation is being automated via JSDoc as its much more easier to maintain. you can check out libp2p/js-libp2p-bootstrap#95 to have an idea

We can split it up if you are interested

[philipstanislaus]

Got it, looking forward to use them! Thanks!

[samparsky]

@philipstanislaus Are you interested in splitting it up and working on it together?

[philipstanislaus]

@samparsky sure, let’s do that. I’ll get back to you in a bit.

[vasco-santos]

@samparsky @philipstanislaus thanks for working on this. Let me know in case you need any help 🙂

[ryanchristo]

@samparsky @philipstanislaus @vasco-santos I'd be happy to help out as well.

[samparsky]

@ryanchristo You can reach out to me on telegram but I am not sure I need any more help right now

[samparsky]

@vasco-santos How is it possible to reach out to you?

There is a limitation to automating the generation of typings right now.

Right now it's difficult to generate automatically correct typings for default exports. i.e. modules with the following

module.exports = function(){}

or

exports default function() {}

It requires manually adding the type details to types.d.ts to make it work

Although automatically generating types for named exports works perfectly i.e.

exports.create = function(){}
or
module.exports = {}

You can see an example here in the PR to js-libp2p-bootstrap
https://github.com/libp2p/js-libp2p-bootstrap/blob/f46c06fa2edfc95e00e738ee11fac0e3104682db/src/types.d.ts#L34

[alxroyer]

I bet it could be worth fixing / augmenting tsd-jsdoc in order to bring the minimum of constraints on the libp2p code:

• Make it generate stable output whatever the version of jsdoc (*)
• Add missing features (**)

I'm giving a try on that.

---

(*) tsd-jsdoc comes with jsdoc@3.5.5 by default (and I assume it has been developed with this former version of jsdoc).
However, as pointed by jsdoc#1672, jsdoc's behaviour has changed a bit since version 3.6.x, which leads to different behaviours for third party tools, such as tsd-jsdoc.
Indeed, as far as I have tested, tsd-jsdoc's output does differ depending on the version of jsdoc being used.

(**) Such as default exports.

[vasco-santos]

@samparsky let's discuss that on libp2p/js-libp2p#208, can you post that there? We can also involve jacob on it

[philipstanislaus]

@samparsky I looked into this, but it seems I won't have the capacity to make significant contributions in the next 2 weeks – deadlines, you know ;)

Let me know if I can be of any other help. Thanks!

[alxroyer]

I have just found out the jsdoc-tsd library, similar to (and visibly inspired from) tsd-jsdoc.

I've made a couple of tests with both, but I could not figure out whether one was better than the other.
I could not manage, among others, to generate automatically a default export declaration.

I keep on trying to fix tsd-jsdoc for the moment.

[samparsky]

@Alexis-ROYER Cool! keep me posted if you are able to fix it

[samparsky]

@Alexis-ROYER I have created an issue on jsdoc-tsd repo, currently looking at ways of solving it
otris/jsdoc-tsd#73

[alxroyer]

I've got a very first 'export default' declaration with tsd-jsdoc! The code is still ugly, but it's on the way.

I clean it a bit, then I start a draft PR out of your tsd-jsdoc#96 issue.

[alxroyer]

Draft PR#98 initialized on tsd-jsdoc for default exports.
Plus issue#99 for jsdoc 3.6.x support, and issue#100 for documented items vs exported items generation strategy.

Feel free to react on these.

[alxroyer]

Still work to do on the tsd-jsdoc#98 PR, but I have now reached a state that could be worth testing on real code.

Checkout from my tsd-jsdoc fork and run tsd-jsdoc from it, using the generationStrategy option set to 'exported'.

As I said before, work is still going on on that PR, but it should support by now:

• default exports:
  • export default keywords
  • module.exports = pattern
• named exports:
  • export keyword set before a type
  • module.exports.name = and exports.name = patterns
  • module.exports = { ... } pattern

I think it should work with jsdoc@3.6.3, but I've not tested it explicitely yet. If not, please get back to jsdoc@3.5.5 for the moment.

Refer to the ongoing exports test for details on what is supported or not.

[IwraStudios]

Hi all, it's been a while since I did libp2p/js-libp2p#346

I didn't realize there was a need for, so didn't bother to update it, but I did continue to create them for the modules I used.

Anyway I've got declaration files for around 60% of js-libp2p-*

Some interfaces might be old, because I created them a few months after initially posting them.

Also for the people tackling this, while most of the jsdoc is a good reference some of them are also not accurate (PeerInfo vs string was a common one iirc)

I'll post the files I have later today.

EDIT: there were a lot less changes than expected so I've just modified the original gist https://gist.github.com/IwraStudios/eecd07e060cf49145a974ec160c775ec

[mcclure]

Trying to make sure I'm up to date, is this correct?

• https://github.com/polkadot-js/ts/tree/master/types is still the most up to date js-libp2p typings and the best starting point for more
• However this predates the await/async refactor so many things will be wrong

If I want some sort of approximate types should I start with the polkadot-js project or @Alexis-ROYER 's thing?

[alxroyer]

@mcclure I bet we'd better forget the jsdoc approach. After giving it a try, I eventually came to the conclusion that it will be easier to write the .d.ts files and maintain them directly.

Let us know.

[gbaranski]

Hi, are you still interested in funding this feature? I'm currently working on it at DefinitelyTyped, but will move those type definitions to the js-ipfs in a moment.

@raulk

[vasco-santos]

FYI
In js-libp2p/IPFS we are currently working towards having type definitions on release. These type definitions are inferred by JSDOC typedef and some typescript files for completeness. Some context in ipfs/js-ipfs#2945 libp2p/js-libp2p#659

The libp2p work has already started and we aim to ship soon 0.30 with the core API with type definitions