Should we accept purposely incomplete lib defs of huge libraries?

[Brianzchen]

Problem

There are huge libraries in the JS ecosystem that are not flow-typed. Namely material-ui which many have asked for and firebase which I'm starting to get into now.

I'm slowly typing out my stub for firebase which works well but it's a huge effort for myself or anyone for that matter if the first submission of the type def had to be fully complete because I doubt I'll use all the features to be able to ensure it works for everyone.

I did previously add the definition for cypress, but even that was a huge effort that took me days/weeks but I had the motivation because someone else had previously attempted a PR I could base the definitions off. I don't use all the functions from cypress so I couldn't validate that they're all accurate but from the previous attempt I was confident enough to make a submission.

Not having things like material-ui I think really hurts the flow community's growth because although the avid flow users don't use material-ui since I personally see it as a more hobbyist library, a lot of new comers would come from that and would find the ecosystem not worth it without their most depended on library typed in comparison to TS.

Proposal

What I'm wondering is if the general community here would accept a partially typed definition, so that something can at least be started even if it doesn't work for everyone initially. If not the case, I doubt I would ever feel confident enough to submit my stub back to the community.

Of course whatever submitted would include thorough testing against the lib def of what's there so that quality is kept, just that complete definitions won't be there.

I would also note that I my thoughts are that incomplete objects are typed as {| |} instead of { ... } and more object properties are simply added over time.

---

What's your thoughts? Tagging some active contributors to get the conversation going
@pascalduez @AndrewSouthpaw @villesau @gantoine @jedwards1211 @Ashoat @atabel

[gantoine]

I need to mull this over a little, but my gut instinct says that incomplete libdefs are better then no libdefs, as long as the untyped sections are stubbed, so they don't throw errors when running flow.

[pascalduez]

Like you said, as long as the added types are properly tested, and maybe a few comments added at the top of the libdef, it's all fine. We already accepted several partial libdefs.
I also have the same issues, I locally have (I can't count how much) started branches which stalled because it quickly became overwhelming.

[jedwards1211]

For me at least, writing type tests is the biggest time suck when making large libdefs.

It definitely seems like automated conversion should be used for converting large parts of Material-UI's TS defs to Flow. It's been awhile since I tried out some of the converters out there, but I can't tell if any support TS & (though A & B should be converted to {| ...$Exact<A>, ...$Exact<B> |} in the case of object types, I avoid object intersections like the plague in Flow now). I have a lot of experience with AST transformation though, soiIt's something I'd be interested in helping with when I can find the time, plus I use Flow and Material UI.

[pascalduez]

For me at least, writing type tests is the biggest time suck when making large libdefs.

Yes, we should probably be flexible here, for large libdefs, maybe only the major APIs could be sufficient.

It's been awhile since I tried out some of the converters out there

Last time I tried to use the --typescript flag from our CLI, I couldn't make it work... :\

[AndrewSouthpaw]

I'm generally in the camp of "something is better than nothing". Ramda was this way too. It can be frustrating because you expect libdefs to be typesafe out of the gate, but that needs to be balanced with the reality that we have limited bandwidth to create/maintain new libdefs.

[villesau]

I think incomplete typedefs are also better than nothing. But it could be good to communicate it somehow and have guidelines for people to follow: Let's say you have following type: () => NotReallyTypedType. Should it return mixed or any? any for ease of use, mixed for soundess. Flow advocates for soundness, but returning mixed is a huge pain in the ass. I'd go with any, or if we know it's an object, some object type etc.

Guidelines would help people revieweing to review incomplete libdefs as well as implementing partial libdefs.

[Brianzchen]

To close this off. Probably just need to add some docs to bless this standard