Environment Records: how scope is specified

Names need a home

In JavaScript, two variables can have the same spelling but hold different values. The specification needs a way to say which one a read means. It uses Environment Records: specification-only records that associate names with bindings. A binding is the association for a name, including its value and whether that value is ready to read.

const user = "Asha";
{
  const user = "Sam";
  console.log(user);
}
console.log(user);

Line 1 stores Asha in an outer binding. Line 3 creates another user inside the braces. Line 4 logs Sam; line 6 logs Asha. The nearer binding wins only while that block is in scope.

You have already used the idea in scope and lexical environments, closures, and the temporal dead zone. Here we read the precise rules instead of reteaching those introductions. The preceding Reference type lesson explains what a resolved name produces; this one explains the record where lookup finds it.

Declarative Environment Records

A Declarative Environment Record directly stores names introduced by declarations. Think of a block with let and const: the two bindings belong to that block, not to a property bag on a JavaScript object. Function and module records are specialized declarative records.

let price = 3;
price = 4;
const order = "tea";
console.log(price, order);

Line 1 creates and initializes mutable price to 3. Line 2 changes it to 4. Line 3 initializes immutable order to tea. Line 4 prints 4 tea. Immutable means the binding cannot later be reassigned; it does not freeze objects stored in the binding.

The spec's declarative record also covers catch parameters and declarations in other lexical scopes. The important distinction is how names are stored: directly as bindings, not as properties of an arbitrary object. That distinction will matter for global code.

Creating and initializing bindings

Creating a lexical binding and giving it its first value are different spec actions. Uninitialized means a binding already exists but has no readable value. This is the source of the temporal dead zone (TDZ): reading the name before its declaration is evaluated throws a ReferenceError.

{
  try { console.log(price); }
  catch (error) { console.log(error.name); }
  let price = 3;
  console.log(price);
}

Line 2 tries to read price before its initializer runs, so the catch logs ReferenceError. Line 4 initializes the existing binding to 3. Line 5 then prints 3. The earlier read does not fall back to another outer name: the local binding was already found.

These are shortened, labeled excerpts of the specification's binding operations, not runnable JavaScript. In the actual declarative algorithms, CreateMutableBinding and CreateImmutableBinding both record an uninitialized name; InitializeBinding marks it initialized, and GetBindingValue checks that state before returning a value.

CreateMutableBinding("price", false): create an uninitialized mutable binding.
CreateImmutableBinding("user", true): create an uninitialized immutable binding.
InitializeBinding("price", 3): set its value and mark it initialized.
GetBindingValue("price", true): if uninitialized, throw ReferenceError; otherwise return its value.

The spec also has SetMutableBinding for later assignments. Do not mistake the first initialization for a later write: the first gives a reserved name its value, whereas a later assignment changes an initialized mutable binding. Read the normative declarative record algorithms alongside the runnable example.

Object Environment Records

An Object Environment Record looks up identifier names through an object's properties. A legacy with statement demonstrates this directly. It is banned in strict mode, so do not introduce it into new application code; its role here is to make the specification's object-backed record visible.

const order = { price: 3 };
with (order) {
  console.log(price);
}
console.log(order.price);

Line 1 creates an object with a price property. Line 2 starts a legacy with scope using that object. Line 3 prints 3, because the property supplies the name. Line 5 reads the property explicitly and also prints 3. The object is real; its Environment Record is a specification-only way to explain name lookup.

An object-backed record can see inherited properties too. Its set of available names can change when properties are added or removed. For with, Symbol.unscopables can exclude a property from name lookup. These extra rules are one reason to prefer clear order.price property access in everyday code.

Object records also appear inside the global record, but there the binding object is the global object, not this order. The same record kind serves two different contexts. The spec's object record rules describe the property lookup and the special with behavior.

The two parts of a global record

A Global Environment Record is one logical record with two components. Its object record uses the global object for top-level classic-script var and function declarations. Its declarative record holds top-level let, const, and class declarations. This distinction is for classic scripts, not modules.

var cart = "tea";
function checkout() { return cart; }
let price = 3;
const user = "Asha";
console.log(globalThis.cart, globalThis.checkout());
console.log(globalThis.price, globalThis.user);

Line 1 declares cart with var; line 2 declares checkout. Lines 3 and 4 declare lexical names. Line 5 prints tea tea through global-object properties; line 6 prints undefined undefined for globalThis.price and globalThis.user. Reading price by name still gives 3.

This example must run as a top-level classic script. Code wrapped by a bundler, function, or module is not the same test. The lesson test runs it in a fresh script context; its globalThis is that context's global object, not a browser window. In the browser editor, run the block as a script, not inside a module. Property access on a missing name returns undefined; it does not prove the lexical name is absent.

Global HasBinding(name): check [[DeclarativeRecord]] first.
If not found, check [[ObjectRecord]].
CreateGlobalVarBinding(name, deletable): create and initialize in [[ObjectRecord]].

HasBinding checks the declarative component first, then the object component. Special operations CreateGlobalVarBinding and CreateGlobalFunctionBinding put classic-script declarations in the object component. The spec details are in Global Environment Records.

Function records and this

A Function Environment Record belongs to one function invocation and holds top-level local bindings for that call. For a non-arrow function it can also provide this. Which object is passed as this depends on how the function is called. For the Reference side of that story, see the preceding lesson.

"use strict";
function showOrder() { return this.order; }
const cart = { order: "tea", showOrder };
console.log(cart.showOrder());
console.log(showOrder.call({ order: "coffee" }));

Line 1 enables strict mode so the example never relies on a fallback global this. Line 2 defines a function that reads its receiver's order. Line 3 places that function on cart. Line 4 logs tea; line 5 explicitly supplies another receiver with call and logs coffee. Each call gets its own function record.

const cart = {
  order: "tea",
  show() { return () => this.order; },
};
const readOrder = cart.show();
console.log(readOrder());

Line 2 supplies tea on cart. Line 3 returns an arrow from the method; the arrow does not create its own this binding. Line 5 calls show with cart as receiver. Line 6 prints tea even though the method call already returned, because the arrow can still use that invocation's this.

In the spec, HasThisBinding returns false for an arrow's lexical-this status, and true for an ordinary function record. GetThisEnvironment follows outer records until it finds one that supplies this. Function records also hold call-specific state needed for super and new.target; the next call-focused lesson goes deeper.

Module records and live imports

A Module Environment Record is a specialized declarative record for a module's top-level declarations and imports. An imported name is an indirect binding: it points to a binding in another module rather than storing a copied value. The importer cannot reassign that name, but the exporting module can change its own exported let.

export let price = 3;
export function changePrice() { price = 4; }

Line 1 exports price, initially 3. Line 2 exports changePrice, which can set that same binding to 4. This is a file to import, not a standalone classic-script snippet; the next block is its consumer.

import { price, changePrice } from "./cart.mjs";
console.log(price);
changePrice();
console.log(price);

Line 1 connects both imported names. Line 2 prints 3. Line 3 calls the exporter's function; line 4 prints 4. The test runs these as two actual Node module files, since a classic-script sandbox cannot execute a bare import. For a complete look at loading and linking, see module records.

CreateImportBinding(name, targetModule, targetName): create an immutable indirect binding.
GetBindingValue(name, true): for an indirect binding, read targetEnv.GetBindingValue(targetName, true).

CreateImportBinding stores a link to a target module and name. A later GetBindingValue asks the target environment for its current value. Modules have a global record as their outer environment, but their own top-level declarations belong to the module record; module top-level this is undefined. Read the module record rules to see those branches.

PrivateEnvironment Records

A PrivateEnvironment Record tracks the Private Names declared by a class, such as #price. It is similar in purpose to an Environment Record, but is a different specification mechanism. It does not map ordinary identifier names like price to normal variable bindings.

class Cart {
  #price = 3;
  total() { return this.#price; }
}
console.log(new Cart().total());

Line 1 starts the class. Line 2 declares its private field #price with value 3. Line 3 reads it in total; line 5 logs 3. An ordinary property named price would not be the same private name, and code outside the declaring class cannot spell cart.#price to read it.

NewPrivateEnvironment(outer): record [[OuterPrivateEnvironment]] and an empty [[Names]] list.
ResolvePrivateIdentifier(env, name): search [[Names]], then [[OuterPrivateEnvironment]].

Each private record has a [[Names]] list and a [[OuterPrivateEnvironment]] link for nested class cases. ResolvePrivateIdentifier searches those lists, not the ordinary [[OuterEnv]] chain. The spec makes this separate in its PrivateEnvironment Records section. You do not need to build these records by hand in app code.

Do not read #price as a string property that happens to begin with a hash. It is private syntax with a distinct identity. That is why a normal cart.price lookup cannot reach it. The record explains which class text owns the name; each object instance still has its own field value.

Following [[OuterEnv]]

Every ordinary Environment Record has [[OuterEnv]], a link to a logically enclosing record or null. ResolveBinding begins at the currently running code's lexical environment. It uses GetIdentifierReference to ask one record for a name; if missing, it follows that record's outer link.

const price = 3;
function checkout() {
  const order = "tea";
  console.log(order, price);
}
checkout();

Line 1 creates an outer price with value 3. Line 3 creates local order. Line 4 reads order locally and price from outside. Line 6 calls checkout, logging tea 3. The spec's lookup returns a Reference Record for the found binding, not the final value immediately.

ResolveBinding(name): start at the running context's LexicalEnvironment.
GetIdentifierReference(env, name, strict): ask env.HasBinding(name).
If found, return a Reference Record based on env.
Otherwise, try env.[[OuterEnv]]; at null, return an unresolvable Reference Record.

If no record owns the name, GetIdentifierReference returns an unresolvable Reference Record at null; reading that reference later can throw. If a nearer record owns an uninitialized name, lookup stops there and its value read throws instead. The distinction matters for the TDZ: searching outward would incorrectly reveal a shadowed outer name.

1const price = 3;Run2function checkout() {3  const order = "tea";4  return order + ": " + price;5}6console.log(checkout());

The replay calls the lesson's lookup model and shows its recorded snapshots. It does not pause JavaScript or inspect actual engine records. Step to the local order, then watch lookup follow the outer link for price. The printed result is tea: 3 in that replay's source.

const price = 3;
function checkout() {
  const order = "tea";
  console.log(order, price);
}
checkout();

The playground changes just one thing: whether the function record also has price = 4. Its source panel shows the default runnable JavaScript; the checkbox is a labeled teaching-model variation, not an edit to that displayed code. Without the local binding, lookup finds 3 globally. With it, lookup stops locally at 4. Reset restores the first case.

Scope in an application

A website may create a cart with a private price that its UI can read later. When the factory function returns, its local call is finished, but a returned function can still read the binding. The spec connects a function's saved environment to the enclosing record; the garbage collector decides its physical storage and lifetime.

function makeCart(price) {
  return { total() { return price; } };
}
const cart = makeCart(3);
console.log(cart.total());

Line 1 takes a price parameter. Line 2 returns an object with a total method that reads that binding. Line 4 stores a cart created with 3. Line 5 logs 3. This is useful when checkout needs a saved configuration without exposing a writable global property.

function makeOrder() {
  let price = 3;
  return () => ++price;
}
const nextPrice = makeOrder();
console.log(nextPrice());
console.log(nextPrice());

Line 2 creates a mutable price binding. Line 3 returns a function that increments it. Line 5 keeps the function. Lines 6 and 7 log 4 and 5: the returned function reads the same retained binding each time, not two snapshots. See closures for more uses of this pattern.

1function makeOrder() {2  let price = 3;3  return () => ++price;4}5const nextPrice = makeOrder();Run6console.log(nextPrice());7console.log(nextPrice());

This second replay calls the real makeOrder function and records each increment as a change. Back and Reset only change the player's view of those immutable snapshots. They do not expose internal engine allocation or guarantee a particular garbage-collection strategy.

Common mix-ups

Similar syntax can hide different lookup rules. Before predicting an output, ask whether the code is a classic script or a module, whether a name belongs to a block, and whether you are reading an identifier or an object property. Those are distinct questions.

const price = 3;
{
  const price = 4;
  console.log(price);
}
console.log(price);

Line 1 creates outer price = 3. Line 3 creates inner price = 4. Line 4 logs 4; line 6 logs 3. Nothing overwrites the outer value. Lookup merely starts at a different record inside the braces.

• "All variables are properties." Direct lexical bindings are not object properties.
• "An early let read uses the outer name." The nearer uninitialized binding wins, then its read throws.
• "Imported values are copied." An import is an indirect binding that reads the exporter's current value.
• "A closure copies every local." The function can keep access to a live binding; engines may optimize storage.
• "Private fields use normal scope lookup." Private names use a separate PrivateEnvironment chain.

globalThis.price is a property read. Bare price is an identifier lookup. They can have different results in the same classic script. Neither expression grants access to the Environment Record itself: the record is a rulebook device, not a public inspection API.

Practice

Use the same order each time: find the nearest record, decide whether it has the name, then ask if the binding is initialized. For property reads, ask which object the property belongs to. These small tasks use the code and output from the lesson.

{
  try { console.log(price); }
  catch (error) { console.log(error.name); }
  let price = 3;
  console.log(price);
}

const price = 3;
{
  const price = 4;
  console.log(price);
}
console.log(price);

var cart = "tea";
function checkout() { return cart; }
let price = 3;
const user = "Asha";
console.log(globalThis.cart, globalThis.checkout());
console.log(globalThis.price, globalThis.user);

function makeOrder() {
  let price = 3;
  return () => ++price;
}
const nextPrice = makeOrder();
console.log(nextPrice());
console.log(nextPrice());

class Cart {
  #price = 3;
  total() { return this.#price; }
}
console.log(new Cart().total());

import { price, changePrice } from "./cart.mjs";
console.log(price);
changePrice();
console.log(price);

Check your understanding

Predict code by separating names, records, and values. Read a property expression such as globalThis.price differently from an identifier expression such as price. The quiz mixes both.

For a missed question, revisit the matching example above and run it again. In particular, a TDZ error happens after lookup finds the nearer binding; it does not mean lookup could not find the name.

Key takeaways

Scope is not an object-property search in every case. The spec uses different records for ordinary lexical names, object-backed names, global declarations, function calls, modules, and class private names. Those records explain visible behavior without requiring any particular engine storage layout.

• Declarative bindings can be created before they are initialized; early reads throw ReferenceError.
• Classic-script var and functions use the global object side; let and const do not.
• Function records can provide this; arrows follow an outer record for this.
• Module imports read a target binding indirectly, so an exporter's changes remain visible.
• PrivateEnvironment Records resolve class private names using a separate outer-private chain.
• GetIdentifierReference checks the nearest record and then follows [[OuterEnv]] only if the name is missing.

Coming next: Execution contexts & jobs in the spec. That lesson explains which record is the running code's starting point and how the specification organizes work over time.