TypeScript Support

[devinivy]

Background

There have been recurring questions about whether pal will offer official TypeScript support. Some are interested because they develop in TS, and others simply for a nice experience in their IDE while using pal. Most pal module lead maintainers aren't interested in taking on the burden of maintaining typings in additional to the maintenance and feature work that they already do. At the same time, I see benefits to managing typings and organizing the project of writing typings ourselves rather than deferring the community effort to DefinitelyTyped.

Proposal

I have some ideas about how to organize the community here around TypeScript. It requires some vetting from folks with more experience with the TS ecosystem, though. I would like to manage types under the organization (not crowd-sourced to @types), but not maintained by each module's maintainers, even though I recognize that ideally (from a technical standpoint) types for a module are maintained within its codebase. We're working with other constraints that involve people, though, so it's as much a technical concern as it is an organizational concern. With that said...

I propose we find two lead maintainers (are you interested? let us know here!) of TypeScript typings across the pal ecosystem. We would manage these typings in a monorepo (hapipal/types), and publish independent type modules for each pal module, starting with toys, confidence, schmervice, schwifty, and haute-couture. Individual pal modules would declare their type modules as a direct dependency (I've done some research, but I need some help fleshing out the details here). While the types would be considered a part of the public API of the module, it would not be a responsibility of the maintainer of each module to keep the typings up to date: instead each PR with a change to the module's API would involve opening an issue in hapipal/types for the update to possibly (but not always) occur out-of-sync with the change to the module itself. It would be the responsibility of the maintainers of hapipal/types to land typing contributions.

Conclusion

This is a somewhat early version of this idea. Totally open to feedback, concerns, and additional thoughts/approaches. Big questions are:

• Do we generally like this approach?
• Does anyone know the specifics as to how to configure a module to point to external typings that are not published to @types?
• Are lead maintainers down with this?
• Are you interested in taking on a maintainership role for pal typings?

[devinivy]

I am seeing some general support here per the 👍s on message above which is great! If you are interested in participating as a co-maintainer of typings then please let us know here, as I think that is the main issue in the balance right now.

[sfabriece]

I'm not maintaining any hapi related libraries but having worked with typescript, I would be interested in co-maintaining the typings @devinivy

[devinivy]

@sfabriece that is great news, thank you for stepping-up and offering. Let's will remain on the lookout for another co-maintainer, and if we find one then we can start kicking things off. If you have any further thoughts about how to approach this, of course your expertise is welcome! If you'd like to chat more about your thoughts in realtime, feel free to broach the topic in #hapipal on the hapi hour slack.

[ggallovalle]

Hello, I would love to help. I think I might start tomorrow with Toys. I haven't seen yet if you have guys have a CONTRIBUTIOM.md, I'll check it later.

[devinivy]

@ggallovalle are you interested in being a co-maintainer of types? If so I will create the hapipal/types repository and you two and @sfabriece could get started together. The contribution in hapipal/toys#19 looked like a great start. Perhaps applying the plan/technique described in this issue to toys would be a nice proof of concept. If you two are both on board, I could get you setup with write access to a new types repository very soon 👍

[ggallovalle]

Yes I am. The only thing that to me it feels a little bit counter intuitive the fact that you need another another repo/package to get the types for the whole ecosystem. It's more common that either the package has a types property in the package.json or your get it from @types

I'm also interested in make Happy couture to work with Typescript, but that's another discussion.

[damusix]

@devinivy I'd be glad to lend a hand on virtually any hapi pal plugin. Pretty sure I use all of them. To @ggallovalle 's point, because it is a library, it might make sense to rewrite things in typescript at some point due to the amount of tooling that surrounds it. Recently had a terrible experience using pulumi docs (pulumi is amazing btw) where they don't exactly represent what's in the lib. Typings saved the day 100%. I can assist with this as well.

[devinivy]

We wont be rewriting things in typescript any time soon, as nothing has changed since the problem statement in the original post. But each pal module depending on a package of external type definitions is definitely fair game! The upside over @types/* is that users will not have to install extra packages in their package.json to access the typings. And at the time time pal module maintainers also don't have to accept the burden of maintaining typings.

I think one way this could work is to publish typings as independent modules, but maintained under a monorepo hapipal/types. Then each module (e.g. @hapipal/schwifty) would depend on its type definition module (e.g. @hapipal/types-schwifty) and contain an index.d.ts that re-exports those typings. Typescript aficionados— does that seem like it would work to you?

@sfabriece and @damusix: if I create a repository at hapipal/types, would you two be open to turning it into such a monorepo and creating a proof of concept? @ggallovalle if that is something that happens, would you still be interested in contributing some initial typings? Feel free to start a group message in the hapi hour Slack if it would be easier to talk about this together there. If there are any updates from Slack I will post them here.

Also keep in mind— contributing to DefinitelyTyped right now is still fruitful! The typings are immediately useful to other users, and we can always pull them into hapipal/types in the future if we go that direction.

[damusix]

@devinivy That makes sense to me yeah. I'm game.

[damusix]

Any updates on this? I just remembered after making an issue on schwifty.

[devinivy]

I just put together a proof of concept. If folks are down with the approach, I am ready to hand the keys over to some people interested in taking next steps! Here's the repo: https://github.com/devinivy/hapipal-types-poc

The way it's structured there are three modules:

1. a project using a fictional hapipal package named @hapipal/boing.
2. the package @hapipal/boing.
3. the types package for the boing module @hapipaltypes/boing.

Here is where the project makes use of the boing module:
https://github.com/devinivy/hapipal-types-poc/blob/c0cc0f79297c4939bd1a5f909ca64b4aecb5855d/index.js#L5

Here are the boing module's types:
https://github.com/devinivy/hapipal-types-poc/blob/c0cc0f79297c4939bd1a5f909ca64b4aecb5855d/node_modules/%40hapipaltypes/boing/index.d.ts#L1

And here is how the boing module uses its external types package:
https://github.com/devinivy/hapipal-types-poc/blob/56fb2ab5308255c04035b57a887881a4d2649c1b/node_modules/%40hapipal/boing/package.json#L11-L14
https://github.com/devinivy/hapipal-types-poc/blob/c0cc0f79297c4939bd1a5f909ca64b4aecb5855d/node_modules/%40hapipal/boing/index.d.ts#L1

Does anyone see issues with this approach? I tested it out and it does seem to work just fine, but I am also not as fluent with TS as many others in the community. One of the main upsides for users is that they will no longer have to add the @types/hapipal__* packages to their dependencies.

If that sounds good, I will create a types repository setup as a monorepo with npm workspaces, and some folks can start by porting one module's types into there, then adding the two-line boilerplate to the module itself as a more in-depth proof of concept. My apologies that this has taken so long to act on! @ggallovalle @damusix @sfabriece are any of you are still interested in taking the next steps to bring hapipal-managed types to the ecosystem I will ensure you have the proper permissions to do so 👍 Thanks, yall!

P.S. also wanted to tag in @timcosta for feedback since he did contribute to some TS support of hapi pal tooling in the past.

[damusix]

yep

[devinivy]

Great, I am getting it all setup. While I'm setting up access controls, anyone else interested in helping maintain types for hapi pal?

[ianjkaplan]

I work with @damusix and am interested as well

[devinivy]

Awesome, I've setup a monorepo based on npm workspaces at https://github.com/hapipal/types with the toys types and tests from DefinitelyTyped. I have a basic Travis CI setup running on there too. Just to reference it again, here's the proof of concept that I got working for how I imagined this might work: https://github.com/devinivy/hapipal-types-poc (and more details on that above).

You both have write access, my only request is that we develop in the open (e.g. using github issues, PRs, the hapipal slack, etc.) whenever possible :). Let me know when you'd like to do some beta publishing to npm and I'll get access for that setup! Thanks so much for volunteering. If others want to hop in, I expect there's probably still plenty of room to help with typings, but I defer to @damusix and @ikaplan20 advise on that and lead the way! 🥂