Scope analysis & variable allocation

Where variables live is decided early

The engine is the program inside a browser or Node.js that runs your JavaScript. Before it runs a function, the engine reads the code once. During that first read, it does a job called scope analysis:

• It finds every variable the code makes. Making a variable is called a declaration, like const currency = "₹".
• It finds every place the code uses a name. Each use is called a reference.
• It links each reference to the declaration it means.
• It decides where each variable will be kept while the code runs.

A part of the code where a name can be used is called a scope. A function is one scope. A block in curly braces, { }, is another. Scopes sit inside each other, like boxes inside boxes. Together they form a scope tree.

Earlier lessons covered Scope, Closures, Execution contexts, Hoisting, Stack & heap, eval, and Strict mode. Those lessons showed what JavaScript does. This lesson shows how the engine plans for it before the code runs.

JavaScript uses lexical scope. That means a name's meaning comes from where the code is written, not from when it runs. So the engine can link most names just by reading the code.

The part of the engine that reads code text is called the parser. It makes a scope for each of these:

• a function
• a block in curly braces
• a catch (error) part of a try...catch
• a module, which is a file that uses import or export
• a class

Then it takes each name the code uses. It starts in the scope where the name is used and looks outward, one scope at a time, until it finds the declaration. If it finds none, it marks the name as global or not found.

1function priceLabel(price) {2  const currency = "₹";3  const rounded = Math.round(price);4  return currency + rounded;5}6 7console.log(priceLabel(19.4));

• Line 1 makes the function priceLabel with one parameter, price.
• Line 2 makes currency.
• Line 3 makes rounded by rounding price. Math.round(19.4) is 19.
• Line 4 joins currency and rounded.
• Line 7 calls the function and prints ₹19.

The engine doesn't have to guess what price, currency, and rounded mean. It links each one to its declaration before the first call.

function makeCounter() {
  let count = 0;
  const label = "jobs";
  return function next() {
    count += 1;
    return label + ":" + count;
  };
}

This playground is a small analyzer made for this lesson. It is much simpler than V8, the engine inside Chrome and Node.js, but it is real code. It uses two libraries, acorn and acorn-walk, to read your code, build the scope tree, link each name, and sort the variables. It never runs your code.

Once every name is linked, the engine decides where each variable lives. There are two main places:

• The stack is fast, short-lived memory. Each function call gets its own area on it, called a frame. V8 also uses registers: small, fast slots for the values a call is working on. Everything in a frame is thrown away when the call returns.
• The heap is memory for things that must last longer. V8 keeps such variables in a heap object called a Context. Each kept variable gets its own numbered place in it, called a slot.

A variable used only during the call can stay on the stack. A variable that an inner function uses needs a Context slot, because the inner function might run after the outer call has returned. Putting a variable in a Context is called context allocation.

The V8 team calls this the "variable allocation problem" in the blog post Blazingly fast parsing, part 2: lazy parsing. For each variable an inner function uses, the engine must know: is it on the stack, or in a Context? V8's runtime scope docs name three objects that take part:

• Scope: what the parser builds while it reads the code.
• ScopeInfo: a short saved description of a scope and its slots.
• Context: the heap object that holds the kept values while the code runs.

The table lists the four kinds of decision. Read each row as: "when this is true, the engine picks this place, and this is what to picture."

Some names can't be planned ahead. When eval or with is involved, the engine only finds out while the code runs what a name means. This lesson calls those names dynamic. You'll see why in the section on eval and with.

A local variable normally goes away when its function returns. A closure changes that. A closure is a function made inside another function that still uses the outer function's variables. If the inner function can read or change a variable later, that variable must be kept.

So V8 gives the inner function two links: one to its code, and one to the outer call's Context. The Context holds only the variables that must be kept.

1function makeCounter(label) {Run2  const scratch = label.trim();3  let count = 0;4  return function increment() {5    count += 1;6    return scratch + ":" + count;7  };8}9 10const next = makeCounter(" jobs ");11console.log(next());12console.log(next());

Step through the replay above. It shows what the analyzer decides for each variable:

• label is used only on line 2, inside makeCounter. It can stay on the stack.
• scratch is used by increment on line 6. It goes into the Context.
• count is read and changed by increment on line 5. It goes into the Context too.

Now run the same code. The function you get back uses the same kept variables on every call.

1function makeCounter(label) {2  const scratch = label.trim();3  let count = 0;4  return function increment() {5    count += 1;6    return scratch + ":" + count;7  };8}9 10const next = makeCounter(" jobs ");11console.log(next());12console.log(next());

• Line 10 calls makeCounter once. label.trim() on line 2 removes the spaces, so scratch is "jobs". The returned increment function is saved as next.
• Line 11 prints jobs:1.
• Line 12 prints jobs:2.

Both calls change the same count, because it lives in the Context, not in one call's frame.

V8 doesn't keep every outer variable just because a closure exists. It keeps only the variables the inner functions use. But all closures made by the same outer call share one Context. If one slot holds a big object, and any of those closures is still in use, the Context and the big object stay in memory.

1function buildWidgets() {2  const bigConfig = { theme: "dark", cache: new Array(1000).fill("data") };3  let clicks = 0;4 5  function track() {6    clicks += 1;7    return clicks;8  }9 10  function readTheme() {11    return bigConfig.theme;12  }13 14  return { track, readTheme };15}

• Line 2 makes bigConfig, which holds an array of 1000 strings.
• track, on lines 5 to 8, uses only clicks.
• readTheme, on lines 10 to 12, uses only bigConfig.
• Line 14 returns both functions.

Both functions come from the same call to buildWidgets, so they share one Context. That Context holds clicks and bigConfig. While track is still in use, bigConfig stays in memory too, even after readTheme is gone.

This is a common cause of a memory leak: memory your program keeps but no longer needs. An event listener, a timer, or a cache keeps one small closure in use, and the shared Context keeps a big object with it. The later Memory management and Finding memory leaks lessons show how to find what is being kept.

Scope analysis works best when the written code tells the whole story. Two features break that rule:

• eval(text) runs a string as JavaScript code. When you call it by its own name, eval(...), it is a direct eval. The string can then use the variables around the call.
• with (object) { ... } makes the object's properties act like variables inside the block.

Code without "use strict" is called non-strict code. In non-strict code, a direct eval string can read any variable it can see, and it can even make a new var variable in the calling function. The engine can't know any of that until the string arrives at run time.

A with statement has the same problem. An object property can hide a variable with the same name, and the engine only finds out while the code runs. In both cases the engine must play safe: it keeps the names findable by name and skips some speed-ups.

1function demo() {Run2  let local = 1;3  eval("var surprise = local");4  return local;5}6 7function readWith(box) {8  const answer = "lexical";9  with (box) {10    return answer;11  }12}13 14console.log(readWith({ answer: "object wins" }));

The next example tries three ways to call eval:

• sloppyDirect uses direct eval in non-strict code.
• strictDirect uses direct eval in strict code, after "use strict".
• indirectEval writes (0, eval). The comma hands back the plain eval function, so the call is no longer direct. An indirect eval runs the string at the top level of the script, outside every function.

1function sloppyDirect() {2  const x = "local";3  eval("var leaked = x");4  return x + " | " + leaked;5}6 7function strictDirect() {8  "use strict";9  const x = "strict local";10  eval("var hidden = 1");11  return x + " | " + typeof hidden;12}13 14globalThis.x = "global";15function indirectEval() {16  const x = "local";17  return (0, eval)("x");18}19 20console.log(sloppyDirect());21console.log(strictDirect());22console.log(indirectEval());

Strict mode stops eval from adding variables to the calling function. It doesn't stop eval from reading them by name: the string can still name any local variable it can see. So in the tested version of V8 (12.4), that local variable is kept in a Context slot. Other engines may store it in a different way.

1function readWith(box) {2  const answer = "lexical";3  with (box) {4    return answer;5  }6}7 8console.log(readWith({ answer: "object wins" }));

• Line 2 makes a variable called answer, holding "lexical".
• Line 3 starts a with (box) block.
• On line 4, answer is looked up as a property of box first.
• Line 8 passes an object that has an answer property, so it prints object wins.

Strict mode doesn't allow with at all: it is a syntax error. Even in non-strict code, write the property access yourself, like box.answer. People can read it more easily, and the engine can plan for it.

The specification is the document that defines JavaScript. It describes each scope as a lexical environment: a list of variables plus a link to the scope outside it. Following those links outward gives a chain of scopes.

V8 does the same work with its own objects:

• While it reads the code, it builds a Scope for each scope.
• It saves what it needs later in a ScopeInfo.
• While the code runs, it makes a Context for each scope that has kept variables.
• Each Context links to the Context outside it. Those links form the context chain.

1function outer() {2  let total = 0;3  return function middle(step) {4    let label = "count";5    return function inner() {6      total += step;7      return label + ":" + total;8    };9  };10}11 12const inner = outer()(2);13console.log(inner());14console.log(inner());

• inner uses total, which outer makes on line 2.
• It also uses step and label, which middle makes on lines 3 and 4.
• Line 12 calls outer(), then calls the returned middle with 2.
• Lines 13 and 14 print count:2 and then count:4.

The table puts the specification's words next to V8's words. Read each row as: "this term, what it is, and why it matters."

The V8 blog post on faster class features uses the same words for private methods. V8 follows the context chain, reads a slot whose number it already knows, and uses that value. Variables kept for closures are found the same way.

You can see these choices in V8's bytecode. Bytecode is the list of small instructions V8 makes from your code before it runs it. Each instruction has a name, called an opcode:

• Opcodes with ContextSlot in the name read or write a Context slot.
• PushContext makes a Context the current one.
• Star0 stores a value in register 0, on the stack side.

The table lists what to look for. Read each row as: "for this kind of variable, look for these opcodes; they tell you this."

To print the bytecode yourself, save one of the probe programs below as a file, then run this command in a terminal. --print-bytecode-filter=inner prints only the function called inner.

node --print-bytecode --print-bytecode-filter=inner captured.js
# Node 22 / V8 12.4: look for LdaCurrentContextSlot,
# StaCurrentContextSlot, LdaContextSlot, StaContextSlot, and PushContext.

Each probe is a tiny program for one case.

function captured() {
  let x = 0;
  return function inner() {
    x += 1;
    return x;
  };
}
const f = captured();
f();

function uncaptured() {
  let x = 0;
  x += 1;
  return x;
}
uncaptured();

function strictEval() {
  "use strict";
  let local = 1;
  eval("local");
  return local;
}
strictEval();

function outer() {
  let x = 1;
  return function middle() {
    let y = 2;
    return function inner() {
      x += 1;
      y += 1;
      return x + y;
    };
  };
}
const inner = outer()();
inner();

Seeing this in DevTools

Chrome DevTools lets you look at these ideas. When your code is paused at a breakpoint, the Scope pane lists the variables you can see, in groups:

• Local: the variables of the function that is running.
• Closure: outer variables kept in a Context for this function.
• Block: let and const variables of the current block.
• Script: let and const variables at the top level of the script.
• Global: the global variables.

Some variables may not show a value. A variable that was never kept, or that the engine removed to save work, may show as unavailable or "optimized out". The exact words depend on the Chrome version.

In real projects, avoiding eval and with matters for more than style:

• Names the engine can link early let it make your code faster.
• Keeping closures small stops a long-lived closure from holding a big object by accident.

Common misconceptions

Key takeaways

• Because of lexical scope, the engine can link most names to their variables just by reading the code.
• A local variable that no inner function uses can stay on the stack, in the call's frame or in registers.
• A variable that an inner function uses is kept in a slot of a heap object called a Context.
• Non-strict direct eval and with make names unknown until run time, so the engine has to play safe.
• ScopeInfo describes which slots a Context has; the Context holds the values while the code runs.

Up next: Bytecode & interpreters, where you'll see these choices turn into bytecode instructions.