How Node really works · Chapter 1 of 34

Architecture and the event loop

By the end of this chapter you can say when each callback in a Node program runs, and keep a server answering while it does heavy work. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: How Node runs
  • 5 tasks
  • Node.js
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

Tapri's order server takes several orders a second at the 4 pm rush. Last week Ravi ran the day's sales total on it, and for a few seconds no order went through. Kabir wants a backend that never does that, with a status page saying which Node it runs on.

You have used callbacks and promises without asking when they run. On a server that matters: add up a day of sales in one loop and every order waits for it; emit an event before anyone listens and nobody hears it. Fixing either means knowing how Node picks what runs next.

The lesson

V8, libuv and one thread

V8, Chrome's engine, runs your JavaScript and knows nothing about files or networks. libuv, a C library, talks to the operating system: it watches sockets, runs timers, and keeps 4 threads for work like reading files. Both report their versions:

console.log(process.versions.node, process.versions.v8, process.versions.uv);
console.log(process.platform);
24.21.0 13.6.233.17-node.53 1.52.1
linux

Your JavaScript runs on one thread. readFile hands the job to libuv and returns at once; when the file is ready, its callback waits until the thread is free. Here a 10 ms timer meets one long loop:

const start = Date.now();
setTimeout(() => {
  console.log(`order 41 served after ${Date.now() - start} ms`);
}, 10);

let total = 0;
for (let i = 0; i < 300_000_000; i++) total += 40;
console.log(`total ready after ${Date.now() - start} ms`);
total ready after 258 ms
order 41 served after 261 ms

The 10 ms timer waited 261 ms for the busy thread (your numbers will differ).

The event loop phases

After your file's own code, Node goes round the event loop. Each round visits six phases in order:

  1. timers: setTimeout and setInterval callbacks that are due
  2. pending callbacks: some system errors held over from last round
  3. idle, prepare: Node's own housekeeping
  4. poll: waits for I/O and runs its callbacks (a file read)
  5. check: setImmediate callbacks
  6. close callbacks: 'close' events, such as a socket closing

So inside an I/O callback, setImmediate always beats a 0 ms setTimeout: check comes before the next round's timers. From a file's top level, Node does not promise which goes first.

Ticks and promises jump the queue

After every callback, Node empties the nextTick queue (process.nextTick), then the promise queue (then callbacks), and repeats until both are empty. Only then does the loop move on:

setTimeout(() => {
  Promise.resolve().then(() => console.log('promise'));
  process.nextTick(() => console.log('tick'));
  console.log('timer callback');
}, 0);
timer callback
tick
promise

One surprise: every .js file in this lab is an ES module, whose top-level code runs as a promise job, so there the promises go before the ticks:

ES modules also mean import, not require, which fails at once:

ReferenceError: require is not defined in ES module scope, you can use import instead

Not now, but very soon

process.nextTick means "right after the running code, before anything else". An object that emits an event as soon as it is made needs it:

import { EventEmitter } from 'node:events';

function openCounter(name) {
  const counter = new EventEmitter();
  counter.emit('open', name);
  return counter;
}

const counter = openCounter('Indiranagar');
counter.on('open', (name) => console.log(name, 'is open'));
console.log('done');
done

The listener comes after openCounter returns, when the event has gone. Careful: a tick that queues a tick forever starves the loop, and no timer ever runs.

Giving the loop a turn

The fix for the frozen server is not a faster loop. Split the work into chunks, and between chunks hand the thread back with setImmediate:

Your turn

Your five tasks are at the top, all in exercise.js. Two traps: a counter that waits with setImmediate or a timer speaks too late, and an empty list of sales must total 0. For Dev's interview question, write your prediction down first, then run the snippet in the terminal to check it.

What you build: 5 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    runtimeReport: which Node the server runs on

    Write runtimeReport(). It returns one line naming the Node, V8 and libuv versions and the platform of the Node that is running it, in exactly this shape: Node <node version> (V8 <V8 version>, libuv <libuv version>) on <platform>.

    Read the values when the function runs; do not type today's numbers in.

  2. Task 2

    PHASES and phaseFor: a map of the loop

    Fill PHASES with the six phases of the event loop, in the order the loop visits them, using exactly these names: timers, pending callbacks, idle, prepare (one name, with its comma), poll, check, close callbacks.

    Write phaseFor(kind), which returns the phase where that kind of callback runs. kind is one of setTimeout, setInterval, setImmediate, readFile, socket close, nextTick and promise. For a kind that runs between phases rather than in one, return 'microtask'.

  3. Task 3

    openCounter: announce the counter at the right moment

    Write openCounter(name). It returns an EventEmitter that emits 'open' with the name, exactly once. Listeners attached on the lines right after the call must hear it, so it cannot be emitted while openCounter is running.

    It must still come before any callback that is already waiting for the check phase (setImmediate) or for a timer.

  4. Task 4

    totalInChunks: the sales total that never freezes the server

    Write totalInChunks(amounts, chunkSize), with chunkSize 500 when it is left out. It returns a promise of the sum of amounts. It adds chunkSize amounts at a time, and between chunks it hands the thread back with setImmediate, so other callbacks that are waiting run between the chunks.

    An empty list totals 0.

  5. Task 5 · interview question

    Interview: predict the order of ticks, promises, immediates and timeouts

    The starter shows a snippet that runs inside a file system callback and pushes eight entries to log. Set predictedOrder to those eight entries, as the same strings, in the order they are pushed.

    The check runs the same snippet and compares the two lists in order.

What you will learn

  • V8, libuv and one thread: who runs your code, and who waits.
  • The event loop phases: the rounds Node goes through, and which callbacks run in each.
  • nextTick and promises: two queues that run between callbacks.
  • Giving the loop a turn: splitting long work so others are served.

More in How Node runs

Build "Architecture and the event loop" yourself

Tapri’s order server must never stall at the 4 pm rush. You learn why it would. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.