search

ethberlinzwei / Bounties

Get rewards for your contributions
10 stars 10 forks source link

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

Open raulk opened 5 years ago

raulk commented 5 years ago

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: https://github.com/libp2p/devgrants/issues/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:

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 commented 5 years ago

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 commented 5 years ago

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

samparsky commented 5 years ago

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

raulk commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

@Alexis-ROYER Are you at ETHBerlin?

samparsky commented 5 years ago

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

samparsky commented 5 years ago

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

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

https://github.com/libp2p/js-libp2p-bootstrap/pull/95

And a draft PR to the js-libp2p repository

https://github.com/libp2p/js-libp2p/pull/449

philipstanislaus commented 5 years ago

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

samparsky commented 5 years ago

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

samparsky commented 5 years ago

@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 https://github.com/libp2p/js-libp2p-bootstrap/pull/95 to have an idea

We can split it up if you are interested

philipstanislaus commented 5 years ago

Got it, looking forward to use them!

Thanks!

samparsky commented 5 years ago

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

philipstanislaus commented 5 years ago

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

vasco-santos commented 5 years ago

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

ryanchristo commented 5 years ago

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

samparsky commented 5 years ago

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

samparsky commented 5 years ago

@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 commented 5 years ago

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

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 commented 5 years ago

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

philipstanislaus commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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

samparsky commented 5 years ago

@Alexis-ROYER I have created an issue on jsdoc-tsd repo, currently looking at ways of solving it https://github.com/otris/jsdoc-tsd/issues/73

alxroyer commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

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:

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 commented 5 years ago

Hi all, it's been a while since I did https://github.com/libp2p/js-libp2p/issues/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 commented 4 years ago

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

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

alxroyer commented 4 years ago

@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 commented 3 years ago

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 commented 3 years ago

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 https://github.com/ipfs/js-ipfs/issues/2945 https://github.com/libp2p/js-libp2p/issues/659

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