Add alias docs for @babel/types by JLHwung · Pull Request #13151 · babel/babel

JLHwung · 2021-04-14T15:55:05Z

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 · 2021-04-14T15:57:35Z

+  Terminatorless:
+    "A cover of AST nodes whose semantic will change when a line terminator is inserted between the operator and the operand.",
+  UnaryLike: "A cover of UnaryExpression and SpreadElement.",
+  UserWhitespacable: "",


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

ObjectMethod ObjectProperty ObjectTypeInternalSlot ObjectTypeCallProperty ObjectTypeIndexer ObjectTypeProperty ObjectTypeSpreadProperty

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?

Thanks! I update description to "deprecated".

babel-bot · 2021-04-14T15:57:42Z

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

codesandbox-ci · 2021-04-14T16:02:53Z

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 · 2021-04-14T16:03:56Z

+    "A cover of functions and [method](#method)s, the must have `body` and `params`. Note: `Function` is different to `FunctionParent`.",
+  FunctionParent:
+    "A cover of AST nodes that start an execution context with new [VariableEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `var` declarations. FunctionParent did not include `Program` since Babel 7.",
+  Immutable: "A cover of immutable AST nodes.",


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

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.

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

nicolo-ribaudo · 2021-04-14T16:22:39Z

+  EnumBody:
+    "A cover of enum bodies defined in [TypeScript](https://www.typescriptlang.org/docs/handbook/enums.html) and Flow.",
+  EnumMember:
+    "A cover of enum membors defined in [TypeScript](https://www.typescriptlang.org/docs/handbook/enums.html) and Flow.",


I think those are only for Flow

JLHwung · 2021-04-14T16:25:21Z

+  Function:
+    "A cover of functions and [method](#method)s, the must have `body` and `params`. Note: `Function` is different to `FunctionParent`.",
+  FunctionParent:
+    "A cover of AST nodes that start an execution context with new [VariableEnvironment](https://tc39.es/ecma262/#table-additional-state-components-for-ecmascript-code-execution-contexts). In other words, they define the scope of `var` declarations. FunctionParent did not include `Program` since Babel 7.",


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.

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.

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

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); }; };

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.

Oh right, thanks

nicolo-ribaudo · 2021-04-14T16:25:56Z

+  TSType: "A cover of TypeScript type annotations.",
+  TSTypeElement: "A cover of TypeScript type declarations.",
+  Terminatorless:
+    "A cover of AST nodes whose semantic will change when a line terminator is inserted between the operator and the operand.",


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

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 · 2021-04-14T16:31:58Z

+  Expression:
+    "A cover of any [Expression](https://tc39.es/ecma262/#sec-ecmascript-language-expressions)s.",
+  ExpressionWrapper:
+    "A wrapper of expression that does not have run semantics.",


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.

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 · 2021-04-14T16:32:49Z

+const aliasDescriptions = {
+  Binary:
+    "A cover of BinaryExpression and LogicalExpression, which share the same AST shape.",
+  Block: "A cover of BlockStatement and its alike.",


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

Let's just remove it in Babel 8

JLHwung · 2021-04-30T20:08:03Z

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

JLHwung added the PR: Docs 📝 A type of pull request used for our changelog categories label Apr 14, 2021

JLHwung commented Apr 14, 2021

View reviewed changes

nicolo-ribaudo reviewed Apr 14, 2021

View reviewed changes

JLHwung commented Apr 14, 2021

View reviewed changes

nicolo-ribaudo reviewed Apr 14, 2021

View reviewed changes

JLHwung commented Apr 14, 2021

View reviewed changes

JLHwung mentioned this pull request Apr 14, 2021

refactor: use FunctionParent on visiting var scope #13152

Merged

nicolo-ribaudo approved these changes Apr 14, 2021

View reviewed changes

JLHwung mentioned this pull request Apr 14, 2021

docs: refine babel-types docs generator #13148

Merged

JLHwung added 6 commits April 14, 2021 16:32

add alias docs generator

48071f4

fix LVal and PatternLike

4fbcc4b

sort alias covered node types

67edf8f

add inner links between alias and node types

bd0c7ca

review comments

a5d41bc

tiny tweaks

e8ebe57

JLHwung force-pushed the add-alias-docs-generator branch from e23b5ba to e8ebe57 Compare April 14, 2021 20:32

JLHwung mentioned this pull request Apr 30, 2021

Add babel types alias docs babel/website#2492

Merged

JLHwung merged commit 9d6893d into babel:main Apr 30, 2021

JLHwung deleted the add-alias-docs-generator branch April 30, 2021 20:08

This was referenced May 18, 2021

chore(deps-dev): bump @babel/core from 7.13.8 to 7.14.2 filecoin-project/slate#746

Closed

chore(deps-dev): bump @babel/eslint-parser from 7.13.8 to 7.14.2 filecoin-project/slate#745

Closed

github-actions Bot added the outdated A closed issue/PR that is archived due to age. Recommended to make a new issue label Jul 31, 2021

github-actions Bot locked as resolved and limited conversation to collaborators Jul 31, 2021

	/**
	* 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 {

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

Uh oh!

Conversation

JLHwung commented Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hzoo Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

babel-bot commented Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codesandbox-ci Bot commented Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nicolo-ribaudo Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JLHwung Apr 14, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JLHwung commented Apr 30, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JLHwung commented Apr 14, 2021 •

edited

Loading

hzoo Apr 14, 2021 •

edited

Loading

babel-bot commented Apr 14, 2021 •

edited

Loading

codesandbox-ci Bot commented Apr 14, 2021 •

edited

Loading

nicolo-ribaudo Apr 14, 2021 •

edited

Loading

JLHwung Apr 14, 2021 •

edited

Loading