📎 [WIP] AST updates

[jamiebuilds]

Description

Reviewing the new Ungrammar AST carefully there are a number of changes I think should be made for these reasons (in this order):

• Accuracy: Where possible we should represent all valid programs and only valid programs.
• Clarity: When you see a node in isolation, you should have a clear picture of what syntax it represents and where it is valid.
• Predictability: When you're building the AST or just interacting with the API, you should be able to guess what the API is for the task at hand.
• Consistency: This is more an element of predictability, but it's worth calling out specifically, consistency creates habits and things become second nature.

There are some places where being accurate isn't always reasonable:

• When it would create lots of overly-specific node types that would burden developers having to translate between two very similar nodes just to move syntax around.
• When it very closely ties the AST to the current state of the spec and would likely lead to breaking changes. It's tempting to just copy how the spec defines things (although that's not always possible), sometimes it's worth giving a little wiggle room in order to be defensive.

When it comes to naming there's a couple high-level guidances (not strict rules) that I've come up with:

• When you introduce a term that represents a category, define its purpose clearly, and make sure all the nodes that fall in that category are using it in the same way. (i.e. "declaration" is currently being used in several different syntactic contexts).
• Prefer to name things after their relationship to one another in syntax, rather than their relationship to another node's "type" (although if you do this everywhere they'll start to be the same). This helps keep things consistent, but also is defensive against changing syntax.
• Never use abbreviations, even where it seems obvious. (i.e. Parameter not Param)
• Things that accept many items should be pluralized words. (i.e. items not body)

There are a couple "category" words that I've defined. In all cases, any node that falls into these categories should be swappable with any other node that falls into the same category. They are:

• Expression: An expression produces a value and can be written wherever a value is expected.
• Statement: A statement represents a discrete step in evaluation, it does not produce a value and therefore cannot be used in any position a value is expected.
• Type: A type represents a constraint
• Binding: A binding represents a name that is created in a scope and can be referenced later on.
• Assignment: An assignment represents an operation that mutates a value either in scope or within another value.
• {Binding,Assignment}Pattern: A pattern represents the destructuring of a value to create a binding or assignment.
• Name: [WIP]
• {Object,Class}Member: [WIP: A named item of an object]
• Element: [WIP: An item of an array]
• Parameter: [WIP: An item of signature]
• Argument: [WIP: An item of a call]

There's also a somewhat special category that I think needs better defining:

• List: This should only ever contain a single array of items, but we sometimes need it to make sure we have O(1) access to CST nodes, so we should consider how we use it and if we should "defensively" use it.

There are some other names that I've started to come up with names of that only really apply to node attributes:

• Consequent: [WIP: The logic that runs if a condition is met]
• Alternate: [WIP: The logic that runs if a condition is not met]
• Operator: A piece of lexical syntax that serves an important role describing a logical/algebraic/etc function. (i.e. % or in)
• Left/Right: These should always be a pair and separated by an operator (i.e. 2 % 2), and they should have the same type (i.e. for (let x in y) should not be named left/right).
• (I've played around with a lot of other changes, but I'm not really certain about the rest yet)

Then there is the structure of a node name:

Name     = Meta? Grammar Kind Category Element?
Meta     = 'Any' | 'Bogus'
Grammar  = 'Js' | 'Jsx' | 'Ts' | 'Tsx'
Kind     = 'Variable' | 'TypeAlias' | 'Boolean'
Category = 'Expression' | 'Statement' | 'Type' | `BindingPattern` | etc
Element  = 'Element' | 'Member' | 'Clause' | 'Entry' | 'Specifier' | etc

The important parts here are:

• Meta names, like Any or Bogus (which I'll get to later), should come first because they describe properties of how we write ASTs (with enums and error recovery nodes) and this helps us from ever confusing TsAnyType (the enum) with TsAnyType (the ts any type)
• Putting the feature before the category helps make autocompletion not suck (Actually to be honest I don't know how true that is, the intuition feels right, but maybe I'm just stuck in my ways)
• Specific "elements" of features should be at the end, this keeps them all grouped together for completions and just mental understanding.

AnyJsArrayBindingPatternElement

Meta     = 'Any'
Grammar  = 'Js'
Kind     = 'Array'
Category = 'BindingPattern'
Element  = 'Element'

Note: I could be convinced it should be AnyJsBindingPatternArrayElement, it feels so weird though.

That all being said, here are some changes that I'd make to follow the above thinking:

• JsAny* → AnyJs*
• JsUnknown* → BogusJs*
• JsRoot.program = JsModule | JsScript
• All statements end in *Statement
• All expressions end in *Expression
• All types end in *Type
• Drop *Literal
• Imports/Exports are not "statements"
• JsImportCallExpression → JsImportExpression
• *AssignmentTarget → *Assignment
• *Pattern (etc) → *BindingPattern & *AssignmentPattern
• *Binding & *Assignment should not include patterns
• Ts{Keyword}Type → Ts{Keyword}KeywordType
• Ts{Literal}LiteralType → Ts{Literal}Type
• TsObjectType → TsLiteralType (or better name)
• Unknown* → Bogus*
• For{In,Of}Statement.left → For{In,Of}Statement.initializer
• For{In,Of}Statement.initializer = JsVariableDeclaration | JsAnyAssignmentPattern

Breaking some of those down more specifically:

JsAny* → AnyJs*

Using the rules about how these "meta" names should be included.

JsUnknown* → BogusJs*

Names like TsUnknownType (if we ever decided to have that as an error recovery node) would be incredibly confusing if not conflicting. Initially I was just going to say we should name it UnknownTsType but then @sebmck and I sat down and thought about how that doesn't leave exactly the right impression.

We sat around with a thesaurus and tried out a bunch of different names, we ended up liking "bogus" because:

• It doesn't seem like it'd ever be a name used by a syntax feature in any language.
• It's not implying that we couldn't figure out what it is (when we sometimes might be totally capable of that), it's that the syntax doesn't belong where it is.

That being said, we're also worried that ESL speakers might not be familiar with that word, and we're not super tied to it, so if someone has suggestions please share them.

JsRoot.program = JsModule | JsScript

JsScript cannot contain imports or exports, JsModule can. This is a very important distinction in how you interpret these files and should be reflected in the AST.

All statements end in *Statement

The distinction of "declaration" gets confusing because some declarations are statements and others are not. Doubly confusing when some statement declarations are named like VariableDeclarationStatement.

Note: To reduce confusion coming from other ASTs, I think we should just drop the use of "declaration" in all places.

Important: The spec does have a number of places where statements and declarations are separate unions and they are valid in different places. These differences are not usually represented in existing JS ASTs, but we may want to revisit it later.

All expressions end in *Expression

Babel uses nodes like StringLiteral in non-expression positions (such as import "source"). I don't believe we're doing that anywhere (but we shouldn't) so using *Expression everywhere makes it clear that you should only use them in expression positions.

Drop the *Literal*

Using JsStringLiteralExpression feels like we're qualifying its type too much. JsStringExpression is plenty specific. Same goes for all the others.

All types end in *Type

For consistency's sake. Encourages correct usage.

Imports/Exports are not "statements"

In the sense that imports/exports can not appear in any statement position means we can either consider them "special" statements, or something else entirely. In order to simplify our idea of JsAnyStatement we should consider imports/exports to be their own thing.

I'm not sure if it makes sense to try and unify the different import/export types behind singular JsImport and JsExport nodes, but I think we might want to try.

JsImportCallExpression → JsImportExpression

Despite the syntax, import() should not be considered a "call" to a function named import.

If there were a JsAnyCallExpression, it would be confusing if it included imports because they have substantially different behavior. Especially when you consider the static nature of how they are used in bundlers. Removing *Call* from the name makes it clearer they are unrelated.

JsReferenceIdentifierExpression → JsIdentifierExpression

Identifiers in expression positions can only ever be references.

If we use Reference here, there are arguably other places we should add that qualifier such as JSThisReferenceExpression or JSSuperReferenceExpression. That feels like an unnecessary amount of qualification.

Previously this was called JsReferenceIdentifier so that it could be used in non-expression positions. But that feels like the wrong separation.

*AssignmentTarget → *Assignment

AssignmentTarget is a really long qualifier. Previous in Rome Classic we just used Assignment and that worked fine.

[WIP] Binding(Pattern) & Assignment(Pattern)

Note: This section is a work in progress, in particular the default portion is not quite correct. Let's have a call to describe the ideal state better.

I think it's important to distinguish when something is a "binding" or "assignment" vs when it's a "pattern". An "Object Binding" seems nonsensical. And this actually aligns with the naming of the spec.

Syntax	Bindings	Assignments
Bind/Assign	AnyJsBinding	AnyJsAssignment
id	JsIdentifierBinding	JsIdentifierAssignment
expr.name	N/A	JsStaticMemberAssignment
expr[expr]	N/A	JsComputedMemberAssignment
Defaults
target=expr	JsBindingDefault	JsAssignmentDefault
Patterns
	AnyJsBindingPattern	AnyJsAssignmentPattern
Patterns/Objects
{}	JsObjectBindingPattern	JsObjectAssignmentPattern
	AnyJsObjectBindingPatternMember	AnyJsObjectAssignmentPatternMember
{name|[expr]:id}	JsObjectBindingPatternProperty	JsObjectAssignmentPatternProperty
{id}	JsObjectBindingPatternShorthandProperty	JsObjectAssignmentPatternShorthandProperty
{...id}	JsObjectBindingPatternRest	JsObjectAssignmentPatternRest
Patterns/Arrays
[]	JsArrayBindingPattern	JsArrayAssignmentPattern
	AnyJsArrayBindingPatternElement	AnyJsArrayAssignmentPatternElement
[...target]	JsArrayBindingPatternRestElement	JsArrayAssignmentPatternRestElement

AnyJsBinding = JsIdentifierBinding
AnyJsAssignment = JsIdentifierAssignment | JsStaticMemberAssignment | JsComputedMemberAssignment

AnyJsBindingPattern = AnyJsBinding | JsObjectBindingPattern | JsArrayBindingPattern
AnyJsAssignmentPattern = AnyJsAssignment | JsObjectAssignmentPattern | JsArrayAssignmentPattern

AnyJsObjectBindingPatternMember = AnyJsBindingPattern | JsBindingDefault
AnyJsObjectAssignmentPatternMember = AnyJsAssignmentPattern | JsAssignmentDefault

AnyJsArrayBindingPatternElement =
AnyJsArrayAssignmentPatternElement =

Ts{Keyword}Type → Ts{Keyword}KeywordType & Ts{Literal}LiteralType → Ts{Literal}Type

This feels like a better alignment:

JsStringExpression : TsStringType :: `("")` : `type T = ""`
JsNumberExpression : TsNumberType :: `(42)` : `type T = 42`

So I think we should use *KeywordType:

type TsStringKeywordType = string
type TsNumberKeywordType = number
type TsObjectKeywordType = object
type TsUnknownKeywordType = unknown
type TsAnyKeywordType = any
type TsVoidKeywordType = void
// etc...

This also happens to be how TypeScript names these "keywords".

TsObjectType → TsLiteralType

In TypeScript type t = {} doesn't really mean "an object", it describes the shape of a value, and can describe types such as functions. This can be confusing to a lot of TypeScript users, and developers working with Rome's AST might be doubly confused if it's called an "object".

TypeScript and Babel both call this node a TypeLiteral, which flipping it to follow our "All types end in *Type" rule, is TsLiteralType.

Calling this a "literal" is a bit odd though, it doesn't really meet any definition for "literal" that I can come up with. So I'm very open to other ideas.

---

I have a couple other things I'm thinking about, but I wanted to share what I had so far.

[MichaReiser]

This looks amazing and thank you for writing it down.

*AssignmentTarget → *Assignment

This is a bit misleading in my view because my understanding is that an assignment consists of a value that gets assigned to something. My initial thought was, let's name this assignee but it seems that assignees must be people.

[jamiebuilds]

My initial thought was, let's name this assignee but it seems that assignees must be people.

I think English is pretty flexible in that regard. You can totally personify an object or concept with a word like “assignee”.

I could go either way, “Assignment” feels similar enough to “Binding” to me; both describing the operation that’s happening on that target. “Binding” also could have been “BindingTarget” but that feels overly qualified.

[jamiebuilds]

Binary Expressions & Assignment Expressions

All of these expressions (binary and assignment) fall under the category of "lhs op rhs" but there are important differences between many of them:

1. What nodes are allowed on either side of the operator. Example: The left side of = only allows assignment targets.
2. The type of the value produced by the operator. Example: == and < produce a boolean, - and ** produce a number/bigint.
3. Another important difference is the different types of operations the operators perform. Example: == and ** will always evaluate both sides, || and && may optionally evaluate only the left side.

Most JavaScript ASTs only distinguish the first (assignment vs binary) and third (binary vs logical), and they do so somewhat inconsistently:

• in accepts a #privateName on left-side
• + can produce strings
• ??= will sometimes not assign
• *= only accepts simple assignment targets on left-side

I would argue for these reasons we should split all of these up:

JsComparativeExpression = '<' | '>' | '<=' | '>=' | '==' | '===' | '!=' | '!=='
JsArithmeticExpression  = '+' | '-' | '*' | '/' | '%' | '**'
JsBitwiseExpression     = '<<' | '>>' | '>>>' | '&' | '|' | '^'
JsLogicalExpression     = '??' | '||' | '&&'
JsInExpression          = 'in'
JsInstanceofExpression  = 'instanceof'

JsSimpleAssignmentExpression     = '='
JsArithmeticAssignmentExpression = '+=' | '-=' | '*=' | '%=' | '**=' |
JsBitwiseAssignmentExpression    = '>>=' | '<<=' | '>>>=' | '&=' | '|=' | '^='
JsLogicalAssignmentExpression    = '&&=' | '||=' | '??='

AnyJsAssignmentExpression =
	JsSimpleAssignmentExpression
	| JsArithmeticAssignmentExpression
	| JsBitwiseAssignmentExpression
	| JsLogicalAssignmentExpression

Notes:

• I've dropped Binary from the names, I think it makes them unnecessarily overspecified (more on this in a second)
• I've kept "bitwise" and "arithmetic" separate, I don't have any good reason for this other than it feels right. Feel free to tell me I'm wrong.
• I've kept + grouped in with "arithmetic" even though it's slightly different in that it can produce a string. It feels like it would be more surprising to have it as its own expression than people needing to be conscious of type casting in JavaScript.
• I went with JsSimpleAssignmentExpression but I'm up for a better name if someone has one.

Thinking about it, I kinda find the concept of a "binary operator" a little bit poorly defined at the level of abstraction we have in our AST. I think it might be more meaningful in a higher-level representation where things like ??= are multiple steps.

I'm not entirely opposed to having an enum that captures all these related ast nodes, but I'm not sure if it's really necessary.

in

One additional thing we could do is split the in operator into two expressions:

// These names feel weird being named after the operator now
JsInExpression       = AnyJsExpression 'in' AnyJsExpression
JsPrivateInExpresion = PrivateName 'in' AnyJsExpression

Thoughts?

Unary Expressions & Update Expressions

It's worth revisiting these at the same time. By the same logic as above, it would mean splitting up most of these. Initially that feels like overkill though.

For the same reasons I don't think "binary" makes sense at this level of abstraction, I also think "unary" is kind of fuzzy.

Some thoughts:

• delete shouldn't be grouped in with void typeof + - ~ ! because it has side effects
• void typeof + - ~ ! could be grouped together as "casts"
• Is delete a prefix "update expression"?
• Should void typeof + - ~ ! be split up on the types they produce or the steps they take?

[MichaReiser]

Identifiers & Names

The name in export { name } is a reference to name but we can't use IdentifierExpression because you can't replace name with any other expression.

That's why we should introduce a new ReferenceIdentifier that is the counterpart to BindingIdentifier

// Used when an identifier references a symbol in the lexical scope
JsReferenceIdentifier = name: 'ident'

// Used when an identifier binds a new symbol in the lexical scope
JsBindingIdentifier = name: 'ident'

JsIdentifierExpression = identifier: JsReferenceIdentifier

I further suggest introducing the new "concept" of JsName and JsPrivateName for "identifiers" that are neither a reference nor bind a symbol in the lexical scope. Use cases are:

• JsStaticMemberExpression.member
• export { a } from 'b': The a is referencing a symbol from the lexical scope of b
• export { b as c }: The c doesn't bind a new identifier in the current lexical scope

JsName = value: 'ident'
JsPrivateName = '#' value: 'ident'
JsAnyName = JsName | JsPrivateName

[jamiebuilds]

Imports

This is more of an exploration

import "mod"
import foo from "mod"
import { foo } from "mod"
import * as foo from "mod"
import foo, { bar } from "mod"
import foo, * as bar from "mod"
// TypeScript:
import type foo from "mod"
import type { foo } from "mod"
import { type foo } from "mod"
import type * as foo from "mod"
import foo, { type bar } from "mod"
import foo = require("mod")
import foo = a.b.c
// Invalid:
import type foo, { bar } from "mod"
import type foo, * as bar from "mod"
import foo = a
import type foo = a

Lexical Grammar

If we try to enforce type with the grammar:

specifier       = 'ident' ('as' 'ident')?
type_specifier  = 'type'? specifier
specifiers      = (specifier (',' specifier) ','?)?
type_specifiers = (type_specifier (',' type_specifier) ','?)?

assert_entry = 'ident' ':' 'string'
assert = 'assert' '{' (assert_entry (',' assert_entry) ','?)? '}'

import = 'import' 'string' assert? ';'?
import = 'import' 'type'? 'ident' 'from' 'string' assert? ';'?
import = 'import' 'type'? '{' specifiers '}' 'from' 'string' assert? ';'?
import = 'import' '{' type_specifiers '}' 'from' 'string' assert? ';'?
import = 'import' 'type'? '*' 'as' 'ident' 'from' 'string' assert? ';'?
import = 'import' 'ident' ',' '{' type_specifiers '}' 'from' 'string' assert? ';'?
import = 'import' 'ident' ',' '*' 'as' 'ident' 'from' 'string' assert? ';'?
import = 'import' 'type'? 'ident' '=' 'require' '(' 'string' ')' ';'?
import = 'import' 'ident' '=' 'ident' ('.' 'ident')* ';'?

If we validate type at runtime:

specifier  = 'type'? 'ident' ('as' 'ident')?
specifiers = '{' (specifier (',' specifier) ','?)? '}'

assert_entry = 'ident' ':' 'string'
assert = 'assert' '{' (assert_entry (',' assert_entry) ','?)? '}'

import = 'import' 'string' assert? ';'?
import = 'import' 'type'? 'ident' 'from' 'string' assert? ';'?
import = 'import' 'type'? specifiers 'from' 'string' assert? ';'?
import = 'import' 'type'? '*' 'as' 'ident' 'from' 'string' assert? ';'?
import = 'import' 'ident' ',' specifiers 'from' 'string' assert? ';'?
import = 'import' 'ident' ',' '*' 'as' 'ident' 'from' 'string' assert? ';'?
import = 'import' 'type'? 'ident' '=' 'require' '(' 'string' ')' ';'?
import = 'import' 'ident' '=' 'ident' ('.' 'ident')* ';'?

If we validate commas at runtime:

specifier  = 'type'? 'ident' ('as' 'ident')?
specifiers = '{' (specifier (',' specifier) ','?)? '}'

assert_entry = 'ident' ':' 'string'
assert = 'assert' '{' (assert_entry (',' assert_entry) ','?)? '}'

default_clause = 'ident'
named_clause = specifiers | ('*' 'as' 'ident')

import = 'import' 'string' assert? ';'?
import = 'import' 'type'? default_clause? ','? named_clause? 'from' 'string' assert? ';'
import = 'import' 'type'? 'ident' '=' 'require' '(' 'string' ')' ';'?
import = 'import' 'ident' '=' 'ident' ('.' 'ident')* ';'?

In the interest of making imports easier to work with (they can be incredibly frustrating), I think we should trade off correctness for simplicity here.

Syntax Grammar

JsNamedImportSpecifier = 'type'? JsName ('as' JsIdentifierBinding)?
JsNamedImportSpecifierList = '{' (JsImportSpecifier (',' JsImportSpecifier) ','?)? '}'
JsNamespaceImportSpecifier = '*' 'as' JsIdentifierBinding
JsDefaultImportSpecifier = JsIdentifierBinding

JsImportSource = 'string'

JsImportAssertionEntry = 'ident' ':' 'string'
JsImportAssertion = 'assert' '{' (JsImportAssertionEntry (',' JsImportAssertionEntry) ','?)? '}'

JsImportBareClause = JsImportSource JsImportAssertion?
JsImportSpecifiersClause = 'type'? JsDefaultImportSpecifier? ','? (JsNamedImportSpecifierList |  JsNamespaceImportSpecifier)? 'from' JsImportSource JsImportAssertion?
TsImportRequireClause = 'ident' '=' 'require' '(' 'string' ')'
TsImportAliasClause = 'ident' '=' TsNamespace

AnyJsImportClause = JsImportBareClause | JsImportSpecifiersClause | TsImportRequireClause | TsImportAliasClause

JsImport = 'import' AnyJsImportClause ';'?

There might be some issues with how I defined that

[jamiebuilds]

In working on the export stuff, I realized that we might want to have a separate TsImportAliasStatement for import x = ... because it can appear in places that any other form of JsImport cannot:

export import x = require("m")

This is different from export * as x from "m" because it actually creates a binding in scope. Which makes it feel like this should still be a JsImport but I'm not sure.

[MichaReiser]

I haven't had much time to look into imports today, bindings and error recovery kept me busy for the most part of my day

One thing I noticed is that this syntax is adding TS syntax to JS nodes. My understanding was that we are OK having unions that contain as well JS and TS syntax but that JS nodes should only contain JS children, meaning, we would need to introduce a TsNamedImportSpecifier for { type A } imports.

JsNamedImportSpecifier = 'type'? JsName ('as' JsIdentifierBinding)?

I think we should split the NamedImportSpecifier with and without as into two nodes because

• name: must be a JsIdentifierBinding if the as... is absent
• name: must be a JsName if the as... is present.

It would resemble what we have for bindings: JsShorthandPropertyBindingPattern and JsPropertyBindingPattern

[jamiebuilds]

Oh, I think that not allowing JS nodes to contain TS nodes as children would make the AST a lot less usable. We'd need to have forks of: imports, exports, variables, functions, classes, jsx, try-catch, for/for-of/in, ast, expression statements, and probably some others I'm missing.

I think it's okay for JS nodes to have something like ts_type_annotation (or whatever the name is), but some rules:

• Must always be optional. This is compatible with how typescript designs syntax.
• Must always be prefixed with ts_. I think this will help with stability long term.

Thoughts?

[MichaReiser]

I think it's important to distinguish when something is a "binding" or "assignment" vs when it's a "pattern". An "Object Binding" seems nonsensical. And this actually aligns with the naming of the spec.

This is genius! I love it. And I think it solves the most problematic cases of when "illegal" identifiers bubble up as you suggested in our meeting yesterday. This would involve the following changes:

• Change all ids to JsAnyBinding, for example class.id changes from JsBindingIdentifier to JsAnyBinding.
• Change JsAnyBinding to JsBindingIdentifier | JsUnknownBinding
• Introduce JsAnyBindingPattern as JsAnyBinding | JsArrayBindingPattern " JsObjectBindingPattern

There may be more cases where syntax errors can "bubble up" but my impression is that they're less widespread and more local than what we've seen with binding identifiers.

The downside is that this is a JS specific solution and other languages will require an equally considered AST design.

[MichaReiser]

I extended your grammar a bit:

• Use JsBinding for local_name
• Introduced JsImportDefaultClause and JsImportNamespaceClause to verify the , between import a, { }and preventimport from "a". It also validates the typecombinations. I know you argued against it and I can see that it requires passes to analyze three different nodes to find alldefault` imports. I'm also OK validating this at runtime but we make the same distinction in other places. Overall, the overhead are two additional nodes which seems OK to me
• Renamed JsImportSource to JsModuleSource (we can share this with `exports)
• Split JsNamedImportSpecifier into JsShorthandNamedImportSpecifier and JsNamedImportSpecifier to correctly type local_name as a JsBinding
• Introduce JsAnyExportName (see next comment) to support { default as b} or `{ 'a-b-c-d' as b } (yes, that's valid syntax)
• Import assertion: Changed typing of key to 'ident' | 'string'
• TsImportRequireClause: Allow for type

JsImport = 
    'import' 
    import_clause: AnyJsImportClause
    ';'?

AnyJsImportClause = 
    JsImportBareClause 
    | JsImportNamedClause
    | JsImportDefaultClause
    | JsImportNamespaceClause
    | TsImportRequireClause 
    | TsImportAliasClause

// import "abcd"
// import "abcd" assert ...
JsImportBareClause = 
    source: JsModuleSource 
    assertion: JsImportAssertion?

// import foo from "mod"
// import type foo from "mod" `where foo is a `TsTypeBinding`
JsImportDefaultClause =
    'type'?
    local_name: JsBinding
    'from'
    source: JsModuleSource
    assertion: JsImportAssertion?

// import * as foo from "mod";
// import type * as foo from "mod";
JsImportNamespaceClause = 
    'type'?
    '*'
    'as'
    local_name: JsBinding
    specifier: JsNamespaceImportSpecifier
    'from'
    source: JsModuleSource
    assertion: JsImportAssertion?

// 
// import { a, b: c } from "d"
//        ^^^^^^^^^^^^^^^^^^^^
// import c, { b } from "c"
//        ^^^^^^^^^^^^^^^^^
// import { type a } from "c"
//        ^^^^^^^^^^^^^^^^^^^
// import foo, * as bar from "mod"
//        ^^^^^^^^^^^^^^^^^^^^^^^^
// import type { foo } from "mod";
//        ^^^^^^^^^^^^^^^^^^^^^^^
// import foo, { type bar } from "mod";
JsImportNamedClaus = 
    'type'? 
    default_specifier: JsDefaultImportSpecifier? 
    named_import: JsAnyNamedImport
    'from' 
    source: JsModuleSource 
    assertion: JsImportAssertion?

// import a, { b, c } from "d";
//        ^^
JsDefaultImportSpecifier = 
    local_name: JsBinding
    ','

JsAnyNamedImport = JsNamedImportSpecifierList |  JsNamespaceImportSpecifier 

JsNamespaceImportSpecifier = 
    '*' 
    'as' 
    local_name: JsBinding

JsNamedImportSpecifierList = 
    '{' 
    specifiers: (JsAnyNamedImportSpecifier (',' JsAnyNamedImportSpecifier)* ','?)
    '}'

JsAnyNamedImportSpecifier = 
    JsShorthandNamedImportSpecifier
    | JsNamedImportSpecifier

// import { foo as test } from "mod";
//          ^^^^^^^^^^^
// import { type foo as test } from "mod";
//          ^^^^^^^^^^^^^^^^^
JsNamedImportSpecifier = 
    'type'? 
    name: JsAnyExportName 
    'as' 
    local_name: JsBinding

// import { type foo } from "mod";
//          ^^^^^^^^
JsShorthandNamedImportSpecifier = 
    'type'? 
    local_name: JsBinding

// import x from "test"
//                ^^^^^
JsModuleSource = 'string'

JsImportAssertion = 
    'assert' 
    '{' 
    assertions: (JsImportAssertionEntry (',' JsImportAssertionEntry) ','?)
    '}'

JsImportAssertionEntry = 
    key: ('ident' | 'string') 
    ':' 
    value: 'string'


JsBinding = 
    JsIdentifierBinding
    | JsUnknownBinding
    | TsIdentifierBinding


// import foo = require("mod")
// import type foo = require("mod")
TsImportRequireClause = 
    'type'?
    // Used to be indent
    local_name: JsBinding
    '='
    'require'
    '('
    source: 'string' // JsModuleSource?
    ')'

// import foo = a.b.c;
// import foo = a // Valid!
// import type foo = a; // Invalid
TsImportAliasClause = 
    local_name: JsBinding   // TODO probably should be a TsName
    '=' 
    TsNamespace

One question that popped up while I worked on this is if we should introduce a TsBindingIdentifier for identifier binding a typescript value like a type.

[MichaReiser]

Exports

Buh, exports are killing it. This is insane...

One important finding is that class and function declaration used in export default do not require an id, so we can't reuse FunctionStatement (which would have been weird anyway, because that's a statement).

/////////////////////////////////////////////////
// EXPORTS                                     //
/////////////////////////////////////////////////

JsExport = 
    'export'
    export_clause: JsAnyExportClause 
    ';'?

JsAnyExportClause = 
    JsAnyExportDeclaration
    | JsExportDefaultClause
    | JsExportNamedClause
    | JsReExportClause
    | JsReExportNamedClause
    | TsExportAsNamespaceClause
    | TsExportAssignmentClause
    | TsExportImportClause


// export class A {}
// export function a() {}
// export let a, b, c, d;
// Typescript:
// export type A = string;
// export enum B { A, B }
// export interface C {}
// export namespace D {}
JsAnyExportDeclaration = 
    JsExportVariableDeclaration 
    | JsExportFunctionDeclaration 
    | JsExportClassDeclaration
    | TsExportTypeDeclaration
    | TsExportEnumDeclaration
    | TsExportInterfaceDeclaration
    | TsExportNamespaceDeclaration

JsExportVariableDeclaration = 
    kind: ('let' | 'const' | 'var')
    declarations: (JsVariableDeclaration (',' JsVariableDeclaration)*)

JsExportClassDeclaration = 
    'class'
    id: JsBinding
    extends_clause: JsExtendsClause?
    '{'
    members: JsClassMember*
    '}'

JsExportFunctionDeclaration =   
    'async'?
    'function'
    '*'?
    id: JsBinding
    parameter_list: JsParameterList
    body: JsFunctionBody

// Same as JsImportNamedClause;
// export { myFunction as default };
// export { myFunction, myVariable };
JsExportNamedClause = 
    '{'
    specifiers: (JsAnyExportNamedSpecifier (',' JsAnyExportNamedSpecifier)* ',')
    '}'

JsAnyExportNamedSpecifier = 
    JsExportNamedShorthandSpecifier
    | JsExportNamedSpecifier

JsExportNamedShorthandSpecifier = 
    'type'?
    name: JsReferenceIdentifier

JsExportNamedSpecifier = 
    'type'?
    local_name: JsReferenceIdentifier
    'as'
    exported_name: JsAnyExportName


JsAnyExportName = 
    | JsLiteralExportName
    | JsDefaultExportName

JsLiteralExportName = value: ('ident' | 'string')
JsDefaultExportName = 'default'

// export default class {} 
// export default class A {}     // ID is not required!!!
// export default function() {}  // ID is not required!!!
// export default function a() {}
JsExportDefaultClause = 
    'export'
    argument: JsAnyExportDefaultArgument

JsAnyExportDefaultArgument = 
    JsAnyExpression
    | JsExportDefaultClassArgument
    | JsExportDefaultFunctionArgument

JsExportDefaultClassArgument = 
    'class'
    id: JsBinding?
    extends_clause: JsExtendsClause?
    '{'
    members: JsClassMember*
    '}'

JsExportDefaultFunctionArgument = 
    'async'?
    'function'
    '*'?
    id: JsBinding?
    parameter_list: JsParameterList
    body: JsFunctionBody

JsAnyClass = 
    JsClassStatement
    | JsClassExpression
    | JsExportDefaultClassArgument
    | JsExportClassDeclaration

JsAnyFunction =  // Includes methods?
    | JsFunctionStatement
    | JsFunctionExpression
    | JsExportFunctionDeclaration
    | JsExportDefaultFunctionArgument

// Aggregating modules
// export * from …; // does not set the default export
// export * as name1 from …; // Draft ECMAScript® 2O21
// export { name1, name2, …, nameN } from …;
// export { import1 as name1, import2 as name2, …, nameN } from …;
// export { default, … } from …;
// export { type default as C } from "a";
// export { type default } from "a";

JsReExportClause = 
    '*'
    export_as: JsExportAsClause?
    'from'
    source: JsModuleSource

JsReExportNamedClause = 
    '{'
    specifiers: (JsReExportNamedSpecifier (',' JsReExportNamedSpecifier)* ','?)
    '}'
    'from'
    source: JsModuleSource


JsReExportNamedSpecifier = 
    'type'?
    source_name: JsAnyExportName
    export_as: JsExportAsClause? // OK because source_name is always a JsAnyExportName

JsExportAsClause = 
    'as'
    exported_name: JsAnyExportName

TsExportImportClause = 
    import: TsImportAliasClause

// export = b;
TsExportAssignmentClause = 
    '=' 
    source: JsName

// export as namespace c;
TsExportAsNamespaceClause = 
    'as'
    'namespace'
    source: JsName

[MichaReiser]

Additional changes:

• Introduce JsParameter: needed to support typescript type annotations
• Rename JsEqualValueClause to JsInitializerClause