Babel/types/fix/export flow types

[kayhadrin]

Q	A
Fixed Issues?	This could help #8739
Patch: Bug Fix?	Bug fix
Major: Breaking Change?	No, but improved types could reveal new Flow errors
Minor: New Feature?
Tests Added + Pass?	Tests OK;
Documentation PR Link
Any Dependency Changes?	No
License	MIT

To properly import @babel/types types in a Flow+JS project, we need to fix a few things:

1. Declare that the @babel/types module exports a default value; otherwise, we'll get a Flow error that sounds like "cannot import a default export because there is no default export"
2. Explicitly export each function and type of the @babel/types module
3. Fix existing Flow typing errors. E.g. Node -> BabelNode
4. Add the @flow pragma in the file header. It's not mandatory, but it helps in some scenarios when we want to import the index.js.flow file directly.

Generated output example: https://gist.github.com/kayhadrin/dfe0f9785622a1dfaf726cba0001b993

[babel-bot]

Build successful! You can test your changes in the REPL here: https://babeljs.io/repl/build/24996/

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit b153d07:

Sandbox	Source
hungry-brook-bfnxb	Configuration
eager-brook-dip73	Configuration

[nicolo-ribaudo]

Declare that the @babel/types module exports a default value; otherwise, we'll get a Flow error that sounds like "cannot import a default export because there is no default export"

That error seems correct, since @babel/types doesn't have a default export. You should use it as import * as t from "@babel/types".

[kayhadrin]

@nicolo-ribaudo

That error seems correct, since @babel/types doesn't have a default export. You should use it as import * as t from "@babel/types".

Your recommendation is in plain JS and suggests to import all the exported JS values of a module, but I'm trying to import the exported default type of a JS module as a Flow type.

In Flow, that's done like this: import typeof MyModuleType from 'MyModule'
and that's when the Flow error mentioned earlier is outputted: "cannot import a default export because there is no default export".

Hence why I needed to do some of the changes in this PR.
Beside that, there are several other Flow typing errors that were fixed too.

[kayhadrin]

🏓

[nicolo-ribaudo]

?

import typeof * as t from "@babel/types"

[kayhadrin]

I tried import typeof * as BabelTypes from "@babel/types".
It seems like a good idea but this produces new Flow errors that don't normally appear when using import typeof BabelTypes from '@babel/types'.

E.g. from fbt project: facebook/fbt#150

$ /oss-fbt/__github__/node_modules/.bin/flow check --show-all-errors
Error -------------------------------------------------------------------- flow-types/nonfb/libdef/babelTypes.js:1806:18

boolean [1] is not supported by unclassified use SubstOnPredT.

   flow-types/nonfb/libdef/babelTypes.js:1806:18
   1806|   declare export function isArrayExpression(node: ?Object, opts?: ?Object): boolean %checks (node instanceof BabelNodeArrayExpression)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

References:
   flow-types/nonfb/libdef/babelTypes.js:1806:94
   1806|   declare export function isArrayExpression(node: ?Object, opts?: ?Object): boolean %checks (node instanceof BabelNodeArrayExpression)
                                                                                                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [1]


Error -------------------------------------------------------------------- flow-types/nonfb/libdef/babelTypes.js:1807:18

boolean [1] is not supported by unclassified use SubstOnPredT.

   flow-types/nonfb/libdef/babelTypes.js:1807:18
   1807|   declare export function isAssignmentExpression(node: ?Object, opts?: ?Object): boolean %checks (node instanceof BabelNodeAssignmentExpression)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

References:
   flow-types/nonfb/libdef/babelTypes.js:1807:99
   1807|   declare export function isAssignmentExpression(node: ?Object, opts?: ?Object): boolean %checks (node instanceof BabelNodeAssignmentExpression)
                                                                                                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ [1]

...

Found 238 errors
error Command failed with exit code 2.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

There seem to be a problem using %checks(...) in that particular scenario. :-(

I've asked the Flow team for help; in the meantime, do you reckon the current solution in this PR is good enough for now?

[kayhadrin]

Ping @nicolo-ribaudo

The Flow team will fix the type issue mentioned above.
If we care about backward compatibility, we could add the declare export default {...} block; otherwise, people could use import typeof * as ... only if they update their Flow engine too.

What do you think about the rest of this PR?

[kayhadrin]

🏓

[JLHwung]

@kayhadrin Can you rebase on main?

[kayhadrin]

@kayhadrin Can you rebase on main?

Done.
But note that I found some lint errors due to someone else's changes after rebasing on master.

####
# make test
####
...
error: Delete `·` (prettier/prettier) at babel.config.js:3:26:
  1 | "use strict";
  2 | 
> 3 | module.exports = function (api) {
    |                          ^
  4 |   const env = api.env();
  5 | 
  6 |   const includeCoverage = process.env.BABEL_COVERAGE === "true";

[JLHwung]

@kayhadrin Please run make bootstrap after your rebased. It is due to prettier was updated recently but the one in your n_m is not sync with package locks.

[kayhadrin]

Ok, rebased again on the main branch and rerun tests:

 PASS  packages/babel-types/test/misc.js
 PASS  packages/babel-types/test/builders/flow/declareClass.js
 PASS  packages/babel-types/test/cloning.js
 PASS  packages/babel-types/test/retrievers.js
 PASS  packages/babel-types/test/builders/flow/createTypeAnnotationBasedOnTypeof.js
 PASS  packages/babel-types/test/builders/es2015/templateElement.js
 PASS  packages/babel-types/test/builders/typescript/tsTypeParameter.js
 PASS  packages/babel-types/test/validators.js
 PASS  packages/babel-types/test/builders/experimental/classProperty.js
 PASS  packages/babel-types/test/regressions.js
 PASS  packages/babel-types/test/converters.js
 PASS  packages/babel-types/test/asserts.js

Test Suites: 12 passed, 12 total
Tests:       412 passed, 412 total
Snapshots:   21 passed, 21 total
Time:        5.063s
Ran all test suites matching /(packages|codemods|eslint)\/.*babel-types.*\/test/i.

[kayhadrin]

@JLHwung 🏓

[JLHwung]

Thanks.

(sorry, I didn't mean to approve yet)

[nicolo-ribaudo]

Just to understand, the declare export default {} bit is needed for backward compatibility, because it used to work with previous Babel versions? If so, I would love for a pr targeting the next-8-dev branch (after that this PR is merged to main and to next-8-dev) to remove it.

[kayhadrin]

Just to understand, the declare export default {} bit is needed for backward compatibility, because it used to work with previous Babel versions?

Yes, it used to work but some other Flow type changes caused it to break (e.g. the addition of Node type references). Also, the usage of the ES6 export pattern instead of CommonJS also exposed a bug in the Flow engine, that was recently patched in 0.128.0 (see facebook/flow@d326475)

If so, I would love for a pr targeting the next-8-dev branch (after that this PR is merged to main and to next-8-dev) to remove it.

TBH, unless we're prepared to patch older Babel releases, I think I could already remove the declare export default {} part.
Instead, we should consider adding a few explanations in the README to show people how to import types from this file.
E.g. How to use import typeof * as BabelTypes from "@babel/types" since it was new to me before I submitted this PR.

[kayhadrin]

@nicolo-ribaudo What would you like me to do then?
I'm a bit confused for now.

[liuxingbaoyu]

Thank you for your PR! Since it is now obsolete, I will close it.