☰

Draft ECMA-262 / September 14, 2020

ECMAScript® 2021 Language Specification

Introduction This Ecma Standard defines the ECMAScript 2021 Language. It is the twelfth edition of the ECMAScript Language Specification. Since publication of the first edition in 1997, ECMAScript has grown to be one of the world's most widely used general-purpose programming languages. It is best known as the language embedded in web browsers but has also been widely adopted for server and embedded applications. ECMAScript is based on several originating technologies, the most well-known being JavaScript (Netscape) and JScript (Microsoft). The language was invented by Brendan Eich at Netscape and first appeared in that company's Navigator 2.0 browser. It has appeared in all subsequent browsers from Netscape and in all browsers from Microsoft starting with Internet Explorer 3.0. The development of the ECMAScript Language Specification started in November 1996. The first edition of this Ecma Standard was adopted by the Ecma General Assembly of June 1997. That Ecma Standard was submitted to ISO/IEC JTC 1 for adoption under the fast-track procedure, and approved as international standard ISO/IEC 16262, in April 1998. The Ecma General Assembly of June 1998 approved the second edition of ECMA-262 to keep it fully aligned with ISO/IEC 16262. Changes between the first and the second edition are editorial in nature. The third edition of the Standard introduced powerful regular expressions, better string handling, new control statements, try/catch exception handling, tighter definition of errors, formatting for numeric output and minor changes in anticipation of future language growth. The third edition of the ECMAScript standard was adopted by the Ecma General Assembly of December 1999 and published as ISO/IEC 16262:2002 in June 2002. After publication of the third edition, ECMAScript achieved massive adoption in conjunction with the World Wide Web where it has become the programming language that is supported by essentially all web browsers. Significant work was done to develop a fourth edition of ECMAScript. However, that work was not completed and not published as the fourth edition of ECMAScript but some of it was incorporated into the development of the sixth edition. The fifth edition of ECMAScript (published as ECMA-262 5th edition) codified de facto interpretations of the language specification that have become common among browser implementations and added support for new features that had emerged since the publication of the third edition. Such features include accessor properties, reflective creation and inspection of objects, program control of property attributes, additional array manipulation functions, support for the JSON object encoding format, and a strict mode that provides enhanced error checking and program security. The fifth edition was adopted by the Ecma General Assembly of December 2009. The fifth edition was submitted to ISO/IEC JTC 1 for adoption under the fast-track procedure, and approved as international standard ISO/IEC 16262:2011. Edition 5.1 of the ECMAScript Standard incorporated minor corrections and is the same text as ISO/IEC 16262:2011. The 5.1 Edition was adopted by the Ecma General Assembly of June 2011. Focused development of the sixth edition started in 2009, as the fifth edition was being prepared for publication. However, this was preceded by significant experimentation and language enhancement design efforts dating to the publication of the third edition in 1999. In a very real sense, the completion of the sixth edition is the culmination of a fifteen year effort. The goals for this edition included providing better support for large applications, library creation, and for use of ECMAScript as a compilation target for other languages. Some of its major enhancements included modules, class declarations, lexical block scoping, iterators and generators, promises for asynchronous programming, destructuring patterns, and proper tail calls. The ECMAScript library of built-ins was expanded to support additional data abstractions including maps, sets, and arrays of binary numeric values as well as additional support for Unicode supplemental characters in strings and regular expressions. The built-ins were also made extensible via subclassing. The sixth edition provides the foundation for regular, incremental language and library enhancements. The sixth edition was adopted by the General Assembly of June 2015. ECMAScript 2016 was the first ECMAScript edition released under Ecma TC39's new yearly release cadence and open development process. A plain-text source document was built from the ECMAScript 2015 source document to serve as the base for further development entirely on GitHub. Over the year of this standard's development, hundreds of pull requests and issues were filed representing thousands of bug fixes, editorial fixes and other improvements. Additionally, numerous software tools were developed to aid in this effort including Ecmarkup, Ecmarkdown, and Grammarkdown. ES2016 also included support for a new exponentiation operator and adds a new method to Array.prototype called includes . ECMAScript 2017 introduced Async Functions, Shared Memory, and Atomics along with smaller language and library enhancements, bug fixes, and editorial updates. Async functions improve the asynchronous programming experience by providing syntax for promise-returning functions. Shared Memory and Atomics introduce a new memory model that allows multi- agent programs to communicate using atomic operations that ensure a well-defined execution order even on parallel CPUs. It also included new static methods on Object: Object.values , Object.entries , and Object.getOwnPropertyDescriptors . ECMAScript 2018 introduced support for asynchronous iteration via the AsyncIterator protocol and async generators. It also included four new regular expression features: the dotAll flag, named capture groups, Unicode property escapes, and look-behind assertions. Lastly it included object rest and spread properties. ECMAScript 2019 introduced a few new built-in functions: flat and flatMap on Array.prototype for flattening arrays, Object.fromEntries for directly turning the return value of Object.entries into a new Object, and trimStart and trimEnd on String.prototype as better-named alternatives to the widely implemented but non-standard String.prototype.trimLeft and trimRight built-ins. In addition, it included a few minor updates to syntax and semantics. Updated syntax included optional catch binding parameters and allowing U+2028 (LINE SEPARATOR) and U+2029 (PARAGRAPH SEPARATOR) in string literals to align with JSON. Other updates included requiring that Array.prototype.sort be a stable sort, requiring that JSON.stringify return well-formed UTF-8 regardless of input, and clarifying Function.prototype.toString by requiring that it either return the corresponding original source text or a standard placeholder. ECMAScript 2020, the 11th edition, introduces the matchAll method for Strings, to produce an iterator for all match objects generated by a global regular expression; import() , a syntax to asynchronously import Modules with a dynamic specifier; BigInt , a new number primitive for working with arbitrary precision integers; Promise.allSettled , a new Promise combinator that does not short-circuit; globalThis , a universal way to access the global this value; dedicated export * as ns from 'module' syntax for use within modules; increased standardization of for-in enumeration order; import.meta , a host -populated object available in Modules that may contain contextual information about the Module; as well as adding two new syntax features to improve working with “nullish” values ( null or undefined ): nullish coalescing, a value selection operator; and optional chaining, a property access and function invocation operator that short-circuits if the value to access/invoke is nullish. Dozens of individuals representing many organizations have made very significant contributions within Ecma TC39 to the development of this edition and to the prior editions. In addition, a vibrant community has emerged supporting TC39's ECMAScript efforts. This community has reviewed numerous drafts, filed thousands of bug reports, performed implementation experiments, contributed test suites, and educated the world-wide developer community about ECMAScript. Unfortunately, it is impossible to identify and acknowledge every person and organization who has contributed to this effort. Allen Wirfs-Brock

ECMA-262, Project Editor, 6th Edition Brian Terlson

ECMA-262, Project Editor, 7th through 10th Editions Jordan Harband

ECMA-262, Project Editor, 10th through 12th Editions

1 Scope This Standard defines the ECMAScript 2021 general-purpose programming language.

2 Conformance A conforming implementation of ECMAScript must provide and support all the types, values, objects, properties, functions, and program syntax and semantics described in this specification. A conforming implementation of ECMAScript must interpret source text input in conformance with the latest version of the Unicode Standard and ISO/IEC 10646. A conforming implementation of ECMAScript that provides an application programming interface (API) that supports programs that need to adapt to the linguistic and cultural conventions used by different human languages and countries must implement the interface defined by the most recent edition of ECMA-402 that is compatible with this specification. A conforming implementation of ECMAScript may provide additional types, values, objects, properties, and functions beyond those described in this specification. In particular, a conforming implementation of ECMAScript may provide properties not described in this specification, and values for those properties, for objects that are described in this specification. A conforming implementation of ECMAScript may support program and regular expression syntax not described in this specification. In particular, a conforming implementation of ECMAScript may support program syntax that makes use of any “future reserved words” noted in subclause 11.6.2 of this specification. A conforming implementation of ECMAScript must not implement any extension that is listed as a Forbidden Extension in subclause 16.1 . A conforming implementation of ECMAScript must not redefine any facilities that are not implementation-defined , implementation-approximated , or host-defined .

3 Normative References The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies. ISO/IEC 10646 Information Technology — Universal Multiple-Octet Coded Character Set (UCS) plus Amendment 1:2005, Amendment 2:2006, Amendment 3:2008, and Amendment 4:2008, plus additional amendments and corrigenda, or successor ECMA-402, ECMAScript 2015 Internationalization API Specification.

https://ecma-international.org/publications/standards/Ecma-402.htm ECMA-404, The JSON Data Interchange Format.

https://ecma-international.org/publications/standards/Ecma-404.htm

4 Overview This section contains a non-normative overview of the ECMAScript language. ECMAScript is an object-oriented programming language for performing computations and manipulating computational objects within a host environment . ECMAScript as defined here is not intended to be computationally self-sufficient; indeed, there are no provisions in this specification for input of external data or output of computed results. Instead, it is expected that the computational environment of an ECMAScript program will provide not only the objects and other facilities described in this specification but also certain environment-specific objects, whose description and behaviour are beyond the scope of this specification except to indicate that they may provide certain properties that can be accessed and certain functions that can be called from an ECMAScript program. ECMAScript was originally designed to be used as a scripting language, but has become widely used as a general-purpose programming language. A scripting language is a programming language that is used to manipulate, customize, and automate the facilities of an existing system. In such systems, useful functionality is already available through a user interface, and the scripting language is a mechanism for exposing that functionality to program control. In this way, the existing system is said to provide a host environment of objects and facilities, which completes the capabilities of the scripting language. A scripting language is intended for use by both professional and non-professional programmers. ECMAScript was originally designed to be a Web scripting language, providing a mechanism to enliven Web pages in browsers and to perform server computation as part of a Web-based client-server architecture. ECMAScript is now used to provide core scripting capabilities for a variety of host environments. Therefore the core language is specified in this document apart from any particular host environment . ECMAScript usage has moved beyond simple scripting and it is now used for the full spectrum of programming tasks in many different environments and scales. As the usage of ECMAScript has expanded, so have the features and facilities it provides. ECMAScript is now a fully featured general-purpose programming language. Some of the facilities of ECMAScript are similar to those used in other programming languages; in particular C, Java™, Self, and Scheme as described in: ISO/IEC 9899:1996, Programming Languages — C. Gosling, James, Bill Joy and Guy Steele. The Java™ Language Specification. Addison Wesley Publishing Co., 1996. Ungar, David, and Smith, Randall B. Self: The Power of Simplicity. OOPSLA '87 Conference Proceedings, pp. 227-241, Orlando, FL, October 1987. IEEE Standard for the Scheme Programming Language. IEEE Std 1178-1990. 4.1 Web Scripting A web browser provides an ECMAScript host environment for client-side computation including, for instance, objects that represent windows, menus, pop-ups, dialog boxes, text areas, anchors, frames, history, cookies, and input/output. Further, the host environment provides a means to attach scripting code to events such as change of focus, page and image loading, unloading, error and abort, selection, form submission, and mouse actions. Scripting code appears within the HTML and the displayed page is a combination of user interface elements and fixed and computed text and images. The scripting code is reactive to user interaction, and there is no need for a main program. A web server provides a different host environment for server-side computation including objects representing requests, clients, and files; and mechanisms to lock and share data. By using browser-side and server-side scripting together, it is possible to distribute computation between the client and server while providing a customized user interface for a Web-based application. Each Web browser and server that supports ECMAScript supplies its own host environment , completing the ECMAScript execution environment. 4.2 Hosts and Implementations To aid integrating ECMAScript into host environments, this specification defers the definition certain facilities (e.g., abstract operations ), either in whole or in part, to a source outside of this specification. Editorially, this specification distinguishes the following kinds of deferrals. An implementation is an external source that further defines facilities enumerated in Annex D or those that are marked as implementation-defined or implementation-approximated . In informal use, an implementation refers to a concrete artefact, such as a particular web browser. An implementation-defined facility is one that defers its definition to an external source without further qualification. This specification does not make any recommendations for particular behaviours, and conforming implementations are free to choose any behaviour within the constraints put forth by this specification. An implementation-approximated facility is one that defers its definition to an external source while recommending an ideal behaviour. While conforming implementations are free to choose any behaviour within the constraints put forth by this specification, they are encouraged to strive to approximate the ideal. Some mathematical operations, such as Math.exp , are implementation-approximated . A host is an external source that further defines facilities listed in Annex D but does not further define other implementation-defined or implementation-approximated facilities. In informal use, a host refers to the set of all implementations, such as the set of all web browsers, that interface with this specification in the same way via Annex D . A host is often an external specification, such as WHATWG HTML (https://html.spec.whatwg.org/). In other words, facilities that are host-defined are often further defined in external specifications. A host hook is an abstract operation that is defined in whole or in part by an external source. All host hooks must be listed in Annex D . A host-defined facility is one that defers its definition to an external source without further qualification and is listed in Annex D . Implementations that are not hosts may also provide definitions for host-defined facilities. A host environment is a particular choice of definition for all host-defined facilities. A host environment typically includes objects or functions which allow obtaining input and providing output as host-defined properties of the global object . This specification follows the editorial convention of always using the most specific term. For example, if a facility is host-defined , it should not be referred to as implementation-defined . Both hosts and implementations may interface with this specification via the language types, specification types, abstract operations , grammar productions, intrinsic objects, and intrinsic symbols defined herein. 4.3 ECMAScript Overview The following is an informal overview of ECMAScript—not all parts of the language are described. This overview is not part of the standard proper. ECMAScript is object-based: basic language and host facilities are provided by objects, and an ECMAScript program is a cluster of communicating objects. In ECMAScript, an object is a collection of zero or more properties each with attributes that determine how each property can be used—for example, when the Writable attribute for a property is set to false , any attempt by executed ECMAScript code to assign a different value to the property fails. Properties are containers that hold other objects, primitive values, or functions. A primitive value is a member of one of the following built-in types: Undefined, Null, Boolean, Number, BigInt, String, and Symbol; an object is a member of the built-in type Object; and a function is a callable object. A function that is associated with an object via a property is called a method. ECMAScript defines a collection of built-in objects that round out the definition of ECMAScript entities. These built-in objects include the global object ; objects that are fundamental to the runtime semantics of the language including Object , Function , Boolean , Symbol , and various Error objects; objects that represent and manipulate numeric values including Math , Number , and Date ; the text processing objects String and RegExp ; objects that are indexed collections of values including Array and nine different kinds of Typed Arrays whose elements all have a specific numeric data representation; keyed collections including Map and Set objects; objects supporting structured data including the JSON object, ArrayBuffer , SharedArrayBuffer , and DataView ; objects supporting control abstractions including generator functions and Promise objects; and reflection objects including Proxy and Reflect . ECMAScript also defines a set of built-in operators. ECMAScript operators include various unary operations, multiplicative operators, additive operators, bitwise shift operators, relational operators, equality operators, binary bitwise operators, binary logical operators, assignment operators, and the comma operator. Large ECMAScript programs are supported by modules which allow a program to be divided into multiple sequences of statements and declarations. Each module explicitly identifies declarations it uses that need to be provided by other modules and which of its declarations are available for use by other modules. ECMAScript syntax intentionally resembles Java syntax. ECMAScript syntax is relaxed to enable it to serve as an easy-to-use scripting language. For example, a variable is not required to have its type declared nor are types associated with properties, and defined functions are not required to have their declarations appear textually before calls to them. 4.3.1 Objects Even though ECMAScript includes syntax for class definitions, ECMAScript objects are not fundamentally class-based such as those in C++, Smalltalk, or Java. Instead objects may be created in various ways including via a literal notation or via constructors which create objects and then execute code that initializes all or part of them by assigning initial values to their properties. Each constructor is a function that has a property named "prototype" that is used to implement prototype-based inheritance and shared properties. Objects are created by using constructors in new expressions; for example, new Date(2009, 11) creates a new Date object. Invoking a constructor without using new has consequences that depend on the constructor . For example, Date() produces a string representation of the current date and time rather than an object. Every object created by a constructor has an implicit reference (called the object's prototype) to the value of its constructor 's "prototype" property. Furthermore, a prototype may have a non-null implicit reference to its prototype, and so on; this is called the prototype chain. When a reference is made to a property in an object, that reference is to the property of that name in the first object in the prototype chain that contains a property of that name. In other words, first the object mentioned directly is examined for such a property; if that object contains the named property, that is the property to which the reference refers; if that object does not contain the named property, the prototype for that object is examined next; and so on. Figure 1: Object/Prototype Relationships In a class-based object-oriented language, in general, state is carried by instances, methods are carried by classes, and inheritance is only of structure and behaviour. In ECMAScript, the state and methods are carried by objects, while structure, behaviour, and state are all inherited. All objects that do not directly contain a particular property that their prototype contains share that property and its value. Figure 1 illustrates this: CF is a constructor (and also an object). Five objects have been created by using new expressions: cf 1 , cf 2 , cf 3 , cf 4 , and cf 5 . Each of these objects contains properties named "q1" and "q2" . The dashed lines represent the implicit prototype relationship; so, for example, cf 3 's prototype is CF p . The constructor , CF, has two properties itself, named "P1" and "P2" , which are not visible to CF p , cf 1 , cf 2 , cf 3 , cf 4 , or cf 5 . The property named "CFP1" in CF p is shared by cf 1 , cf 2 , cf 3 , cf 4 , and cf 5 (but not by CF), as are any properties found in CF p 's implicit prototype chain that are not named "q1" , "q2" , or "CFP1" . Notice that there is no implicit prototype link between CF and CF p . Unlike most class-based object languages, properties can be added to objects dynamically by assigning values to them. That is, constructors are not required to name or assign values to all or any of the constructed object's properties. In the above diagram, one could add a new shared property for cf 1 , cf 2 , cf 3 , cf 4 , and cf 5 by assigning a new value to the property in CF p . Although ECMAScript objects are not inherently class-based, it is often convenient to define class-like abstractions based upon a common pattern of constructor functions, prototype objects, and methods. The ECMAScript built-in objects themselves follow such a class-like pattern. Beginning with ECMAScript 2015, the ECMAScript language includes syntactic class definitions that permit programmers to concisely define objects that conform to the same class-like abstraction pattern used by the built-in objects. 4.3.2 The Strict Variant of ECMAScript The ECMAScript Language recognizes the possibility that some users of the language may wish to restrict their usage of some features available in the language. They might do so in the interests of security, to avoid what they consider to be error-prone features, to get enhanced error checking, or for other reasons of their choosing. In support of this possibility, ECMAScript defines a strict variant of the language. The strict variant of the language excludes some specific syntactic and semantic features of the regular ECMAScript language and modifies the detailed semantics of some features. The strict variant also specifies additional error conditions that must be reported by throwing error exceptions in situations that are not specified as errors by the non-strict form of the language. The strict variant of ECMAScript is commonly referred to as the strict mode of the language. Strict mode selection and use of the strict mode syntax and semantics of ECMAScript is explicitly made at the level of individual ECMAScript source text units. Because strict mode is selected at the level of a syntactic source text unit, strict mode only imposes restrictions that have local effect within such a source text unit. Strict mode does not restrict or modify any aspect of the ECMAScript semantics that must operate consistently across multiple source text units. A complete ECMAScript program may be composed of both strict mode and non-strict mode ECMAScript source text units. In this case, strict mode only applies when actually executing code that is defined within a strict mode source text unit. In order to conform to this specification, an ECMAScript implementation must implement both the full unrestricted ECMAScript language and the strict variant of the ECMAScript language as defined by this specification. In addition, an implementation must support the combination of unrestricted and strict mode source text units into a single composite program. 4.4 Terms and Definitions For the purposes of this document, the following terms and definitions apply. 4.4.1 implementation-approximated an implementation-approximated facility is defined in whole or in part by an external source but has a recommended, ideal behaviour in this specification 4.4.2 implementation-defined an implementation-defined facility is defined in whole or in part by an external source to this specification 4.4.3 host-defined same as implementation-defined Note Editorially, see clause 4.2 . 4.4.4 type set of data values as defined in clause 6 4.4.5 primitive value member of one of the types Undefined, Null, Boolean, Number, BigInt, Symbol, or String as defined in clause 6 Note A primitive value is a datum that is represented directly at the lowest level of the language implementation. 4.4.6 object member of the type Object Note An object is a collection of properties and has a single prototype object. The prototype may be the null value. 4.4.7 constructor function object that creates and initializes objects Note The value of a constructor 's "prototype" property is a prototype object that is used to implement inheritance and shared properties. 4.4.8 prototype object that provides shared properties for other objects Note When a constructor creates an object, that object implicitly references the constructor 's "prototype" property for the purpose of resolving property references. The constructor 's "prototype" property can be referenced by the program expression constructor .prototype , and properties added to an object's prototype are shared, through inheritance, by all objects sharing the prototype. Alternatively, a new object may be created with an explicitly specified prototype by using the Object.create built-in function. 4.4.9 ordinary object object that has the default behaviour for the essential internal methods that must be supported by all objects 4.4.10 exotic object object that does not have the default behaviour for one or more of the essential internal methods Note Any object that is not an ordinary object is an exotic object . 4.4.11 standard object object whose semantics are defined by this specification 4.4.12 built-in object object specified and supplied by an ECMAScript implementation Note Standard built-in objects are defined in this specification. An ECMAScript implementation may specify and supply additional kinds of built-in objects. A built-in constructor is a built-in object that is also a constructor . 4.4.13 undefined value primitive value used when a variable has not been assigned a value 4.4.14 Undefined type type whose sole value is the undefined value 4.4.15 null value primitive value that represents the intentional absence of any object value 4.4.16 Null type type whose sole value is the null value 4.4.17 Boolean value member of the Boolean type Note There are only two Boolean values, true and false . 4.4.18 Boolean type type consisting of the primitive values true and false 4.4.19 Boolean object member of the Object type that is an instance of the standard built-in Boolean constructor Note A Boolean object is created by using the Boolean constructor in a new expression, supplying a Boolean value as an argument. The resulting object has an internal slot whose value is the Boolean value. A Boolean object can be coerced to a Boolean value. 4.4.20 String value primitive value that is a finite ordered sequence of zero or more 16-bit unsigned integer values Note A String value is a member of the String type. Each integer value in the sequence usually represents a single 16-bit unit of UTF-16 text. However, ECMAScript does not place any restrictions or requirements on the values except that they must be 16-bit unsigned integers. 4.4.21 String type set of all possible String values 4.4.22 String object member of the Object type that is an instance of the standard built-in String constructor Note A String object is created by using the String constructor in a new expression, supplying a String value as an argument. The resulting object has an internal slot whose value is the String value. A String object can be coerced to a String value by calling the String constructor as a function ( 21.1.1.1 ). 4.4.23 Number value primitive value corresponding to a double-precision 64-bit binary format IEEE 754-2019 value Note A Number value is a member of the Number type and is a direct representation of a number. 4.4.24 Number type set of all possible Number values including the special “Not-a-Number” (NaN) value, positive infinity, and negative infinity 4.4.25 Number object member of the Object type that is an instance of the standard built-in Number constructor Note A Number object is created by using the Number constructor in a new expression, supplying a Number value as an argument. The resulting object has an internal slot whose value is the Number value . A Number object can be coerced to a Number value by calling the Number constructor as a function ( 20.1.1.1 ). 4.4.26 Infinity Number value that is the positive infinite Number value 4.4.27 NaN Number value that is an IEEE 754-2019 “Not-a-Number” value 4.4.28 BigInt value primitive value corresponding to an arbitrary-precision integer value 4.4.29 BigInt type set of all possible BigInt values 4.4.30 BigInt object member of the Object type that is an instance of the standard built-in BigInt constructor 4.4.31 Symbol value primitive value that represents a unique, non-String Object property key 4.4.32 Symbol type set of all possible Symbol values 4.4.33 Symbol object member of the Object type that is an instance of the standard built-in Symbol constructor 4.4.34 function member of the Object type that may be invoked as a subroutine Note In addition to its properties, a function contains executable code and state that determine how it behaves when invoked. A function's code may or may not be written in ECMAScript. 4.4.35 built-in function built-in object that is a function Note Examples of built-in functions include parseInt and Math.exp . A host or implementation may provide additional built-in functions that are not described in this specification. 4.4.36 property part of an object that associates a key (either a String value or a Symbol value) and a value Note Depending upon the form of the property the value may be represented either directly as a data value (a primitive value, an object, or a function object ) or indirectly by a pair of accessor functions. 4.4.37 method function that is the value of a property Note When a function is called as a method of an object, the object is passed to the function as its this value. 4.4.38 built-in method method that is a built-in function Note Standard built-in methods are defined in this specification. A host or implementation may provide additional built-in methods that are not described in this specification. 4.4.39 attribute internal value that defines some characteristic of a property 4.4.40 own property property that is directly contained by its object 4.4.41 inherited property property of an object that is not an own property but is a property (either own or inherited) of the object's prototype 4.5 Organization of This Specification The remainder of this specification is organized as follows: Clause 5 defines the notational conventions used throughout the specification. Clauses 6 through 9 define the execution environment within which ECMAScript programs operate. Clauses 10 through 16 define the actual ECMAScript programming language including its syntactic encoding and the execution semantics of all language features. Clauses 17 through 27 define the ECMAScript standard library. They include the definitions of all of the standard objects that are available for use by ECMAScript programs as they execute. Clause 28 describes the memory consistency model of accesses on SharedArrayBuffer-backed memory and methods of the Atomics object.

25 Managing Memory 25.1 WeakRef Objects A WeakRef is an object that is used to refer to a target object without preserving it from garbage collection. WeakRefs can be dereferenced to allow access to the target object, if the target object hasn't been reclaimed by garbage collection. 25.1.1 The WeakRef Constructor The WeakRef constructor : is %WeakRef%.

is the initial value of the "WeakRef" property of the global object .

property of the . creates and initializes a new WeakRef object when called as a constructor .

. is not intended to be called as a function and will throw an exception when called in that manner.

is designed to be subclassable. It may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified WeakRef behaviour must include a super call to the WeakRef constructor to create and initialize the subclass instance with the internal state necessary to support the WeakRef.prototype built-in methods. 25.1.1.1 WeakRef ( target ) When the WeakRef function is called with argument target , the following steps are taken: If NewTarget is undefined , throw a TypeError exception. If Type ( target ) is not Object, throw a TypeError exception. Let weakRef be ? OrdinaryCreateFromConstructor (NewTarget, "%WeakRef.prototype%" , « [[WeakRefTarget]] »). Perform ! AddToKeptObjects ( target ). Set weakRef .[[WeakRefTarget]] to target . Return weakRef . 25.1.2 Properties of the WeakRef Constructor The WeakRef constructor : has a [[Prototype]] internal slot whose value is %Function.prototype% .

. has the following properties: 25.1.2.1 WeakRef.prototype The initial value of WeakRef.prototype is the intrinsic %WeakRef.prototype% object. This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: false }. 25.1.3 Properties of the WeakRef Prototype Object The WeakRef prototype object: is %WeakRef.prototype% .

. has a [[Prototype]] internal slot whose value is %Object.prototype% .

. is an ordinary object .

. does not have a [[WeakRefTarget]] internal slot. 25.1.3.1 WeakRef.prototype.constructor The initial value of WeakRef.prototype.constructor is % WeakRef %. This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: true }. 25.1.3.2 WeakRef.prototype.deref ( ) The following steps are taken: Let weakRef be the this value. Perform ? RequireInternalSlot ( weakRef , [[WeakRefTarget]]). Return ! WeakRefDeref ( weakRef ). Note If the WeakRef returns a target Object that is not undefined , then this target object should not be garbage collected until the current execution of ECMAScript code has completed. The AddToKeptObjects operation makes sure read consistency is maintained. target = { foo : function ( ) {} }; let weakRef = new WeakRef(target); ... later ... if (weakRef.deref()) { weakRef.deref().foo(); } In the above example, if the first deref does not evaluate to undefined then the second deref cannot either. 25.1.3.3 WeakRef.prototype [ @@toStringTag ] The initial value of the @@toStringTag property is the String value "WeakRef" . This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: true }. 25.1.4 WeakRef Abstract Operations 25.1.4.1 WeakRefDeref ( weakRef ) The abstract operation WeakRefDeref takes argument weakRef (a WeakRef ). It performs the following steps when called: Let target be weakRef .[[WeakRefTarget]]. If target is not empty , then Perform ! AddToKeptObjects ( target ). Return target . Return undefined . Note This abstract operation is defined separately from WeakRef.prototype.deref strictly to make it possible to succinctly define liveness. 25.1.5 Properties of WeakRef Instances WeakRef instances are ordinary objects that inherit properties from the WeakRef prototype. WeakRef instances also have a [[WeakRefTarget]] internal slot. 25.2 FinalizationRegistry Objects A FinalizationRegistry is an object that manages registration and unregistration of cleanup operations that are performed when target objects are garbage collected. 25.2.1 The FinalizationRegistry Constructor The FinalizationRegistry constructor : is %FinalizationRegistry% .

. is the initial value of the "FinalizationRegistry" property of the global object .

property of the . creates and initializes a new FinalizationRegistry object when called as a constructor .

. is not intended to be called as a function and will throw an exception when called in that manner.

is designed to be subclassable. It may be used as the value in an extends clause of a class definition. Subclass constructors that intend to inherit the specified FinalizationRegistry behaviour must include a super call to the FinalizationRegistry constructor to create and initialize the subclass instance with the internal state necessary to support the FinalizationRegistry.prototype built-in methods. 25.2.1.1 FinalizationRegistry ( cleanupCallback ) When the FinalizationRegistry function is called with argument cleanupCallback , the following steps are taken: If NewTarget is undefined , throw a TypeError exception. If IsCallable ( cleanupCallback ) is false , throw a TypeError exception. Let finalizationRegistry be ? OrdinaryCreateFromConstructor (NewTarget, "%FinalizationRegistry.prototype%" , « [[Realm]], [[CleanupCallback]], [[Cells]] »). Let fn be the active function object . Set finalizationRegistry .[[Realm]] to fn .[[Realm]]. Set finalizationRegistry .[[CleanupCallback]] to cleanupCallback . Set finalizationRegistry .[[Cells]] to a new empty List . Return finalizationRegistry . 25.2.2 Properties of the FinalizationRegistry Constructor The FinalizationRegistry constructor : has a [[Prototype]] internal slot whose value is %Function.prototype% .

. has the following properties: 25.2.2.1 FinalizationRegistry.prototype The initial value of FinalizationRegistry.prototype is the intrinsic %FinalizationRegistry.prototype% object. This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: false }. 25.2.3 Properties of the FinalizationRegistry Prototype Object The FinalizationRegistry prototype object: is %FinalizationRegistry.prototype% .

. has a [[Prototype]] internal slot whose value is %Object.prototype% .

. is an ordinary object .

. does not have [[Cells]] and [[CleanupCallback]] internal slots. 25.2.3.1 FinalizationRegistry.prototype.constructor The initial value of FinalizationRegistry.prototype.constructor is %FinalizationRegistry% . 25.2.3.2 FinalizationRegistry.prototype.register ( target , heldValue [ , unregisterToken ] ) The following steps are taken: Let finalizationRegistry be the this value. Perform ? RequireInternalSlot ( finalizationRegistry , [[Cells]]). If Type ( target ) is not Object, throw a TypeError exception. If SameValue ( target , heldValue ) is true , throw a TypeError exception. If Type ( unregisterToken ) is not Object, then If unregisterToken is not undefined , throw a TypeError exception. Set unregisterToken to empty . Let cell be the Record { [[WeakRefTarget]]: target , [[HeldValue]]: heldValue , [[UnregisterToken]]: unregisterToken }. Append cell to finalizationRegistry .[[Cells]]. Return undefined . Note Based on the algorithms and definitions in this specification, cell .[[HeldValue]] is live when cell is in finalizationRegistry .[[Cells]]; however, this does not necessarily mean that cell .[[UnregisterToken]] or cell .[[Target]] are live . For example, registering an object with itself as its unregister token would not keep the object alive forever. 25.2.3.3 FinalizationRegistry.prototype.unregister ( unregisterToken ) The following steps are taken: Let finalizationRegistry be the this value. Perform ? RequireInternalSlot ( finalizationRegistry , [[Cells]]). If Type ( unregisterToken ) is not Object, throw a TypeError exception. Let removed be false . For each Record { [[WeakRefTarget]], [[HeldValue]], [[UnregisterToken]] } cell of finalizationRegistry .[[Cells]], do If cell .[[UnregisterToken]] is not empty and SameValue ( cell .[[UnregisterToken]], unregisterToken ) is true , then Remove cell from finalizationRegistry .[[Cells]]. Set removed to true . Return removed . 25.2.3.4 FinalizationRegistry.prototype [ @@toStringTag ] The initial value of the @@toStringTag property is the String value "FinalizationRegistry" . This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: true }. 25.2.4 Properties of FinalizationRegistry Instances FinalizationRegistry instances are ordinary objects that inherit properties from the FinalizationRegistry prototype. FinalizationRegistry instances also have [[Cells]] and [[CleanupCallback]] internal slots.

27 Reflection 27.1 The Reflect Object The Reflect object: is %Reflect% .

. is the initial value of the "Reflect" property of the global object .

property of the . is an ordinary object .

. has a [[Prototype]] internal slot whose value is %Object.prototype% .

. is not a function object .

. does not have a [[Construct]] internal method; it cannot be used as a constructor with the new operator.

with the operator. does not have a [[Call]] internal method; it cannot be invoked as a function. 27.1.1 Reflect.apply ( target , thisArgument , argumentsList ) When the apply function is called with arguments target , thisArgument , and argumentsList , the following steps are taken: If IsCallable ( target ) is false , throw a TypeError exception. Let args be ? CreateListFromArrayLike ( argumentsList ). Perform PrepareForTailCall (). Return ? Call ( target , thisArgument , args ). 27.1.2 Reflect.construct ( target , argumentsList [ , newTarget ] ) When the construct function is called with arguments target , argumentsList , and newTarget , the following steps are taken: If IsConstructor ( target ) is false , throw a TypeError exception. If newTarget is not present, set newTarget to target . Else if IsConstructor ( newTarget ) is false , throw a TypeError exception. Let args be ? CreateListFromArrayLike ( argumentsList ). Return ? Construct ( target , args , newTarget ). 27.1.3 Reflect.defineProperty ( target , propertyKey , attributes ) When the defineProperty function is called with arguments target , propertyKey , and attributes , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). Let desc be ? ToPropertyDescriptor ( attributes ). Return ? target .[[DefineOwnProperty]]( key , desc ). 27.1.4 Reflect.deleteProperty ( target , propertyKey ) When the deleteProperty function is called with arguments target and propertyKey , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). Return ? target .[[Delete]]( key ). 27.1.5 Reflect.get ( target , propertyKey [ , receiver ] ) When the get function is called with arguments target , propertyKey , and receiver , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). If receiver is not present, then Set receiver to target . Return ? target .[[Get]]( key , receiver ). 27.1.6 Reflect.getOwnPropertyDescriptor ( target , propertyKey ) When the getOwnPropertyDescriptor function is called with arguments target and propertyKey , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). Let desc be ? target .[[GetOwnProperty]]( key ). Return FromPropertyDescriptor ( desc ). 27.1.7 Reflect.getPrototypeOf ( target ) When the getPrototypeOf function is called with argument target , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Return ? target .[[GetPrototypeOf]](). 27.1.8 Reflect.has ( target , propertyKey ) When the has function is called with arguments target and propertyKey , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). Return ? target .[[HasProperty]]( key ). 27.1.9 Reflect.isExtensible ( target ) When the isExtensible function is called with argument target , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Return ? target .[[IsExtensible]](). 27.1.10 Reflect.ownKeys ( target ) When the ownKeys function is called with argument target , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let keys be ? target .[[OwnPropertyKeys]](). Return CreateArrayFromList ( keys ). 27.1.11 Reflect.preventExtensions ( target ) When the preventExtensions function is called with argument target , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Return ? target .[[PreventExtensions]](). 27.1.12 Reflect.set ( target , propertyKey , V [ , receiver ] ) When the set function is called with arguments target , V , propertyKey , and receiver , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. Let key be ? ToPropertyKey ( propertyKey ). If receiver is not present, then Set receiver to target . Return ? target .[[Set]]( key , V , receiver ). 27.1.13 Reflect.setPrototypeOf ( target , proto ) When the setPrototypeOf function is called with arguments target and proto , the following steps are taken: If Type ( target ) is not Object, throw a TypeError exception. If Type ( proto ) is not Object and proto is not null , throw a TypeError exception. Return ? target .[[SetPrototypeOf]]( proto ). 27.1.14 Reflect [ @@toStringTag ] The initial value of the @@toStringTag property is the String value "Reflect" . This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: true }. 27.2 Proxy Objects 27.2.1 The Proxy Constructor The Proxy constructor : is %Proxy% .

. is the initial value of the "Proxy" property of the global object .

property of the . creates and initializes a new Proxy exotic object when called as a constructor .

when called as a . is not intended to be called as a function and will throw an exception when called in that manner. 27.2.1.1 Proxy ( target , handler ) When Proxy is called with arguments target and handler , it performs the following steps: If NewTarget is undefined , throw a TypeError exception. Return ? ProxyCreate ( target , handler ). 27.2.2 Properties of the Proxy Constructor The Proxy constructor : has a [[Prototype]] internal slot whose value is %Function.prototype% .

. does not have a "prototype" property because Proxy exotic objects do not have a [[Prototype]] internal slot that requires initialization.

property because Proxy exotic objects do not have a [[Prototype]] internal slot that requires initialization. has the following properties: 27.2.2.1 Proxy.revocable ( target , handler ) The Proxy.revocable function is used to create a revocable Proxy object. When Proxy.revocable is called with arguments target and handler , the following steps are taken: Let p be ? ProxyCreate ( target , handler ). Let steps be the algorithm steps defined in Proxy Revocation Functions . Let revoker be ! CreateBuiltinFunction ( steps , « [[RevocableProxy]] »). Set revoker .[[RevocableProxy]] to p . Let result be ! OrdinaryObjectCreate ( %Object.prototype% ). Perform ! CreateDataPropertyOrThrow ( result , "proxy" , p ). Perform ! CreateDataPropertyOrThrow ( result , "revoke" , revoker ). Return result . 27.2.2.1.1 Proxy Revocation Functions A Proxy revocation function is an anonymous built-in function that has the ability to invalidate a specific Proxy object. Each Proxy revocation function has a [[RevocableProxy]] internal slot. When a Proxy revocation function is called, the following steps are taken: Let F be the active function object . Let p be F .[[RevocableProxy]]. If p is null , return undefined . Set F .[[RevocableProxy]] to null . Assert : p is a Proxy object. Set p .[[ProxyTarget]] to null . Set p .[[ProxyHandler]] to null . Return undefined . The "length" property of a Proxy revocation function is 0. 27.3 Module Namespace Objects A Module Namespace Object is a module namespace exotic object that provides runtime property-based access to a module's exported bindings. There is no constructor function for Module Namespace Objects. Instead, such an object is created for each module that is imported by an ImportDeclaration that includes a NameSpaceImport . In addition to the properties specified in 9.4.6 each Module Namespace Object has the following own property: 27.3.1 @@toStringTag The initial value of the @@toStringTag property is the String value "Module" . This property has the attributes { [[Writable]]: false , [[Enumerable]]: false , [[Configurable]]: false }.

E Corrections and Clarifications in ECMAScript 2015 with Possible Compatibility Impact 8.1.1.4.15 - 8.1.1.4.18 Edition 5 and 5.1 used a property existence test to determine whether a global object property corresponding to a new global declaration already existed. ECMAScript 2015 uses an own property existence test. This corresponds to what has been most commonly implemented by web browsers. 9.4.2.1 : The 5th Edition moved the capture of the current array length prior to the integer conversion of the array index or new length value. However, the captured length value could become invalid if the conversion process has the side-effect of changing the array length. ECMAScript 2015 specifies that the current array length must be captured after the possible occurrence of such side-effects. 20.4.1.14 : Previous editions permitted the TimeClip abstract operation to return either +0 or -0 as the representation of a 0 time value . ECMAScript 2015 specifies that +0 always returned. This means that for ECMAScript 2015 the time value of a Date object is never observably -0 and methods that return time values never return -0 . 20.4.1.15 : If a UTC offset representation is not present, the local time zone is used. Edition 5.1 incorrectly stated that a missing time zone should be interpreted as "z" . 20.4.4.36 : If the year cannot be represented using the Date Time String Format specified in 20.4.1.15 a RangeError exception is thrown. Previous editions did not specify the behaviour for that case. 20.4.4.41 : Previous editions did not specify the value returned by Date.prototype.toString when this time value is NaN . ECMAScript 2015 specifies the result to be the String value "Invalid Date" . 21.2.3.1 , 21.2.3.2.5 : Any LineTerminator code points in the value of the "source" property of a RegExp instance must be expressed using an escape sequence. Edition 5.1 only required the escaping of / . 21.2.5.7 , 21.2.5.10 : In previous editions, the specifications for String.prototype.match and String.prototype.replace was incorrect for cases where the pattern argument was a RegExp value whose global flag is set. The previous specifications stated that for each attempt to match the pattern, if lastIndex did not change it should be incremented by 1. The correct behaviour is that lastIndex should be incremented by one only if the pattern matched the empty String. 22.1.3.27 , 22.1.3.27.1 : Previous editions did not specify how a NaN value returned by a comparefn was interpreted by Array.prototype.sort . ECMAScript 2015 specifies that such as value is treated as if +0 was returned from the comparefn . ECMAScript 2015 also specifies that ToNumber is applied to the result returned by a comparefn . In previous editions, the effect of a comparefn result that is not a Number value was implementation-defined . In practice, implementations call ToNumber .

G Colophon This specification is authored on GitHub in a plaintext source format called Ecmarkup. Ecmarkup is an HTML and Markdown dialect that provides a framework and toolset for authoring ECMAScript specifications in plaintext and processing the specification into a full-featured HTML rendering that follows the editorial conventions for this document. Ecmarkup builds on and integrates a number of other formats and technologies including Grammarkdown for defining syntax and Ecmarkdown for authoring algorithm steps. PDF renderings of this specification are produced by printing the HTML rendering to a PDF. Prior editions of this specification were authored using Word—the Ecmarkup source text that formed the basis of this edition was produced by converting the ECMAScript 2015 Word document to Ecmarkup using an automated conversion tool.

H Bibliography IEEE 754-2019 : IEEE Standard for Floating-Point Arithmetic. Institute of Electrical and Electronic Engineers, New York (2019) Note There are no normative changes between IEEE 754-2008 and IEEE 754-2019 that affect the ECMA-262 specification. The Unicode Standard, available at <https://unicode.org/versions/latest> Unicode Technical Note #5: Canonical Equivalence in Applications, available at <https://unicode.org/notes/tn5/> Unicode Technical Standard #10: Unicode Collation Algorithm, available at <https://unicode.org/reports/tr10/> Unicode Standard Annex #15, Unicode Normalization Forms, available at <https://unicode.org/reports/tr15/> Unicode Standard Annex #18: Unicode Regular Expressions, available at <https://unicode.org/reports/tr18/> Unicode Standard Annex #24: Unicode Script Property, available at <https://unicode.org/reports/tr24/> Unicode Standard Annex #31, Unicode Identifiers and Pattern Syntax, available at <https://unicode.org/reports/tr31/> Unicode Standard Annex #44: Unicode Character Database, available at <https://unicode.org/reports/tr44/> Unicode Technical Standard #51: Unicode Emoji, available at <https://unicode.org/reports/tr51/> IANA Time Zone Database, available at <https://www.iana.org/time-zones> ISO 8601:2004(E) Data elements and interchange formats — Information interchange — Representation of dates and times RFC 1738 “Uniform Resource Locators (URL)”, available at <https://tools.ietf.org/html/rfc1738> RFC 2396 “Uniform Resource Identifiers (URI): Generic Syntax”, available at <https://tools.ietf.org/html/rfc2396> RFC 3629 “UTF-8, a transformation format of ISO 10646”, available at <https://tools.ietf.org/html/rfc3629> RFC 7231 “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content”, available at <https://tools.ietf.org/html/rfc7231>