Add alias docs for @babel/types

[JLHwung]

Q	A
License	MIT

This PR adds a new "Alias" section to the docs of @babel/types. It reflects my understanding of current aliases, feedbacks are welcome!

This PR includes commits from #13148, will rebase once that one is merged.

See here for rendered results.

[JLHwung]

I have no idea what is our intention for UserWhitespacable, it covers

ObjectMethod
ObjectProperty
ObjectTypeInternalSlot
ObjectTypeCallProperty
ObjectTypeIndexer
ObjectTypeProperty
ObjectTypeSpreadProperty

[hzoo]

b1fe449 based on this, it's probably something that used to be used in generator, we can probably just remove it honestly. Sounds like it wasn't intended to be used as a visitor at least but to check something for printing. It would be really odd if someone used it, we don't anywhere?

[JLHwung]

Thanks! I update description to "deprecated".

[babel-bot]

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

[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 e8ebe57:

Sandbox	Source
babel-repl-custom-plugin	Configuration
babel-plugin-multi-config	Configuration

[JLHwung]

Can we come up with a formal definition of Immutable? What is the difference between Pureish and Immutable?

[nicolo-ribaudo]

I think the original intention was

• Immutable -> You cannot define properties on it (+ JSX elements which behave as you can't otherwise you break JSX libraries)
• Pureish -> It doesn't have side effects

We will probably need to audit all these aliases before Babel 8.

[JLHwung]

Thanks! It looks like Immutable refers to https://tc39.es/ecma262/#immutable-prototype-exotic-object ?

[nicolo-ribaudo]

I think those are only for Flow

[JLHwung]

Based on the definition, I think it should also cover StaticBlock, which does define a new var scope. Note that in Babel 6 FunctionParent includes Program, but we removed Program in #5923 because the name FunctionParent strongly indicates that it should always be a Function, which is not the case for StaticBlock and Program.

Currently FunctionParent and Function are equivalent, they include exactly the same AST nodes.

BTW we have several usage of scope.getFunctionParent() || scope.getProgramParent(). This depends on the assumption that an AST tree can only have one Program node and all the function node must placed within that program node. This is not true for module-blocks proposal.

[nicolo-ribaudo]

In Babel 8 we might just rename them to LexicalScope and VariableScope, where VariableScope is a subset of LexicalScope.

This is not true for module-blocks proposal.

Can you show an example where scope.getFunctionParent() || scope.getProgramParent() would break with the module-blocks proposal? When I proposed to use Program for the ModuleExpression node it was exactly to support this existing pattern.

[JLHwung]

Ah I missed that module blocks can only be at the top level.

[nicolo-ribaudo]

No, they can also be nested, but we'll want to consider "the top level" the module block itself.

For example, if we have

let mod = module {
  class A {}
};

We want to get this:

let mod = module {
  function _classCallCheck() {}
  let A = function A() {
    _classCallCheck(this);
  };
};

and not this:

function _classCallCheck() {}
let mod = module {
  let A = function A() {
    _classCallCheck(this);
  };
};

[JLHwung]

Yeah, I just checked module blocks proposal and you are right they can be nested.

Can you show an example where scope.getFunctionParent() || scope.getProgramParent() would break with the module-blocks proposal

function f() {
  (module {
    var x;
  })
}

scope.getFunctionParent() || scope.getProgramParent() on var x will return function f instead of the module block.

[nicolo-ribaudo]

Oh right, thanks

[nicolo-ribaudo]

This description isn't true for await and throw, but I don't know what a better description would be 🤷

[JLHwung]

I can't find the usage in our codebase. The term terminatorless is referenced in

babel/packages/babel-generator/src/printer.ts

Lines 332 to 348 in d24bd7c

	/**
	* Set some state that will be modified if a newline has been inserted before any
	* non-space characters.
	*
	* This is to prevent breaking semantics for terminatorless separator nodes. eg:
	*
	* return foo;
	*
	* returns `foo`. But if we do:
	*
	* return
	* foo;
	*
	* `undefined` will be returned and not `foo` due to the terminator.
	*/
	startTerminatorless(isLabel: boolean = false): any {

Based on that I don't think ThrowStatement and AwaitExpression should belong to TerminatorLess, we can also consider just remove it.

[JLHwung]

Currently ExpressionWrapper includes

ExpressionStatement
ParenthesizedExpression
TypeCastExpression

We have a very similar helper for the same purpose:

babel/packages/babel-helper-skip-transparent-expression-wrappers/src/index.js

Lines 11 to 19 in d24bd7c

	export function isTransparentExprWrapper(node: Node) {
	return (
	t.isTSAsExpression(node) ||
	t.isTSTypeAssertion(node) ||
	t.isTSNonNullExpression(node) ||
	t.isTypeCastExpression(node) ||
	t.isParenthesizedExpression(node)
	);
	}

this helper is used in optional chaining to stick chains separated by such transparent wrappers. Since an ExpressionStatement can not be nested inside expression, I think it is safe to merge these two, in other words we can consider to extend ExpressionWrapper to cover TSNonNullExpression, TSAsExpression and TSTypeAssertion.

[nicolo-ribaudo]

We can either merge them, or just delete ExpressionWrapper and replace it with TransparentExpressionWrapper (which has the property that they don't modify the this context for call),

[JLHwung]

Block is not used by our codes. I am not sure about its intention.

[nicolo-ribaudo]

Let's just remove it in Babel 8

[JLHwung]

Merging as-is since it is a docs generator script and not published to npm.