ECMA-262 (12th Edition) ECMAScript 2021 Language Specification

If a right-hand side alternative is prefixed with “[+parameter]” that alternative is only available if the named
parameter was used in referencing the production's nonterminal symbol. If a right-hand side alternative is prefixed
with “[~parameter]” that alternative is only available if the named parameter was

not

used in referencing the

production's nonterminal symbol. This means that:

StatementList

[Return]

[+Return]

ReturnStatement

ExpressionStatement

is an abbreviation for:

StatementList

ExpressionStatement

StatementList_Return

ReturnStatement
ExpressionStatement

and that:

StatementList

[Return]

[~Return]

ReturnStatement

ExpressionStatement

is an abbreviation for:

StatementList

ReturnStatement
ExpressionStatement

StatementList_Return

ExpressionStatement

When the words “

one of

” follow the colon(s) in a grammar definition, they signify that each of the terminal symbols

on the following line or lines is an alternative definition. For example, the lexical grammar for ECMAScript contains
the production:

NonZeroDigit

one of

which is merely a convenient abbreviation for:

NonZeroDigit

If the phrase “[empty]” appears as the right-hand side of a production, it indicates that the production's right-hand
side contains no terminals or nonterminals.

If the phrase “[lookahead =

seq

]” appears in the right-hand side of a production, it indicates that the production may

only be used if the token sequence

seq

is a prefix of the immediately following input token sequence. Similarly,

“[lookahead

∈

set

]”, where

set

is a finite nonempty set of token sequences, indicates that the production may only be

used if some element of

set

is a prefix of the immediately following token sequence. For convenience, the set can also

be written as a nonterminal, in which case it represents the set of all token sequences to which that nonterminal could
expand. It is considered an editorial error if the nonterminal could expand to infinitely many distinct token sequences.

These conditions may be negated. “[lookahead

≠

seq

]” indicates that the containing production may only be used if

seq

not

a prefix of the immediately following input token sequence, and “[lookahead

∉

set

]” indicates that the

production may only be used if

element of

set

is a prefix of the immediately following token sequence.

As an example, given the definitions:

DecimalDigit

one of

DecimalDigits

DecimalDigit
DecimalDigits

DecimalDigit

the definition:

LookaheadExample

[lookahead

∉

{

}]

DecimalDigits

DecimalDigit

[lookahead

∉

DecimalDigit

]

matches either the letter

followed by one or more decimal digits the first of which is even, or a decimal digit not

followed by another decimal digit.

Note that when these phrases are used in the syntactic grammar, it may not be possible to unambiguously identify the
immediately following token sequence because determining later tokens requires knowing which lexical

goal symbol

to use at later positions. As such, when these are used in the syntactic grammar, it is considered an editorial error for a
token sequence

seq

to appear in a lookahead restriction (including as part of a set of sequences) if the choices of lexical

goal symbols to use could change whether or not

seq

would be a prefix of the resulting token sequence.

If the phrase “[no

LineTerminator

here]” appears in the right-hand side of a production of the syntactic grammar, it

indicates that the production is

a restricted production

: it may not be used if a

LineTerminator

occurs in the input stream

at the indicated position. For example, the production:

ThrowStatement

throw

[no

LineTerminator

here]

Expression

;

indicates that the production may not be used if a

LineTerminator

occurs in the script between the

throw

token and

the

Expression

Unless the presence of a

LineTerminator

is forbidden by a restricted production, any number of occurrences of

LineTerminator

may appear between any two consecutive tokens in the stream of input elements without affecting the

syntactic acceptability of the script.

When an alternative in a production of the lexical grammar or the numeric string grammar appears to be a multi-code
point token, it represents the sequence of code points that would make up such a token.

The right-hand side of a production may specify that certain expansions are not permitted by using the phrase “

but

not

” and then indicating the expansions to be excluded. For example, the production:

means that the nonterminal

Identifier

may be replaced by any sequence of code points that could replace

IdentifierName

provided that the same sequence of code points could not replace

ReservedWord

Finally, a few nonterminal symbols are described by a descriptive phrase in sans-serif type in cases where it would be
impractical to list all the alternatives:

SourceCharacter

any Unicode code point

The specification often uses a numbered list to specify steps in an algorithm. These algorithms are used to precisely
specify the required semantics of ECMAScript language constructs. The algorithms are not intended to imply the use
of any specific implementation technique. In practice, there may be more efficient algorithms available to implement a
given feature.

Algorithms may be explicitly parameterized with an ordered, comma-separated sequence of alias names which may
be used within the algorithm steps to reference the argument passed in that position. Optional parameters are
denoted with surrounding brackets ([ ,

name

]) and are no different from required parameters within algorithm steps.

A rest parameter may appear at the end of a parameter list, denoted with leading ellipsis (, ...

name

). The rest parameter

5.2 Algorithm Conventions

captures all of the arguments provided following the required and optional parameters into a

List

. If there are no such

additional arguments, that

List

is empty.

Algorithm steps may be subdivided into sequential substeps. Substeps are indented and may themselves be further
divided into indented substeps. Outline numbering conventions are used to identify substeps with the first level of
substeps labelled with lower case alphabetic characters and the second level of substeps labelled with lower case
roman numerals. If more than three levels are required these rules repeat with the fourth level using numeric labels.
For example:

1. Top-level step

a. Substep.

b. Substep.

i. Subsubstep.

1. Subsubsubstep

a. Subsubsubsubstep

i. Subsubsubsubsubstep

A step or substep may be written as an “if” predicate that conditions its substeps. In this case, the substeps are only
applied if the predicate is true. If a step or substep begins with the word “else”, it is a predicate that is the negation of
the preceding “if” predicate step at the same level.

A step may specify the iterative application of its substeps.

A step that begins with “

Assert

:” asserts an invariant condition of its algorithm. Such assertions are used to make

explicit algorithmic invariants that would otherwise be implicit. Such assertions add no additional semantic
requirements and hence need not be checked by an implementation. They are used simply to clarify algorithms.

Algorithm steps may declare named aliases for any value using the form “Let

someValue

”. These aliases are

reference-like in that both

and

someValue

refer to the same underlying data and modifications to either are visible to

both. Algorithm steps that want to avoid this reference-like behaviour should explicitly make a copy of the right-hand
side: “Let

be a copy of

someValue

” creates a shallow copy of

someValue

Once declared, an alias may be referenced in any subsequent steps and must not be referenced from steps prior to the
alias's declaration. Aliases may be modified using the form “Set

someOtherValue

”.

In order to facilitate their use in multiple parts of this specification, some algorithms, called

abstract operations

, are

named and written in parameterized functional form so that they may be referenced by name from within other
algorithms. Abstract operations are typically referenced using a functional application style such as
OperationName(

arg1

arg2

). Some abstract operations are treated as polymorphically dispatched methods of class-like

specification abstractions. Such method-like abstract operations are typically referenced using a method application
style such as

someValue

.OperationName(

arg1

arg2

syntax-directed operation

is a named operation whose definition consists of algorithms, each of which is associated

with one or more productions from one of the ECMAScript grammars. A production that has multiple alternative
definitions will typically have a distinct algorithm for each alternative. When an algorithm is associated with a
grammar production, it may reference the terminal and nonterminal symbols of the production alternative as if they

5.2.1 Abstract Operations

5.2.2 Syntax-Directed Operations

were parameters of the algorithm. When used in this manner, nonterminal symbols refer to the actual alternative
definition that is matched when parsing the source text. The

source text matched by

a grammar production is the

portion of the source text that starts at the beginning of the first terminal that participated in the match and ends at the
end of the last terminal that participated in the match.

When an algorithm is associated with a production alternative, the alternative is typically shown without any “[ ]”
grammar annotations. Such annotations should only affect the syntactic recognition of the alternative and have no
effect on the associated semantics for the alternative.

Syntax-directed operations are invoked with a parse node and, optionally, other parameters by using the conventions
on steps

, and

in the following algorithm:

1. Let

status

be SyntaxDirectedOperation of

SomeNonTerminal

2. Let

someParseNode

be the parse of some source text.

3. Perform SyntaxDirectedOperation of

someParseNode

4. Perform SyntaxDirectedOperation of

someParseNode

passing

"value"

as the argument.

Unless explicitly specified otherwise, all chain productions have an implicit definition for every operation that might
be applied to that production's left-hand side nonterminal. The implicit definition simply reapplies the same operation
with the same parameters, if any, to the

chain production

's sole right-hand side nonterminal and then returns the

result. For example, assume that some algorithm has a step of the form: “Return the result of evaluating

Block

” and

that there is a production:

Block

{

StatementList

}

but the Evaluation operation does not associate an algorithm with that production. In that case, the Evaluation
operation implicitly includes an association of the form:

Runtime Semantics: Evaluation

Block

{

StatementList

}

1. Return the result of evaluating

StatementList

Algorithms which specify semantics that must be called at runtime are called

runtime semantics

. Runtime semantics are

defined by

abstract operations

or syntax-directed operations. Such algorithms always return a completion record.

The algorithms of this specification often implicitly return

Completion

Records whose [[Type]] is

normal

. Unless it is

otherwise obvious from the context, an algorithm statement that returns a value that is not a

Completion Record

, such

as:

1. Return

"Infinity"

means the same thing as:

1. Return

NormalCompletion

(

"Infinity"

5.2.3 Runtime Semantics

5.2.3.1 Implicit Completion Values

However, if the value expression of a “return” statement is a

Completion Record

construction literal, the resulting

Completion Record

is returned. If the value expression is a call to an abstract operation, the “return” statement simply

returns the

Completion Record

produced by the abstract operation.

The abstract operation

Completion

(

completionRecord

) is used to emphasize that a previously computed

Completion

Record

is being returned. The

Completion

abstract operation takes a single argument,

completionRecord

, and performs

the following steps:

Assert

completionRecord

is a

Completion Record

2. Return

completionRecord

as the

Completion Record

of this abstract operation.

A “return” statement without a value in an algorithm step means the same thing as:

1. Return

NormalCompletion

(

undefined

Any reference to a

Completion Record

value that is in a context that does not explicitly require a complete

Completion

Record

value is equivalent to an explicit reference to the [[Value]] field of the

Algorithms steps that say to throw an exception, such as

1. Throw a

TypeError

exception.

mean the same things as:

1. Return

ThrowCompletion

(a newly created

TypeError

object).

Algorithms steps that say or are otherwise equivalent to:

ReturnIfAbrupt

(

argument

mean the same thing as:

1. If

argument

is an

abrupt completion

, return

argument

2. Else if

argument

is a

Completion Record

, set

argument

.[[Value]].

Algorithms steps that say or are otherwise equivalent to:

ReturnIfAbrupt

(AbstractOperation()).

mean the same thing as:

1. Let

hygienicTemp

be AbstractOperation().

2. If

hygienicTemp

is an

abrupt completion

, return

hygienicTemp

3. Else if

hygienicTemp

is a

Completion Record

, set

hygienicTemp

.[[Value]].

Where

hygienicTemp

is ephemeral and visible only in the steps pertaining to ReturnIfAbrupt.

Algorithms steps that say or are otherwise equivalent to:

5.2.3.2 Throw an Exception

5.2.3.3 ReturnIfAbrupt

1. Let

result

be AbstractOperation(

ReturnIfAbrupt

(

argument

)).

mean the same thing as:

1. If

argument

is an

abrupt completion

, return

argument

2. If

argument

is a

Completion Record

, set

argument

.[[Value]].

3. Let

result

be AbstractOperation(

argument

Invocations of

abstract operations

and syntax-directed operations that are prefixed by

indicate that

ReturnIfAbrupt

should be applied to the resulting

Completion Record

. For example, the step:

1. ? OperationName().

is equivalent to the following step:

ReturnIfAbrupt

(OperationName()).

Similarly, for method application style, the step:

1. ?

someValue

.OperationName().

is equivalent to:

ReturnIfAbrupt

(

someValue

.OperationName()).

Similarly, prefix

is used to indicate that the following invocation of an abstract or syntax-directed operation will

never return an

abrupt completion

and that the resulting

Completion Record

's [[Value]] field should be used in place

of the return value of the operation. For example, the step:

1. Let

val

be ! OperationName().

is equivalent to the following steps:

1. Let

val

be OperationName().

Assert

val

is never an

abrupt completion

3. If

val

is a

Completion Record

, set

val

.[[Value]].

Syntax-directed operations for

runtime semantics

make use of this shorthand by placing

before the invocation

of the operation:

1. Perform ! SyntaxDirectedOperation of

NonTerminal

Context-free grammars are not sufficiently powerful to express all the rules that define whether a stream of input
elements form a valid ECMAScript

Script

Module

that may be evaluated. In some situations additional rules are

needed that may be expressed using either ECMAScript algorithm conventions or prose requirements. Such rules are
always associated with a production of a grammar and are called the

static semantics

of the production.

Static Semantic Rules have names and typically are defined using an algorithm. Named Static Semantic Rules are
associated with grammar productions and a production that has multiple alternative definitions will typically have

5.2.3.4 ReturnIfAbrupt Shorthands

5.2.4 Static Semantics

for each alternative a distinct algorithm for each applicable named static semantic rule.

A special kind of static semantic rule is an

Early Error Rule

Early error

rules define

early error

conditions (see clause

) that are associated with specific grammar productions. Evaluation of most

early error

rules are not explicitly

invoked within the algorithms of this specification. A conforming implementation must, prior to the first evaluation of
a

Script

Module

, validate all of the

early error

rules of the productions used to parse that

the

rules are violated the

Script

Module

is invalid and cannot be evaluated.

This specification makes reference to these kinds of numeric values:

Mathematical values

: Arbitrary real numbers, used as the default numeric type.

Extended mathematical values

: Mathematical values together with +

∞

and -

∞

Numbers

IEEE 754-2019

double-precision floating point values.

BigInts

: ECMAScript values representing arbitrary integers in a one-to-one correspondence.

In the language of this specification, numerical values are distinguished among different numeric kinds using
subscript suffixes. The subscript

𝔽

refers to Numbers, and the subscript

ℤ

refers to BigInts. Numeric values without a

subscript suffix refer to mathematical values.

Numeric operators such as +,

, =, and

≥

refer to those operations as determined by the type of the operands. When

applied to mathematical values, the operators refer to the usual mathematical operations. When applied to Numbers,
the operators refer to the relevant operations within

IEEE 754-2019

. When applied to BigInts, the operators refer to the

usual mathematical operations applied to the

mathematical value

of the BigInt.

In general, when this specification refers to a numerical value, such as in the phrase, "the length of

" or "the

integer

represented by the four hexadecimal digits ...", without explicitly specifying a numeric kind, the phrase refers to a

mathematical value

. Phrases which refer to a Number or a BigInt value are explicitly annotated as such; for example,

"the

Number value

for the number of code points in …" or "the BigInt value for …".

Numeric operators applied to mixed-type operands (such as a Number and a

mathematical value

) are not defined and

should be considered an editorial error in this specification.

This specification denotes most numeric values in base 10; it also uses numeric values of the form 0x followed by
digits 0-9 or A-F as base-16 values.

When the term

integer

is used in this specification, it refers to a

mathematical value

which is in the set of integers,

unless otherwise stated. When the term

integral Number

is used in this specification, it refers to a

Number value

whose

mathematical value

is in the set of integers.

Conversions between mathematical values and Numbers or BigInts are always explicit in this document. A
conversion from a

mathematical value

extended mathematical value

to a Number is denoted as "the

. A conversion from an

integer

to a BigInt is denoted as "the BigInt value

for

" or

ℤ

(

). A conversion from a Number or BigInt

to a

mathematical value

is denoted as "the

mathematical value

", or

ℝ

(

). The

mathematical value

𝔽

and

-0

𝔽

is the

mathematical value

0. The

mathematical value

of non-finite

values is not defined. The

extended mathematical value

is the

mathematical value

for finite values, and is +

∞

and -

∞

for

∞

𝔽

and

∞

𝔽

respectively; it is not defined for

NaN

The mathematical function abs(

) produces the absolute value of

, which is -

< 0 and otherwise is

itself.

5.2.5 Mathematical Operations

The mathematical function min(

, … ,

) produces the mathematically smallest of

through

. The

mathematical function max(

, ...,

) produces the mathematically largest of

through

. The domain and

range of these mathematical functions are the extended mathematical values.

The notation “

modulo

” (

must be finite and non-zero) computes a value

of the same sign as

(or zero) such that

abs

(

) <

) and

The phrase "the result of

clamping

between

lower

and

upper

" (where

is an

extended mathematical value

and

lower

and

upper

are mathematical values such that

lower

≤

upper

) produces

lower

, produces

upper

, and

otherwise produces

The mathematical function floor(

) produces the largest

integer

(closest to +

∞

) that is not larger than

Mathematical functions min, max,

abs

, and

floor

are not defined for Numbers and BigInts, and any usage of those

methods that have non-

mathematical value

arguments would be an editorial error in this specification.

NOTE

In this specification, ECMAScript language values are displayed in

bold

. Examples include

null

true

, or

"hello"

These are distinguished from longer ECMAScript code sequences such as

Function.prototype.apply

let n = 42;

Values which are internal to the specification and not directly observable from ECMAScript code are indicated with a

sans-serif

typeface. For instance, a

Completion Record

's [[Type]] field takes on values like

normal

return

, or

throw

Algorithms within this specification manipulate values each of which has an associated type. The possible value types
are exactly those defined in this clause. Types are further subclassified into ECMAScript language types and
specification types.

Within this specification, the notation “Type(

)” is used as shorthand for “the

type

” where “type” refers to the

ECMAScript language and specification types defined in this clause. When the term “empty” is used as if it was
naming a value, it is equivalent to saying “no value of any type”.

ECMAScript language type

corresponds to values that are directly manipulated by an ECMAScript programmer

using the ECMAScript language. The ECMAScript language types are Undefined, Null, Boolean, String, Symbol,
Number, BigInt, and Object. An

ECMAScript language value

is a value that is characterized by an ECMAScript

language type.

floor

(

) =

- (

modulo

1).

5.2.6 Value Notation

6 ECMAScript Data Types and Values

6.1 ECMAScript Language Types

6.1.1 The Undefined Type

The Undefined type has exactly one value, called

undefined

. Any variable that has not been assigned a value has the

value

undefined

The Null type has exactly one value, called

null

The Boolean type represents a logical entity having two values, called

true

and

false

The String type is the set of all ordered sequences of zero or more 16-bit unsigned

integer

values (“elements”) up to a

maximum length of 2

- 1 elements. The String type is generally used to represent textual data in a running

ECMAScript program, in which case each element in the String is treated as a UTF-16 code unit value. Each element is
regarded as occupying a position within the sequence. These positions are indexed with non-negative integers. The
first element (if any) is at index 0, the next element (if any) at index 1, and so on. The length of a String is the number
of elements (i.e., 16-bit values) within it. The empty String has length zero and therefore contains no elements.

ECMAScript operations that do not interpret String contents apply no further semantics. Operations that do interpret
String values treat each element as a single UTF-16 code unit. However, ECMAScript does not restrict the value of or
relationships between these code units, so operations that further interpret String contents as sequences of Unicode
code points encoded in UTF-16 must account for ill-formed subsequences. Such operations apply special treatment to
every code unit with a numeric value in the inclusive range 0xD800 to 0xDBFF (defined by the Unicode Standard as a

leading surrogate

, or more formally as a

high-surrogate code unit

) and every code unit with a numeric value in the

inclusive range 0xDC00 to 0xDFFF (defined as a

trailing surrogate

, or more formally as a

low-surrogate code unit

) using

the following rules:

A code unit that is not a

leading surrogate

and not a

trailing surrogate

is interpreted as a code point with the

same value.
A sequence of two code units, where the first code unit

is a

leading surrogate

and the second code unit

trailing surrogate

, is a

surrogate pair

and is interpreted as a code point with the value (

- 0xD800)

0x400 + (

- 0xDC00) + 0x10000. (See

11.1.3

)

A code unit that is a

leading surrogate

trailing surrogate

, but is not part of a

surrogate pair

, is interpreted as

a code point with the same value.

The function

String.prototype.normalize

(see

22.1.3.13

) can be used to explicitly normalize a String value.

String.prototype.localeCompare

(see

22.1.3.10

) internally normalizes String values, but no other

operations implicitly normalize the strings upon which they operate. Only operations that are explicitly specified to
be language or locale sensitive produce language-sensitive results.

NOTE

In this specification, the phrase "the

string-concatenation

, ..." (where each argument is a String value, a code unit,

The rationale behind this design was to keep the implementation of Strings as simple and high-
performing as possible. If ECMAScript source text is in Normalized Form C, string literals are
guaranteed to also be normalized, as long as they do not contain any Unicode escape sequences.

6.1.2 The Null Type

6.1.3 The Boolean Type

6.1.4 The String Type

or a sequence of code units) denotes the String value whose sequence of code units is the concatenation of the code
units (in order) of each of the arguments (in order).

The phrase "the

substring

from

inclusiveStart

exclusiveEnd

" (where

is a String value or a sequence of code units

and

inclusiveStart

and

exclusiveEnd

are integers) denotes the String value consisting of the consecutive code units of

beginning at index

inclusiveStart

and ending immediately before index

exclusiveEnd

(which is the empty String when

inclusiveStart

exclusiveEnd

). If the "to" suffix is omitted, the length of

is used as the value of

exclusiveEnd

The abstract operation StringIndexOf takes arguments

string

(a String),

searchValue

(a String), and

fromIndex

(a non-

negative

integer

). It performs the following steps when called:

Assert

Type

(

string

) is String.

Assert

Type

(

searchValue

) is String.

Assert

fromIndex

is a non-negative

integer

4. Let

len

be the length of

string

5. If

searchValue

is the empty String and

fromIndex

≤

len

, return

fromIndex

6. Let

searchLen

be the length of

searchValue

7. For each

integer

starting with

fromIndex

such that

≤

len

searchLen

, in ascending order, do

a. Let

candidate

be the

substring

string

from

searchLen

b. If

candidate

is the same sequence of code units as

searchValue

, return

8. Return -1.

NOTE 1

NOTE 2

The Symbol type is the set of all non-String values that may be used as the key of an Object property (

6.1.7

Each possible Symbol value is unique and immutable.

Each Symbol value immutably holds an associated value called [[Description]] that is either

undefined

or a String

value.

Well-known symbols are built-in Symbol values that are explicitly referenced by algorithms of this specification. They
are typically used as the keys of properties whose values serve as extension points of a specification algorithm. Unless
otherwise specified, well-known symbols values are shared by all realms (

9.2

Within this specification a well-known symbol is referred to by using a notation of the form @@name, where “name”
is one of the values listed in

Table 1

Table 1: Well-known Symbols

searchValue

is the empty String and

fromIndex

is less than or equal to the length of

string

, this

algorithm returns

fromIndex

. The empty String is effectively found at every position within a

string, including after the last code unit.

This algorithm always returns -1 if

fromIndex

> the length of

string

6.1.4.1 StringIndexOf (

string

searchValue

fromIndex

)

6.1.5 The Symbol Type

6.1.5.1 Well-Known Symbols

ECMA-262 (12th Edition) ECMAScript 2021 Language Specification - page 11