Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
raulk opened this issue Aug 18, 2019 · 27 comments

Comments

@raulk
Copy link

commented Aug 18, 2019

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:

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

This comment has been minimized.

Copy link

commented Aug 18, 2019

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

This comment has been minimized.

Copy link
Author

commented Aug 22, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 24, 2019

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

@raulk

This comment has been minimized.

Copy link
Author

commented Aug 24, 2019

@samparsky I didn鈥檛 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 馃憤

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Aug 25, 2019

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

This comment has been minimized.

Copy link

commented Aug 25, 2019

@Alexis-ROYER Are you at ETHBerlin?

@samparsky

This comment has been minimized.

Copy link

commented Aug 25, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 25, 2019

@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

This comment has been minimized.

Copy link

commented Aug 25, 2019

@samparsky are you going to finish these? Otherwise I鈥檒l have a shot later. Thanks!

@samparsky

This comment has been minimized.

Copy link

commented Aug 25, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 25, 2019

@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

This comment has been minimized.

Copy link

commented Aug 25, 2019

@samparsky

This comment has been minimized.

Copy link

commented Aug 25, 2019

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

@philipstanislaus

This comment has been minimized.

Copy link

commented Aug 25, 2019

@samparsky sure, let鈥檚 do that. I鈥檒l get back to you in a bit.

@vasco-santos

This comment has been minimized.

Copy link

commented Aug 25, 2019

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

@ryanchristo

This comment has been minimized.

Copy link

commented Aug 26, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 27, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 27, 2019

@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

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Aug 28, 2019

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

This comment has been minimized.

Copy link

commented Aug 28, 2019

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

@philipstanislaus

This comment has been minimized.

Copy link

commented Aug 28, 2019

@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!

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Aug 28, 2019

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

This comment has been minimized.

Copy link

commented Aug 29, 2019

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

@samparsky

This comment has been minimized.

Copy link

commented Aug 30, 2019

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

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Aug 30, 2019

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.

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Sep 2, 2019

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.

@Alexis-ROYER

This comment has been minimized.

Copy link

commented Sep 20, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can鈥檛 perform that action at this time.