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’ll 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 · 32 comments

Comments

@raulk
Copy link

raulk 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
Copy link

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
Copy link
Author

raulk commented Aug 22, 2019

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

@samparsky
Copy link

samparsky 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
Copy link
Author

raulk commented Aug 24, 2019

@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
Copy link

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
Copy link

@Alexis-ROYER Are you at ETHBerlin?

@samparsky
Copy link

samparsky commented Aug 25, 2019

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

@samparsky
Copy link

samparsky 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
Copy link

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

@samparsky
Copy link

samparsky commented Aug 25, 2019

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

@samparsky
Copy link

samparsky 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
Copy link

philipstanislaus commented Aug 25, 2019 via email

@samparsky
Copy link

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

@philipstanislaus
Copy link

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

@vasco-santos
Copy link

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

@ryanchristo
Copy link

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

@samparsky
Copy link

samparsky 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
Copy link

samparsky 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

@alxroyer
Copy link

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 [email protected] 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
Copy link

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

@philipstanislaus
Copy link

@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
Copy link

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
Copy link

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

@samparsky
Copy link

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

@alxroyer
Copy link

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
Copy link

alxroyer 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.

@alxroyer
Copy link

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 [email protected], but I've not tested it explicitely yet. If not, please get back to [email protected] for the moment.

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

@IwraStudios
Copy link

IwraStudios commented Oct 23, 2019

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
Copy link

mcclure commented Mar 26, 2020

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
Copy link

@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
Copy link

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
Copy link

vasco-santos commented Dec 9, 2020

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

10 participants