Load, link, evaluate

One graph, three phases

A module is not simply a file that runs when the browser sees it. Before any module body runs, the host builds a whole dependency graph. That preparation makes named imports reliable, makes circular imports possible to describe, and makes evaluation order predictable.

This lesson follows the browser security model. Browser rules decide whether a request is allowed; then the module system can load, link, and evaluate the allowed graph. The same broad idea appears in Node, although its resolver and loader have different host rules.

Keep one picture in mind. A module graph is a set of module records connected by import requests. The entry module is the starting point, but its dependencies often run first. That fact explains many surprising logs in real applications.

Source Text Module Records

A Source Text Module Record is the engine's record for one parsed JavaScript module. In plain words, it remembers which modules this source requests, which names it imports, which names it exports, and where the module is in its work: unlinked, linking, linked, evaluating, or evaluated.

1export let count = 0;2 3export function add() {4  count += 1;5}

Line 1 declares one exported binding named count. It starts at 0. Line 3 declares an exported function named add. The record can list these exports after parsing; it does not need to run add to discover the name.

1import { count, add } from "./cart.js";2 3console.log(count);4add();5console.log(count);

Line 1 requests ./cart.js and asks for its count and add exports. Lines 3 through 5 are evaluation work, so they wait until the graph has been prepared. The visible output is 0 and then 1.

The record is not a user-facing JavaScript object you normally inspect. It is useful vocabulary because it separates knowing a module's shape from running its statements. A syntax error can prevent a record from being created; a missing export can prevent linking.

Loading the module graph

Loading means finding, fetching, and parsing every module reachable from the entry. Starting with main.js, the host sees the request for ./cart.js, resolves it according to host rules, fetches it if needed, and parses it into another record.

1import { count } from "./cart.js";2console.log(count);

Line 1 is enough to make cart.js part of this graph. Line 2 does not run while the loader is still only discovering files. It runs later, during evaluation, after linking connects count to a real export.

Loading is recursive because each fetched module can name more imports. A loader must avoid treating two requests for the same resolved module as two independent modules. The graph needs one record per module identity so shared dependencies can be linked and evaluated once.

Linking imports to exports

Linking connects an import request to an export binding. In main.js, the imported name count becomes a connection to the exported count binding in cart.js. It is not a separate number placed in a new variable.

1import { count } from "./cart.js";2 3console.log(count);

Line 1 asks for the export with the exact name count. Line 3 reads that binding. If cart.js did not export that name, the graph would fail while linking instead of quietly giving undefined.

This early failure is valuable. A module can be parsed successfully and still be unlinked because an import name is wrong. No body should be partly run merely because another part of the graph has a naming mistake.

Live bindings, not copies

A live binding is an import that reads the current value of the exporter's binding. It behaves unlike copying a primitive into a new local variable. The exporting module owns its mutable binding; importing modules can read it but cannot assign to it.

1import { count, add } from "./cart.js";2 3console.log(count);4add();5console.log(count);

Line 3 prints 0 because cart.js created its binding with that value. Line 4 calls the exporting module's function. That function changes the same binding. Line 5 therefore prints 1, not a saved copy of 0.

1const cart = createCartModule();Run2 3console.log(cart.count);4cart.add();5console.log(cart.count);

The replay is an instrumented lesson model. It runs the lesson's small cart function and shows the same state change that the module example describes. It does not pause or inspect the JavaScript engine.

Depth-first, post-order evaluation

Evaluation runs module bodies. For a normal synchronous graph, dependencies are evaluated before the module that imports them. A useful teaching model is depth-first, post-order: visit a dependency first, and add a module to the output only after its dependencies.

1// shared.js2console.log("shared");3 4// a.js5import "./shared.js";6console.log("a");7 8// b.js9console.log("b");10 11// main.js12import "./a.js";13import "./b.js";14console.log("main");

The graph says main.js imports a.js and b.js, while a.js imports shared.js. The logs are shared, a, b, and main. A dependency finishes before its importer logs.

1const graph = {2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

Line 9 remembers modules already seen. Line 12 visits every dependency before line 13 adds the current module. The final log on line 21 is shared.js, a.js, b.js, main.js. This is a teaching model, not a copy of an engine's source code.

1const graph = {Run2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

Change one import

The graph becomes clearer when you change one edge. In the playground, remove only the import from a.js to shared.js. Then shared.js is no longer reachable from main.js, so it disappears from this modeled evaluation order.

1const graph = {2  "main.js": ["a.js", "b.js"],3  "a.js": ["shared.js"],4  "b.js": [],5  "shared.js": [],6};7 8function evaluationOrder(graph, entry) {9  const visited = new Set();10  const order = [];11  function visit(name) {12    if (visited.has(name)) return;13    visited.add(name);14    for (const dependency of graph[name] ?? []) visit(dependency);15    order.push(name);16  }17  visit(entry);18  return order;19}20 21console.log(evaluationOrder(graph, "main.js").join(", "));

Reset restores the original graph where a.js imports shared.js. The important rule is not that every file in a folder runs. Only modules reachable from the entry graph are loaded and eventually evaluated.

Module namespace objects

A module namespace object is the special value created by import * as cart from "./cart.js". It gives an object-like view of all exports. Its properties are live, but an importer cannot replace them with assignment.

1// cart.js exports count and add.2import * as cart from "./cart.js";3 4console.log(Object.keys(cart).join(","));5console.log(cart[Symbol.toStringTag]);6console.log(cart.count);7cart.add();8console.log(cart.count);

Line 2 creates the namespace binding named cart. Line 4 lists the export names, so this example prints add,count. Line 5 prints Module. Lines 6 through 8 show a live value: the count changes from 0 to 1.

In strict module code, cart.count = 2 throws a TypeError. That protects the exporter's binding. The exporting module can update its own let count; the namespace gives other modules a read-only view.

How this helps in real apps

A feature module should import the specific shared values it needs. A checkout screen can import add and count from a cart module; it does not need to know whether that state came from a simple variable, a store, or a server-backed adapter.

1import { add, count } from "./cart.js";2 3add();4console.log(count);

Line 1 names the two public exports. Line 3 updates cart state through its public function. Line 4 reads the current exported binding, so it prints 1 when this module starts with the lesson's cart state.

This phase model also helps debug failures. A network or URL problem is usually loading. An error about a missing export is linking. A thrown exception from a top-level statement is evaluation. Separating the words narrows the search quickly.

Common module mistakes

• “An import gets a copy.” Named imports are live bindings to the exporter's binding.
• “Loading runs code.” Loading discovers and parses the graph; evaluation runs bodies later.
• “Imports run top to bottom.” Dependencies run before importers, so graph order matters more than file order.
• “A namespace is a plain object.” It is a special read-only view with live export properties.
• “Each import reruns a shared module.” A module graph evaluates each reachable module once for that graph.

These distinctions become especially important in the next lesson, where two modules can import each other. A cycle is not a reason to forget phases; it is a reason to be even more precise about what is linked before either body finishes evaluating.

Practice exercises

let count = 0;
function add() { count += 1; }
console.log(count);
add();
console.log(count);

const graph = { main: ["a", "b"], a: ["shared"], b: [], shared: [] };
const visited = new Set();
const order = [];
function visit(name) {
  if (visited.has(name)) return;
  visited.add(name);
  for (const dependency of graph[name]) visit(dependency);
  order.push(name);
}
visit("main");
console.log(order.join(","));

Check your understanding

Answer by naming the phase first, then trace a graph only when the question asks about order. For binding questions, ask which module owns the changing value and which module only reads it.

Key takeaways

• A Source Text Module Record remembers one parsed module's imports, exports, and phase.
• Loading discovers every reachable module; linking connects names; evaluation runs bodies.
• Named imports are live bindings, so importers observe updates made by the exporter.
• Normal synchronous evaluation is dependency-first: depth-first, post-order, and once per module.
• A namespace object is a read-only, live view of a module's exports with a Module tag.
• Classify failures by phase before debugging URLs, exports, or top-level code.

Coming next: Circular dependencies. You will use the same records, links, and evaluation states to explain what happens when two modules request each other.