[RFC] Core defintions

[Brianzchen]

RFC style inspired by reactjs

Summary

Create a place to store and pull core definitions for different javascript environments not supported by flow itself.

Basic example

In /definitions/core/es5.js

declare var NaN: number;
declare var Infinity: number;
declare var undefined: void;
// ...

In a project after having an env value setup

flow-typed install 

Which adds to the directory

/flow-typed/core/es5.js

Motivation

Use case from #3755. Requirement to support a unique browser that has different global specs to what is in flow's lib which causes functions to not throw errors on misuse until runtime.

A change of some kind would need to be made for how core.es5 is currently stored so that validate-def command works as intended. See #4249

Detailed design

As a sibling to definitions/npm we have definitions/core which hold module definitions for environments.

// Example
- definitions
  - npm
    - ...
  - core
    - es5
      - flow_v0.83.x-
        - es5.js
        - test_es5.js
    - node
      - flow_v0.23.x-v0.82.x
        - node.js
        - test_node.js
      - flow_v0.83.x-
        - node.js
        - test_node.js

Unlike npm definitions, these will not have versions associated as they are not tied to any releases or published library, any changes to the environment should continue to improve an already existing definition. But just like npm definitions they will have flow versions support and tests to ensure their existing API's aren't broken.

Users can then install this which will add the definitions into their project.

---

It starts to highlight a question of whether node vs browser definitions could be managed here instead of flow itself, decoupling definition improvements to the version it was added to in flow. Also flow as of today only had one mode and loads both node and browser definitions which for the most part works seamlessly but can be a headache when dealing with functions that exist in both modes though have very different api's.

But core definitions could become the ideal place to house global definitions, not part of a library that require reuse not based on libraries but users of flow. Such as a jsx core definitions could hold all possible props for html elements and more specific elements as global types which can then be used by projects.

type Props = {
  ...jsx$inputProps,
  fooFunc: () => {},
};

const MyInput = ({ ... }: Props) => {
  // ...
};

How to install

This can be handled in a few ways though I learn on 4. as the solution to implement

1. If we can work closely with flow team they could support an env property which accepts an array of values that we could use to figure out which core libs the user needs installed.
2. Same as above except that flow themselves would use the env value to pull definitions based on flow version from flow-typed and load it into the users flow instance. By default this could load browser + node.
3. If user wants to use a custom flow-typed env definition they need to run some special command like flow-typed install @flow-typed/core or something similar though less preferred as we generally have flow-typed install which should automatically update definitions with any improvements.
4. Could we have our own config file that could specify env and include settings such as ignore deps and in the future even a proxy registry location.

Drawbacks

I don't see any drawbacks necessarily but I do question if this is the right move for the future of how flow is used. The requirement outlined in the Motivation is a special case and the range of cases maybe be limited.

If we were to adopt a solution that interacts with the flow team we can't be as autonomous and that may hinder us if flow team isn't as active as we are. Is this even useful for Meta or should we aim for a solution that allows us to be as autonomous as possible

Alternatives

1. We could remove core.es5 as it isn't compatible with the rest of the system though this breaks the contributor (@RohanHart) who added this in the beginning
2. Do nothing works but validate defs will never function properly

Adoption strategy

Users install it as needed, no impact to users who don't need special configs

How we teach this

Updating the readme and docs should be enough.

Unresolved questions

[RohanHart]

I'm no longer involved with the project that created core.es5 but at worst they could use a local libdef instead.

[Brianzchen]

Thanks for letting me know! It's an interesting problem you've created nonetheless

[Brianzchen]

@RohanHart do you have any contact I could get in touch with that's still part of this project? I was hoping I could get their input on this usage because I'm finding some errors with the definition that conflicts with builtin defs

[Brianzchen]

Just did some further testing, turns out the def is compatible until 0.142.x, though if possible might be nice for them to know about this future migration.

[RohanHart]

Sorry, I've no contacts for you @Brianzchen

[AndrewSouthpaw]

Seems good to me. I agree that #4 looks like the best option.

If we were to adopt a solution that interacts with the flow team we can't be as autonomous and that may hinder us if flow team isn't as active as we are.

Definitely agree with this part. We've had variable success coordinating with the flow team, they have a lot on their plate, so if we can find a solution that is independent that seems idea.

I'm a 👍🏼 on this approach.

[gantoine]

Agreed with the general sentiment. It would be nice to reach out to the Flow team and see if they have any thoughts, and are interested in sharing it with us. Best case they have some opinions they want to share, worst case we move forward with this proposal anyways. @Brianzchen