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.

Sign up for GitHub

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

Proposal: TypeScript Definitions for core libraries #79

Merged
merged 6 commits into from
Jun 9, 2021
Merged

Proposal: TypeScript Definitions for core libraries #79

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3330e49
add typescript proposal
rvagg Mar 15, 2021
fa1cb42
Update proposals/79-typescript-definitions.md
rvagg Mar 16, 2021
6624cfa
Update proposals/79-typescript-definitions.md
rvagg Mar 16, 2021
f0bc4c5
Update 79-typescript-definitions.md
rvagg Mar 16, 2021
f1e6f2e
tighten scope
rvagg Mar 22, 2021
9c2e6e9
notes for: IPLD, impact, success metric
rvagg Mar 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions proposals/79-typescript-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# TypeScript Definitions for core libraries

Authors: @rvagg

Initial PR: https://github.com/protocol/web3-dev-team/pull/79

## Purpose & impact

Consumers of our JavaScript libraries & components should have sufficient TypeScript definitions, available through standard means, to write fully typed TypeScript code, or use that code to drive tooling that consumes these definitions - such as VS Code editing enhancements, documentation production pipelines, type checking tooling for test & CI pipelines.

This work is high-value and high-impact for the JavaScript ecosystem and those of us working on open source JavaScript libraries can all provide anecdotal evidence for the frequency with which developers request better TypeScript annotations for our libraries. The rate of TypeScript adoption, particularly within larger-scale projects, is increasing, but TypeScript definitions are increasingly useful as they are included in general JavaScript linting, checking and documentation tooling.

This work provides high-leverage within our suite of JavaScript tools as we mature, refactor, modularize and create. We are already establishing a suite of practices and tooling that are used in varying ways across PL JavaScript projects that use definitions, even though we have very few TypeScript projects throughout our GitHub orgs (<https://github.com/ipfs/js-dag-service> being a rare example, which was initially contributed by Textile). It is reasonable to expect that the majority of new JavaScript code produced by Protocol Labs into the future will make use of TypeScript annotations in some way.

Work on this effort has been largely completed, thanks primarily to @hugomrdias, @Gozala, and @achingbrain with assistance from the entire JavaScript team in various ways. The bulk of the activity has been tracked as a roll-up in to js-ipfs @ <https://github.com/ipfs/js-ipfs/issues/2945>.

Remaining work to integrate the current set of js-ipfs dependencies into js-ipfs and address the typing for code directly in js-ipfs is happening here: https://github.com/ipfs/js-ipfs/pull/3550

Aside from completing the remaining js-ipfs itegration work, the scope of this project includes some additional libraries that re not currently part of the js-ipfs dependency tree, including:
rvagg marked this conversation as resolved.
Show resolved Hide resolved

* Next-generation IPLD codec libraries (using the js-multiformats pattern)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this include multiaddr update? multiformats/js-multiaddr#159

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it probably should be, but I don't have a feel for how much work it is to get that over the line. Do you?

Copy link
Contributor

@vasco-santos vasco-santos Mar 16, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

maybe @hugomrdias has an idea on the current state. More than having that merged, this will require changes across the stack as this will change how multiaddrs are created

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That PR should be made non-breaking just to get it finished, i tried a week ago or something but its troublesome. Need to look at it again.

* _TODO: what other non-archived, non-dormant project should we include here to achieve the above value & impact ideals?_
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tooling is mentioned above, but we should clarify what we aim to land as part of this. Quite a bit of work has gone into Aegir for type generation, what's the short term milestone/feature set we're targeting for that? Is it already done?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm interested in input on this, maybe from @hugomrdias or @achingbrain? The aim is something like "get it done properly" but also "not too large in scope that it goes beyond a S/M project". So I don't want to blow this out with tooling investment.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regarding types aegir is pretty much done.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Theirs another angle regarding types, which is documentation. Aegir uses typedoc and it does a pretty good job at taking our types and generating documentation.
But because our code base is still commonjs there is still some minor issues. To overcome these issues i normally need to either change the current commonjs exports to something more friendly or file issues in Typedoc to support all the quirks about commonjs exports :)
This may be out of scope but still, up to date documentation is important!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hugomrdias 👍 my take is that the tooling is not mature enough for the annotated-JS case to do a consistently good job of it--it doesn't seem to be a priority on the typedoc end and doing it from the jsdoc end (as I've been trying to do) just doesn't work the more you lean in to TS (nobody seems to be interested in unifying the two). But this is certainly something we should take on in a near-future project, to build better and more consistent docs across our stack with tight integration with the TS annotations.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure where exactly to fit this and I believe it is out of scope for this specific proposal, but thought I'd still call this out here. We leverage TS a bit across message-port-client / server pieces to ensure that both ends comply with a wire protocol, I think it could be generalized a bit more to provide same value across more places where we hav client / server or other RPC model.

rvagg marked this conversation as resolved.
Show resolved Hide resolved

Project-specific decisions will be made regarding the depth of TypeScript definitional work. Projects with greater expected future usage should include full type checking in CI and will therefore require basic inline TypeScript annotations. Projects that are dependencies but are not expected to be actively maintained or developed further into the future may just include basic API type definitions so that dependents can make use of those.

<!--
#### Background &amp; intent
_Describe the desired state of the world after this project? Why does that matter?_
#### Assumptions &amp; hypotheses
_What must be true for this project to matter?_
#### User workflow example
_How would a developer or user use this new capability?_
#### Impact
_How would this directly contribute to web3 dev stack product-market fit?_
#### Leverage
_How much would nailing this project improve our knowledge and ability to execute future projects?_
#### Confidence
_How sure are we that this impact would be realized? Label from [this scale](https://medium.com/@nimay/inside-product-introduction-to-feature-priority-using-ice-impact-confidence-ease-and-gist-5180434e5b15)_.
## Project definition
#### Brief plan of attack
#### What does done look like?
_What specific deliverables should completed to consider this project done?_
#### What does success look like?
_Success means impact. How will we know we did the right thing?_
#### Counterpoints &amp; pre-mortem
_Why might this project be lower impact than expected? How could this project fail to complete, or fail to be successful?_
#### Alternatives
_How might this project’s intent be realized in other ways (other than this project proposal)? What other potential solutions can address the same need?_
#### Dependencies/prerequisites
#### Future opportunities
## Required resources
#### Effort estimate
#### Roles / skills needed
-->