ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

9.1 Environment Records

Environment Record is a specification type used to define the association of Identifiers to specific variables and functions, based upon the lexical nesting structure of ECMAScript code. Usually an Environment Record is associated with some specific syntactic structure of ECMAScript code such as a FunctionDeclaration, a BlockStatement, or a Catch clause of a TryStatement. Each time such code is evaluated, a new Environment Record is created to record the identifier bindings that are created by that code.

Every Environment Record has an [[OuterEnv]] field, which is either null or a reference to an outer Environment Record. This is used to model the logical nesting of Environment Record values. The outer reference of an (inner) Environment Record is a reference to the Environment Record that logically surrounds the inner Environment Record. An outer Environment Record may, of course, have its own outer Environment Record. An Environment Record may serve as the outer environment for multiple inner Environment Records. For example, if a FunctionDeclaration contains two nested FunctionDeclarations then the Environment Records of each of the nested functions will have as their outer Environment Record the Environment Record of the current evaluation of the surrounding function.

Environment Records are purely specification mechanisms and need not correspond to any specific artefact of an ECMAScript implementation. It is impossible for an ECMAScript program to directly access or manipulate such values.

9.1.1 The Environment Record Type Hierarchy

Environment Records can be thought of as existing in a simple object-oriented hierarchy where Environment Record is an abstract class with three concrete subclasses: Declarative Environment Record, Object Environment Record, and Global Environment Record. Function Environment Records and Module Environment Records are subclasses of Declarative Environment Record.

The Environment Record abstract class includes the abstract specification methods defined in Table 16. These abstract methods have distinct concrete algorithms for each of the concrete subclasses.

Table 16: Abstract Methods of Environment Records
Method Purpose
HasBinding(N) Determine if an Environment Record has a binding for the String value N. Return true if it does and false if it does not.
CreateMutableBinding(N, D) Create a new but uninitialized mutable binding in an Environment Record. The String value N is the text of the bound name. If the Boolean argument D is true the binding may be subsequently deleted.
CreateImmutableBinding(N, S) Create a new but uninitialized immutable binding in an Environment Record. The String value N is the text of the bound name. If S is true then attempts to set it after it has been initialized will always throw an exception, regardless of the strict mode setting of operations that reference that binding.
InitializeBinding(N, V) Set the value of an already existing but uninitialized binding in an Environment Record. The String value N is the text of the bound name. V is the value for the binding and is a value of any ECMAScript language type.
SetMutableBinding(N, V, S) Set the value of an already existing mutable binding in an Environment Record. The String value N is the text of the bound name. V is the value for the binding and may be a value of any ECMAScript language type. S is a Boolean flag. If S is true and the binding cannot be set throw a TypeError exception.
GetBindingValue(N, S) Returns the value of an already existing binding from an Environment Record. The String value N is the text of the bound name. S is used to identify references originating in strict mode code or that otherwise require strict mode reference semantics. If S is true and the binding does not exist throw a ReferenceError exception. If the binding exists but is uninitialized a ReferenceError is thrown, regardless of the value of S.
DeleteBinding(N) Delete a binding from an Environment Record. The String value N is the text of the bound name. If a binding for N exists, remove the binding and return true. If the binding exists but cannot be removed return false. If the binding does not exist return true.
HasThisBinding() Determine if an Environment Record establishes a this binding. Return true if it does and false if it does not.
HasSuperBinding() Determine if an Environment Record establishes a super method binding. Return true if it does and false if it does not.
WithBaseObject() If this Environment Record is associated with a with statement, return the with object. Otherwise, return undefined.

9.1.1.1 Declarative Environment Records

Each Declarative Environment Record is associated with an ECMAScript program scope containing variable, constant, let, class, module, import, and/or function declarations. A Declarative Environment Record binds the set of identifiers defined by the declarations contained within its scope.

The behaviour of the concrete specification methods for Declarative Environment Records is defined by the following algorithms.

9.1.1.1.1 HasBinding ( N )

The HasBinding concrete method of a Declarative Environment Record envRec takes argument N (a String) and returns a normal completion containing a Boolean. It determines if the argument identifier is one of the identifiers bound by the record. It performs the following steps when called:

  1. If envRec has a binding for N, return true.
  2. Return false.

9.1.1.1.2 CreateMutableBinding ( N, D )

The CreateMutableBinding concrete method of a Declarative Environment Record envRec takes arguments N (a String) and D (a Boolean) and returns a normal completion containing unused. It creates a new mutable binding for the name N that is uninitialized. A binding must not already exist in this Environment Record for N. If D is true, the new binding is marked as being subject to deletion. It performs the following steps when called:

  1. Assert: envRec does not already have a binding for N.
  2. Create a mutable binding in envRec for N and record that it is uninitialized. If D is true, record that the newly created binding may be deleted by a subsequent DeleteBinding call.
  3. Return unused.

9.1.1.1.3 CreateImmutableBinding ( N, S )

The CreateImmutableBinding concrete method of a Declarative Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns a normal completion containing unused. It creates a new immutable binding for the name N that is uninitialized. A binding must not already exist in this Environment Record for N. If S is true, the new binding is marked as a strict binding. It performs the following steps when called:

  1. Assert: envRec does not already have a binding for N.
  2. Create an immutable binding in envRec for N and record that it is uninitialized. If S is true, record that the newly created binding is a strict binding.
  3. Return unused.

9.1.1.1.4 InitializeBinding ( N, V )

The InitializeBinding concrete method of a Declarative Environment Record envRec takes arguments N (a String) and V (an ECMAScript language value) and returns a normal completion containing unused. It is used to set the bound value of the current binding of the identifier whose name is N to the value V. An uninitialized binding for N must already exist. It performs the following steps when called:

  1. Assert: envRec must have an uninitialized binding for N.
  2. Set the bound value for N in envRec to V.
  3. Record that the binding for N in envRec has been initialized.
  4. Return unused.

9.1.1.1.5 SetMutableBinding ( N, V, S )

The SetMutableBinding concrete method of a Declarative Environment Record envRec takes arguments N (a String), V (an ECMAScript language value), and S (a Boolean) and returns either a normal completion containing unused or a throw completion. It attempts to change the bound value of the current binding of the identifier whose name is N to the value V. A binding for N normally already exists, but in rare cases it may not. If the binding is an immutable binding, a TypeError is thrown if S is true. It performs the following steps when called:

  1. If envRec does not have a binding for N, then
    1. If S is true, throw a ReferenceError exception.
    2. Perform ! envRec.CreateMutableBinding(N, true).
    3. Perform ! envRec.InitializeBinding(N, V).
    4. Return unused.
  2. If the binding for N in envRec is a strict binding, set S to true.
  3. If the binding for N in envRec has not yet been initialized, then
    1. Throw a ReferenceError exception.
  4. Else if the binding for N in envRec is a mutable binding, then
    1. Change its bound value to V.
  5. Else,
    1. Assert: This is an attempt to change the value of an immutable binding.
    2. If S is true, throw a TypeError exception.
  6. Return unused.
 Note

An example of ECMAScript code that results in a missing binding at step 1 is:

function f() { eval("var x; x = (delete x, 0);"); }

9.1.1.1.6 GetBindingValue ( N, S )

The GetBindingValue concrete method of a Declarative Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns either a normal completion containing an ECMAScript language value or a throw completion. It returns the value of its bound identifier whose name is N. If the binding exists but is uninitialized a ReferenceError is thrown, regardless of the value of S. It performs the following steps when called:

  1. Assert: envRec has a binding for N.
  2. If the binding for N in envRec is an uninitialized binding, throw a ReferenceError exception.
  3. Return the value currently bound to N in envRec.

9.1.1.1.7 DeleteBinding ( N )

The DeleteBinding concrete method of a Declarative Environment Record envRec takes argument N (a String) and returns a normal completion containing a Boolean. It can only delete bindings that have been explicitly designated as being subject to deletion. It performs the following steps when called:

  1. Assert: envRec has a binding for N.
  2. If the binding for N in envRec cannot be deleted, return false.
  3. Remove the binding for N from envRec.
  4. Return true.

9.1.1.1.8 HasThisBinding ( )

The HasThisBinding concrete method of a Declarative Environment Record envRec takes no arguments and returns false. It performs the following steps when called:

  1. Return false.
 Note

A regular Declarative Environment Record (i.e., one that is neither a Function Environment Record nor a Module Environment Record) does not provide a this binding.

9.1.1.1.9 HasSuperBinding ( )

The HasSuperBinding concrete method of a Declarative Environment Record envRec takes no arguments and returns false. It performs the following steps when called:

  1. Return false.
 Note

A regular Declarative Environment Record (i.e., one that is neither a Function Environment Record nor a Module Environment Record) does not provide a super binding.

9.1.1.1.10 WithBaseObject ( )

The WithBaseObject concrete method of a Declarative Environment Record envRec takes no arguments and returns undefined. It performs the following steps when called:

  1. Return undefined.

9.1.1.2 Object Environment Records

Each Object Environment Record is associated with an object called its binding object. An Object Environment Record binds the set of string identifier names that directly correspond to the property names of its binding object. Property keys that are not strings in the form of an IdentifierName are not included in the set of bound identifiers. Both own and inherited properties are included in the set regardless of the setting of their [[Enumerable]] attribute. Because properties can be dynamically added and deleted from objects, the set of identifiers bound by an Object Environment Record may potentially change as a side-effect of any operation that adds or deletes properties. Any bindings that are created as a result of such a side-effect are considered to be a mutable binding even if the Writable attribute of the corresponding property is false. Immutable bindings do not exist for Object Environment Records.

Object Environment Records created for with statements (14.11) can provide their binding object as an implicit this value for use in function calls. The capability is controlled by a Boolean [[IsWithEnvironment]] field.

Object Environment Records have the additional state fields listed in Table 17.

Table 17: Additional Fields of Object Environment Records
Field Name Value Meaning
[[BindingObject]] an Object The binding object of this Environment Record.
[[IsWithEnvironment]] a Boolean Indicates whether this Environment Record is created for a with statement.

The behaviour of the concrete specification methods for Object Environment Records is defined by the following algorithms.

9.1.1.2.1 HasBinding ( N )

The HasBinding concrete method of an Object Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It determines if its associated binding object has a property whose name is N. It performs the following steps when called:

  1. Let bindingObject be envRec.[[BindingObject]].
  2. Let foundBinding be ? HasProperty(bindingObject, N).
  3. If foundBinding is false, return false.
  4. If envRec.[[IsWithEnvironment]] is false, return true.
  5. Let unscopables be ? Get(bindingObject, @@unscopables).
  6. If unscopables is an Object, then
    1. Let blocked be ToBoolean(? Get(unscopables, N)).
    2. If blocked is true, return false.
  7. Return true.

9.1.1.2.2 CreateMutableBinding ( N, D )

The CreateMutableBinding concrete method of an Object Environment Record envRec takes arguments N (a String) and D (a Boolean) and returns either a normal completion containing unused or a throw completion. It creates in an Environment Record's associated binding object a property whose name is N and initializes it to the value undefined. If D is true, the new property's [[Configurable]] attribute is set to true; otherwise it is set to false. It performs the following steps when called:

  1. Let bindingObject be envRec.[[BindingObject]].
  2. Perform ? DefinePropertyOrThrow(bindingObject, N, PropertyDescriptor { [[Value]]: undefined, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: D }).
  3. Return unused.
 Note

Normally envRec will not have a binding for N but if it does, the semantics of DefinePropertyOrThrow may result in an existing binding being replaced or shadowed or cause an abrupt completion to be returned.

9.1.1.2.3 CreateImmutableBinding ( N, S )

The CreateImmutableBinding concrete method of an Object Environment Record is never used within this specification.

9.1.1.2.4 InitializeBinding ( N, V )

The InitializeBinding concrete method of an Object Environment Record envRec takes arguments N (a String) and V (an ECMAScript language value) and returns either a normal completion containing unused or a throw completion. It is used to set the bound value of the current binding of the identifier whose name is N to the value V. It performs the following steps when called:

  1. Perform ? envRec.SetMutableBinding(N, V, false).
  2. Return unused.
 Note

In this specification, all uses of CreateMutableBinding for Object Environment Records are immediately followed by a call to InitializeBinding for the same name. Hence, this specification does not explicitly track the initialization state of bindings in Object Environment Records.

9.1.1.2.5 SetMutableBinding ( N, V, S )

The SetMutableBinding concrete method of an Object Environment Record envRec takes arguments N (a String), V (an ECMAScript language value), and S (a Boolean) and returns either a normal completion containing unused or a throw completion. It attempts to set the value of the Environment Record's associated binding object's property whose name is N to the value V. A property named N normally already exists but if it does not or is not currently writable, error handling is determined by S. It performs the following steps when called:

  1. Let bindingObject be envRec.[[BindingObject]].
  2. Let stillExists be ? HasProperty(bindingObject, N).
  3. If stillExists is false and S is true, throw a ReferenceError exception.
  4. Perform ? Set(bindingObject, N, V, S).
  5. Return unused.

9.1.1.2.6 GetBindingValue ( N, S )

The GetBindingValue concrete method of an Object Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns either a normal completion containing an ECMAScript language value or a throw completion. It returns the value of its associated binding object's property whose name is N. The property should already exist but if it does not the result depends upon S. It performs the following steps when called:

  1. Let bindingObject be envRec.[[BindingObject]].
  2. Let value be ? HasProperty(bindingObject, N).
  3. If value is false, then
    1. If S is false, return undefined; otherwise throw a ReferenceError exception.
  4. Return ? Get(bindingObject, N).

9.1.1.2.7 DeleteBinding ( N )

The DeleteBinding concrete method of an Object Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It can only delete bindings that correspond to properties of the environment object whose [[Configurable]] attribute have the value true. It performs the following steps when called:

  1. Let bindingObject be envRec.[[BindingObject]].
  2. Return ? bindingObject.[[Delete]](N).

9.1.1.2.8 HasThisBinding ( )

The HasThisBinding concrete method of an Object Environment Record envRec takes no arguments and returns false. It performs the following steps when called:

  1. Return false.
 Note

Object Environment Records do not provide a this binding.

9.1.1.2.9 HasSuperBinding ( )

The HasSuperBinding concrete method of an Object Environment Record envRec takes no arguments and returns false. It performs the following steps when called:

  1. Return false.
 Note

Object Environment Records do not provide a super binding.

9.1.1.2.10 WithBaseObject ( )

The WithBaseObject concrete method of an Object Environment Record envRec takes no arguments and returns an Object or undefined. It performs the following steps when called:

  1. If envRec.[[IsWithEnvironment]] is true, return envRec.[[BindingObject]].
  2. Otherwise, return undefined.

9.1.1.3 Function Environment Records

A Function Environment Record is a Declarative Environment Record that is used to represent the top-level scope of a function and, if the function is not an ArrowFunction, provides a this binding. If a function is not an ArrowFunction function and references super, its Function Environment Record also contains the state that is used to perform super method invocations from within the function.

Function Environment Records have the additional state fields listed in Table 18.

Table 18: Additional Fields of Function Environment Records
Field Name Value Meaning
[[ThisValue]] an ECMAScript language value This is the this value used for this invocation of the function.
[[ThisBindingStatus]] lexical, initialized, or uninitialized If the value is lexical, this is an ArrowFunction and does not have a local this value.
[[FunctionObject]] an ECMAScript function object The function object whose invocation caused this Environment Record to be created.
[[NewTarget]] an Object or undefined If this Environment Record was created by the [[Construct]] internal method, [[NewTarget]] is the value of the [[Construct]] newTarget parameter. Otherwise, its value is undefined.

Function Environment Records support all of the Declarative Environment Record methods listed in Table 16 and share the same specifications for all of those methods except for HasThisBinding and HasSuperBinding. In addition, Function Environment Records support the methods listed in Table 19:

Table 19: Additional Methods of Function Environment Records
Method Purpose
BindThisValue(V) Set the [[ThisValue]] and record that it has been initialized.
GetThisBinding() Return the value of this Environment Record's this binding. Throws a ReferenceError if the this binding has not been initialized.
GetSuperBase() Return the object that is the base for super property accesses bound in this Environment Record. The value undefined indicates that such accesses will produce runtime errors.

The behaviour of the additional concrete specification methods for Function Environment Records is defined by the following algorithms:

9.1.1.3.1 BindThisValue ( V )

The BindThisValue concrete method of a Function Environment Record envRec takes argument V (an ECMAScript language value) and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Assert: envRec.[[ThisBindingStatus]] is not lexical.
  2. If envRec.[[ThisBindingStatus]] is initialized, throw a ReferenceError exception.
  3. Set envRec.[[ThisValue]] to V.
  4. Set envRec.[[ThisBindingStatus]] to initialized.
  5. Return V.

9.1.1.3.2 HasThisBinding ( )

The HasThisBinding concrete method of a Function Environment Record envRec takes no arguments and returns a Boolean. It performs the following steps when called:

  1. If envRec.[[ThisBindingStatus]] is lexical, return false; otherwise, return true.

9.1.1.3.3 HasSuperBinding ( )

The HasSuperBinding concrete method of a Function Environment Record envRec takes no arguments and returns a Boolean. It performs the following steps when called:

  1. If envRec.[[ThisBindingStatus]] is lexical, return false.
  2. If envRec.[[FunctionObject]].[[HomeObject]] is undefined, return false; otherwise, return true.

9.1.1.3.4 GetThisBinding ( )

The GetThisBinding concrete method of a Function Environment Record envRec takes no arguments and returns either a normal completion containing an ECMAScript language value or a throw completion. It performs the following steps when called:

  1. Assert: envRec.[[ThisBindingStatus]] is not lexical.
  2. If envRec.[[ThisBindingStatus]] is uninitialized, throw a ReferenceError exception.
  3. Return envRec.[[ThisValue]].

9.1.1.3.5 GetSuperBase ( )

The GetSuperBase concrete method of a Function Environment Record envRec takes no arguments and returns either a normal completion containing either an Object, null, or undefined, or a throw completion. It performs the following steps when called:

  1. Let home be envRec.[[FunctionObject]].[[HomeObject]].
  2. If home is undefined, return undefined.
  3. Assert: home is an Object.
  4. Return ? home.[[GetPrototypeOf]]().

9.1.1.4 Global Environment Records

A Global Environment Record is used to represent the outer most scope that is shared by all of the ECMAScript Script elements that are processed in a common realm. A Global Environment Record provides the bindings for built-in globals (clause 19), properties of the global object, and for all top-level declarations (8.2.9, 8.2.11) that occur within a Script.

A Global Environment Record is logically a single record but it is specified as a composite encapsulating an Object Environment Record and a Declarative Environment Record. The Object Environment Record has as its base object the global object of the associated Realm Record. This global object is the value returned by the Global Environment Record's GetThisBinding concrete method. The Object Environment Record component of a Global Environment Record contains the bindings for all built-in globals (clause 19) and all bindings introduced by a FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, AsyncGeneratorDeclaration, or VariableStatement contained in global code. The bindings for all other ECMAScript declarations in global code are contained in the Declarative Environment Record component of the Global Environment Record.

Properties may be created directly on a global object. Hence, the Object Environment Record component of a Global Environment Record may contain both bindings created explicitly by FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, AsyncGeneratorDeclaration, or VariableDeclaration declarations and bindings created implicitly as properties of the global object. In order to identify which bindings were explicitly created using declarations, a Global Environment Record maintains a list of the names bound using its CreateGlobalVarBinding and CreateGlobalFunctionBinding concrete methods.

Global Environment Records have the additional fields listed in Table 20 and the additional methods listed in Table 21.

Table 20: Additional Fields of Global Environment Records
Field Name Value Meaning
[[ObjectRecord]] an Object Environment Record Binding object is the global object. It contains global built-in bindings as well as FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, AsyncGeneratorDeclaration, and VariableDeclaration bindings in global code for the associated realm.
[[GlobalThisValue]] an Object The value returned by this in global scope. Hosts may provide any ECMAScript Object value.
[[DeclarativeRecord]] a Declarative Environment Record Contains bindings for all declarations in global code for the associated realm code except for FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, AsyncGeneratorDeclaration, and VariableDeclaration bindings.
[[VarNames]] a List of Strings The string names bound by FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, AsyncGeneratorDeclaration, and VariableDeclaration declarations in global code for the associated realm.
Table 21: Additional Methods of Global Environment Records
Method Purpose
GetThisBinding() Return the value of this Environment Record's this binding.
HasVarDeclaration (N) Determines if the argument identifier has a binding in this Environment Record that was created using a VariableDeclaration, FunctionDeclaration, GeneratorDeclaration, AsyncFunctionDeclaration, or AsyncGeneratorDeclaration.
HasLexicalDeclaration (N) Determines if the argument identifier has a binding in this Environment Record that was created using a lexical declaration such as a LexicalDeclaration or a ClassDeclaration.
HasRestrictedGlobalProperty (N) Determines if the argument is the name of a global object property that may not be shadowed by a global lexical binding.
CanDeclareGlobalVar (N) Determines if a corresponding CreateGlobalVarBinding call would succeed if called for the same argument N.
CanDeclareGlobalFunction (N) Determines if a corresponding CreateGlobalFunctionBinding call would succeed if called for the same argument N.
CreateGlobalVarBinding(N, D) Used to create and initialize to undefined a global var binding in the [[ObjectRecord]] component of a Global Environment Record. The binding will be a mutable binding. The corresponding global object property will have attribute values appropriate for a var. The String value N is the bound name. If D is true, the binding may be deleted. Logically equivalent to CreateMutableBinding followed by a SetMutableBinding but it allows var declarations to receive special treatment.
CreateGlobalFunctionBinding(N, V, D) Create and initialize a global function binding in the [[ObjectRecord]] component of a Global Environment Record. The binding will be a mutable binding. The corresponding global object property will have attribute values appropriate for a function. The String value N is the bound name. V is the initialization value. If the Boolean argument D is true, the binding may be deleted. Logically equivalent to CreateMutableBinding followed by a SetMutableBinding but it allows function declarations to receive special treatment.

The behaviour of the concrete specification methods for Global Environment Records is defined by the following algorithms.

9.1.1.4.1 HasBinding ( N )

The HasBinding concrete method of a Global Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It determines if the argument identifier is one of the identifiers bound by the record. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, return true.
  3. Let ObjRec be envRec.[[ObjectRecord]].
  4. Return ? ObjRec.HasBinding(N).

9.1.1.4.2 CreateMutableBinding ( N, D )

The CreateMutableBinding concrete method of a Global Environment Record envRec takes arguments N (a String) and D (a Boolean) and returns either a normal completion containing unused or a throw completion. It creates a new mutable binding for the name N that is uninitialized. The binding is created in the associated DeclarativeRecord. A binding for N must not already exist in the DeclarativeRecord. If D is true, the new binding is marked as being subject to deletion. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, throw a TypeError exception.
  3. Return ! DclRec.CreateMutableBinding(N, D).

9.1.1.4.3 CreateImmutableBinding ( N, S )

The CreateImmutableBinding concrete method of a Global Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns either a normal completion containing unused or a throw completion. It creates a new immutable binding for the name N that is uninitialized. A binding must not already exist in this Environment Record for N. If S is true, the new binding is marked as a strict binding. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, throw a TypeError exception.
  3. Return ! DclRec.CreateImmutableBinding(N, S).

9.1.1.4.4 InitializeBinding ( N, V )

The InitializeBinding concrete method of a Global Environment Record envRec takes arguments N (a String) and V (an ECMAScript language value) and returns either a normal completion containing unused or a throw completion. It is used to set the bound value of the current binding of the identifier whose name is N to the value V. An uninitialized binding for N must already exist. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, then
    1. Return ! DclRec.InitializeBinding(N, V).
  3. Assert: If the binding exists, it must be in the Object Environment Record.
  4. Let ObjRec be envRec.[[ObjectRecord]].
  5. Return ? ObjRec.InitializeBinding(N, V).

9.1.1.4.5 SetMutableBinding ( N, V, S )

The SetMutableBinding concrete method of a Global Environment Record envRec takes arguments N (a String), V (an ECMAScript language value), and S (a Boolean) and returns either a normal completion containing unused or a throw completion. It attempts to change the bound value of the current binding of the identifier whose name is N to the value V. If the binding is an immutable binding and S is true, a TypeError is thrown. A property named N normally already exists but if it does not or is not currently writable, error handling is determined by S. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, then
    1. Return ? DclRec.SetMutableBinding(N, V, S).
  3. Let ObjRec be envRec.[[ObjectRecord]].
  4. Return ? ObjRec.SetMutableBinding(N, V, S).

9.1.1.4.6 GetBindingValue ( N, S )

The GetBindingValue concrete method of a Global Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns either a normal completion containing an ECMAScript language value or a throw completion. It returns the value of its bound identifier whose name is N. If the binding is an uninitialized binding throw a ReferenceError exception. A property named N normally already exists but if it does not or is not currently writable, error handling is determined by S. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, then
    1. Return ? DclRec.GetBindingValue(N, S).
  3. Let ObjRec be envRec.[[ObjectRecord]].
  4. Return ? ObjRec.GetBindingValue(N, S).

9.1.1.4.7 DeleteBinding ( N )

The DeleteBinding concrete method of a Global Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It can only delete bindings that have been explicitly designated as being subject to deletion. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. If ! DclRec.HasBinding(N) is true, then
    1. Return ! DclRec.DeleteBinding(N).
  3. Let ObjRec be envRec.[[ObjectRecord]].
  4. Let globalObject be ObjRec.[[BindingObject]].
  5. Let existingProp be ? HasOwnProperty(globalObject, N).
  6. If existingProp is true, then
    1. Let status be ? ObjRec.DeleteBinding(N).
    2. If status is true and envRec.[[VarNames]] contains N, then
      1. Remove N from envRec.[[VarNames]].
    3. Return status.
  7. Return true.

9.1.1.4.8 HasThisBinding ( )

The HasThisBinding concrete method of a Global Environment Record envRec takes no arguments and returns true. It performs the following steps when called:

  1. Return true.
 Note

Global Environment Records always provide a this binding.

9.1.1.4.9 HasSuperBinding ( )

The HasSuperBinding concrete method of a Global Environment Record envRec takes no arguments and returns false. It performs the following steps when called:

  1. Return false.
 Note

Global Environment Records do not provide a super binding.

9.1.1.4.10 WithBaseObject ( )

The WithBaseObject concrete method of a Global Environment Record envRec takes no arguments and returns undefined. It performs the following steps when called:

  1. Return undefined.

9.1.1.4.11 GetThisBinding ( )

The GetThisBinding concrete method of a Global Environment Record envRec takes no arguments and returns a normal completion containing an Object. It performs the following steps when called:

  1. Return envRec.[[GlobalThisValue]].

9.1.1.4.12 HasVarDeclaration ( N )

The HasVarDeclaration concrete method of a Global Environment Record envRec takes argument N (a String) and returns a Boolean. It determines if the argument identifier has a binding in this record that was created using a VariableStatement or a FunctionDeclaration. It performs the following steps when called:

  1. Let varDeclaredNames be envRec.[[VarNames]].
  2. If varDeclaredNames contains N, return true.
  3. Return false.

9.1.1.4.13 HasLexicalDeclaration ( N )

The HasLexicalDeclaration concrete method of a Global Environment Record envRec takes argument N (a String) and returns a Boolean. It determines if the argument identifier has a binding in this record that was created using a lexical declaration such as a LexicalDeclaration or a ClassDeclaration. It performs the following steps when called:

  1. Let DclRec be envRec.[[DeclarativeRecord]].
  2. Return ! DclRec.HasBinding(N).

9.1.1.4.14 HasRestrictedGlobalProperty ( N )

The HasRestrictedGlobalProperty concrete method of a Global Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It determines if the argument identifier is the name of a property of the global object that must not be shadowed by a global lexical binding. It performs the following steps when called:

  1. Let ObjRec be envRec.[[ObjectRecord]].
  2. Let globalObject be ObjRec.[[BindingObject]].
  3. Let existingProp be ? globalObject.[[GetOwnProperty]](N).
  4. If existingProp is undefined, return false.
  5. If existingProp.[[Configurable]] is true, return false.
  6. Return true.
 Note

Properties may exist upon a global object that were directly created rather than being declared using a var or function declaration. A global lexical binding may not be created that has the same name as a non-configurable property of the global object. The global property "undefined" is an example of such a property.

9.1.1.4.15 CanDeclareGlobalVar ( N )

The CanDeclareGlobalVar concrete method of a Global Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It determines if a corresponding CreateGlobalVarBinding call would succeed if called for the same argument N. Redundant var declarations and var declarations for pre-existing global object properties are allowed. It performs the following steps when called:

  1. Let ObjRec be envRec.[[ObjectRecord]].
  2. Let globalObject be ObjRec.[[BindingObject]].
  3. Let hasProperty be ? HasOwnProperty(globalObject, N).
  4. If hasProperty is true, return true.
  5. Return ? IsExtensible(globalObject).

9.1.1.4.16 CanDeclareGlobalFunction ( N )

The CanDeclareGlobalFunction concrete method of a Global Environment Record envRec takes argument N (a String) and returns either a normal completion containing a Boolean or a throw completion. It determines if a corresponding CreateGlobalFunctionBinding call would succeed if called for the same argument N. It performs the following steps when called:

  1. Let ObjRec be envRec.[[ObjectRecord]].
  2. Let globalObject be ObjRec.[[BindingObject]].
  3. Let existingProp be ? globalObject.[[GetOwnProperty]](N).
  4. If existingProp is undefined, return ? IsExtensible(globalObject).
  5. If existingProp.[[Configurable]] is true, return true.
  6. If IsDataDescriptor(existingProp) is true and existingProp has attribute values { [[Writable]]: true, [[Enumerable]]: true }, return true.
  7. Return false.

9.1.1.4.17 CreateGlobalVarBinding ( N, D )

The CreateGlobalVarBinding concrete method of a Global Environment Record envRec takes arguments N (a String) and D (a Boolean) and returns either a normal completion containing unused or a throw completion. It creates and initializes a mutable binding in the associated Object Environment Record and records the bound name in the associated [[VarNames]] List. If a binding already exists, it is reused and assumed to be initialized. It performs the following steps when called:

  1. Let ObjRec be envRec.[[ObjectRecord]].
  2. Let globalObject be ObjRec.[[BindingObject]].
  3. Let hasProperty be ? HasOwnProperty(globalObject, N).
  4. Let extensible be ? IsExtensible(globalObject).
  5. If hasProperty is false and extensible is true, then
    1. Perform ? ObjRec.CreateMutableBinding(N, D).
    2. Perform ? ObjRec.InitializeBinding(N, undefined).
  6. If envRec.[[VarNames]] does not contain N, then
    1. Append N to envRec.[[VarNames]].
  7. Return unused.

9.1.1.4.18 CreateGlobalFunctionBinding ( N, V, D )

The CreateGlobalFunctionBinding concrete method of a Global Environment Record envRec takes arguments N (a String), V (an ECMAScript language value), and D (a Boolean) and returns either a normal completion containing unused or a throw completion. It creates and initializes a mutable binding in the associated Object Environment Record and records the bound name in the associated [[VarNames]] List. If a binding already exists, it is replaced. It performs the following steps when called:

  1. Let ObjRec be envRec.[[ObjectRecord]].
  2. Let globalObject be ObjRec.[[BindingObject]].
  3. Let existingProp be ? globalObject.[[GetOwnProperty]](N).
  4. If existingProp is undefined or existingProp.[[Configurable]] is true, then
    1. Let desc be the PropertyDescriptor { [[Value]]: V, [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: D }.
  5. Else,
    1. Let desc be the PropertyDescriptor { [[Value]]: V }.
  6. Perform ? DefinePropertyOrThrow(globalObject, N, desc).
  7. Perform ? Set(globalObject, N, V, false).
  8. If envRec.[[VarNames]] does not contain N, then
    1. Append N to envRec.[[VarNames]].
  9. Return unused.
 Note

Global function declarations are always represented as own properties of the global object. If possible, an existing own property is reconfigured to have a standard set of attribute values. Step 7 is equivalent to what calling the InitializeBinding concrete method would do and if globalObject is a Proxy will produce the same sequence of Proxy trap calls.

9.1.1.5 Module Environment Records

A Module Environment Record is a Declarative Environment Record that is used to represent the outer scope of an ECMAScript Module. In additional to normal mutable and immutable bindings, Module Environment Records also provide immutable import bindings which are bindings that provide indirect access to a target binding that exists in another Environment Record.

Module Environment Records support all of the Declarative Environment Record methods listed in Table 16 and share the same specifications for all of those methods except for GetBindingValue, DeleteBinding, HasThisBinding and GetThisBinding. In addition, Module Environment Records support the methods listed in Table 22:

Table 22: Additional Methods of Module Environment Records
Method Purpose
CreateImportBinding(N, M, N2) Create an immutable indirect binding in a Module Environment Record. The String value N is the text of the bound name. M is a Module Record, and N2 is a binding that exists in M's Module Environment Record.
GetThisBinding() Return the value of this Environment Record's this binding.

The behaviour of the additional concrete specification methods for Module Environment Records are defined by the following algorithms:

9.1.1.5.1 GetBindingValue ( N, S )

The GetBindingValue concrete method of a Module Environment Record envRec takes arguments N (a String) and S (a Boolean) and returns either a normal completion containing an ECMAScript language value or a throw completion. It returns the value of its bound identifier whose name is N. However, if the binding is an indirect binding the value of the target binding is returned. If the binding exists but is uninitialized a ReferenceError is thrown. It performs the following steps when called:

  1. Assert: S is true.
  2. Assert: envRec has a binding for N.
  3. If the binding for N is an indirect binding, then
    1. Let M and N2 be the indirection values provided when this binding for N was created.
    2. Let targetEnv be M.[[Environment]].
    3. If targetEnv is empty, throw a ReferenceError exception.
    4. Return ? targetEnv.GetBindingValue(N2, true).
  4. If the binding for N in envRec is an uninitialized binding, throw a ReferenceError exception.
  5. Return the value currently bound to N in envRec.
 Note

S will always be true because a Module is always strict mode code.

9.1.1.5.2 DeleteBinding ( N )

The DeleteBinding concrete method of a Module Environment Record is never used within this specification.

Note

Module Environment Records are only used within strict code and an early error rule prevents the delete operator, in strict code, from being applied to a Reference Record that would resolve to a Module Environment Record binding. See 13.5.1.1.

9.1.1.5.3 HasThisBinding ( )

The HasThisBinding concrete method of a Module Environment Record envRec takes no arguments and returns true. It performs the following steps when called:

  1. Return true.
 Note

Module Environment Records always provide a this binding.

9.1.1.5.4 GetThisBinding ( )

The GetThisBinding concrete method of a Module Environment Record envRec takes no arguments and returns a normal completion containing undefined. It performs the following steps when called:

  1. Return undefined.

9.1.1.5.5 CreateImportBinding ( N, M, N2 )

The CreateImportBinding concrete method of a Module Environment Record envRec takes arguments N (a String), M (a Module Record), and N2 (a String) and returns unused. It creates a new initialized immutable indirect binding for the name N. A binding must not already exist in this Environment Record for N. N2 is the name of a binding that exists in M's Module Environment Record. Accesses to the value of the new binding will indirectly access the bound value of the target binding. It performs the following steps when called:

  1. Assert: envRec does not already have a binding for N.
  2. Assert: When M.[[Environment]] is instantiated, it will have a direct binding for N2.
  3. Create an immutable indirect binding in envRec for N that references M and N2 as its target binding and record that the binding is initialized.
  4. Return unused.

9.1.2 Environment Record Operations

The following abstract operations are used in this specification to operate upon Environment Records:

9.1.2.1 GetIdentifierReference ( env, name, strict )

The abstract operation GetIdentifierReference takes arguments env (an Environment Record or null), name (a String), and strict (a Boolean) and returns either a normal completion containing a Reference Record or a throw completion. It performs the following steps when called:

  1. If env is null, then
    1. Return the Reference Record { [[Base]]: unresolvable, [[ReferencedName]]: name, [[Strict]]: strict, [[ThisValue]]: empty }.
  2. Let exists be ? env.HasBinding(name).
  3. If exists is true, then
    1. Return the Reference Record { [[Base]]: env, [[ReferencedName]]: name, [[Strict]]: strict, [[ThisValue]]: empty }.
  4. Else,
    1. Let outer be env.[[OuterEnv]].
    2. Return ? GetIdentifierReference(outer, name, strict).

9.1.2.2 NewDeclarativeEnvironment ( E )

The abstract operation NewDeclarativeEnvironment takes argument E (an Environment Record or null) and returns a Declarative Environment Record. It performs the following steps when called:

  1. Let env be a new Declarative Environment Record containing no bindings.
  2. Set env.[[OuterEnv]] to E.
  3. Return env.

9.1.2.3 NewObjectEnvironment ( O, W, E )

The abstract operation NewObjectEnvironment takes arguments O (an Object), W (a Boolean), and E (an Environment Record or null) and returns an Object Environment Record. It performs the following steps when called:

  1. Let env be a new Object Environment Record.
  2. Set env.[[BindingObject]] to O.
  3. Set env.[[IsWithEnvironment]] to W.
  4. Set env.[[OuterEnv]] to E.
  5. Return env.

9.1.2.4 NewFunctionEnvironment ( F, newTarget )

The abstract operation NewFunctionEnvironment takes arguments F (an ECMAScript function object) and newTarget (an Object or undefined) and returns a Function Environment Record. It performs the following steps when called:

  1. Let env be a new Function Environment Record containing no bindings.
  2. Set env.[[FunctionObject]] to F.
  3. If F.[[ThisMode]] is lexical, set env.[[ThisBindingStatus]] to lexical.
  4. Else, set env.[[ThisBindingStatus]] to uninitialized.
  5. Set env.[[NewTarget]] to newTarget.
  6. Set env.[[OuterEnv]] to F.[[Environment]].
  7. Return env.

9.1.2.5 NewGlobalEnvironment ( G, thisValue )

The abstract operation NewGlobalEnvironment takes arguments G (an Object) and thisValue (an Object) and returns a Global Environment Record. It performs the following steps when called:

  1. Let objRec be NewObjectEnvironment(G, false, null).
  2. Let dclRec be NewDeclarativeEnvironment(null).
  3. Let env be a new Global Environment Record.
  4. Set env.[[ObjectRecord]] to objRec.
  5. Set env.[[GlobalThisValue]] to thisValue.
  6. Set env.[[DeclarativeRecord]] to dclRec.
  7. Set env.[[VarNames]] to a new empty List.
  8. Set env.[[OuterEnv]] to null.
  9. Return env.

9.1.2.6 NewModuleEnvironment ( E )

The abstract operation NewModuleEnvironment takes argument E (an Environment Record) and returns a Module Environment Record. It performs the following steps when called:

  1. Let env be a new Module Environment Record containing no bindings.
  2. Set env.[[OuterEnv]] to E.
  3. Return env.