Skip to content

Node.js Training: From the Event Loop to Architecture Decisions

You can’t explain Node.js through a framework. You explain it through the event loop, through streams and through the question of which architecture decision a team will still understand tomorrow – and that is exactly what I practice with participants in the introduction-nodejs repo.

≈ 17 min readSoftwareNode.jsBackend

Node.js Training: From the Event Loop to Architecture Decisions

Express answers exactly one question: which function runs for which URL. It doesn’t answer the questions that actually break a Node backend in production – what happens when a single call blocks the only thread, when a response grows larger than the free memory, when a promise is rejected and nobody is listening. If you start with a framework, you memorize an API. If you start with the event loop, you understand why that API looks the way it does and what exactly happens when you use it wrong.

Still, the question “Why don’t we just build this with Express?” comes up very early in Node trainings – whether I run them directly or through partners like Grossweber. It’s a fair question, and it’s still premature. So the starting point is somewhere else: a single line that, at first glance, has nothing to do with architecture.

The first snippet already shows everything#

const fs = require("fs");

const data = fs.readFileSync("input.txt");
console.log(data.toString());
console.log("Fertig");

This isn’t exciting code. That’s exactly why it works as a starting point. readFileSync blocks the process until the file has been read completely. Only then does the next line run. I let participants run this code, then I change one line:

const fs = require("fs");

fs.readFile("input.txt", (err, data) => {
  if (err) return console.error(err);
  console.log(data.toString());
});
console.log("Fertig");

Now “Fertig” shows up first in the console, even though that line comes later in the source. For beginners, this is often the first small moment of shock: the code doesn’t run from top to bottom, at least not the way you’re used to from other languages. You can hang the entire rest of the training on this tiny difference. At its core, Node.js isn’t a framework and isn’t a collection of modules. It’s a decision: a program reacts to a slow input/output operation by moving on instead of waiting.

The event loop is architecture, not a footnote#

Node runs on Chrome’s V8 engine and in a single JavaScript thread. That regularly surprises participants, because the server can still handle thousands of concurrent connections. The contradiction dissolves as soon as you distinguish between concurrent and parallel. At any given moment, Node only processes one piece of JavaScript, but while that piece waits for an answer from the disk, the network or a database, Node hands the work down to libuv, the kernel or an internal thread pool. The event loop is the part that picks up the returned results and calls the matching callbacks as soon as the main thread is free.

This is where I deliberately slow down in the training, because this is where the real architectural statement lives: concurrency in Node isn’t an implementation detail you can ignore as long as the code works. It determines which work may happen right away and which has to wait, and it determines what a single blocking call means for every other request running at the same time. A CPU-heavy loop, a synchronous JSON.parse over several megabytes, a nested regex with catastrophic backtracking – none of these just stalls the one request that triggered it. They stall the entire process, because there is no second thread that could take over in the meantime.

flowchart LR
  subgraph Call["Call stack (one thread)"]
    direction TB
    JS["Your JavaScript"]
  end
  JS -->|"hands off I/O"| LibUV["libuv / kernel / thread pool"]
  LibUV -->|"result is ready"| Queue["Callback queue"]
  Queue -->|"call stack is empty"| JS

For participants who come from Java or .NET environments, this is often the biggest adjustment. The sentence I want to stick isn’t “Node is fast.” It’s this: Node is fair as long as you don’t sneak blocking work into it. That’s an operational promise, not a marketing line, and it has direct consequences for what is allowed to end up in a Node service at all.

Why callbacks, EventEmitter, streams and promises come in exactly this order#

In the introduction-nodejs repo, which I work through together with participants, the chapters deliberately follow this order: callbacks first, then EventEmitter, then streams, then promises and, at the very end, RxJS. It looks like an arbitrary list of async tools, but it’s actually a learning curve with clear logic behind it, and that logic is worth spelling out once.

A callback delivers exactly one result, exactly once, and error handling is pure convention: the first argument is set in case of an error, otherwise it isn’t. This convention is called error-first, and it only works if every function sticks to it with discipline. An EventEmitter goes one step further and delivers any number of events over time, but it has no built-in error channel. An error event is just an agreement, and if nobody listens to it, Node throws the exception further up, uncaught. At its core, a stream is a specialized EventEmitter that adds two things that matter in everyday work: a fixed role (Readable, Writable, Duplex or Transform) and backpressure, a built-in brake for when the destination is slower than the source. Finally, a promise goes back to exactly one result, exactly once, but gains a real, composable error channel through .catch that neither the callback nor the EventEmitter has. RxJS combines both properties at the end: many values over time, as with the EventEmitter, but with the same reliable error and completion contract that promises introduced.

Once participants have seen this arc, they stop asking for the “best” async pattern. The question shifts to something more useful: How many values do I expect, how many times may an error happen, and who is responsible for handling it?

Streams and backpressure in a concrete example#

No chapter in the training produces as many aha moments as streams, because they show for the first time that Node architecture is also a question of memory and throughput, not just syntax. A small example that gets shown a lot is all you need:

const fs = require("fs");
const zlib = require("zlib");

fs.createReadStream("input.txt")
  .pipe(zlib.createGzip())
  .pipe(fs.createWriteStream("input.txt.gz"));

At first glance, this is just a convenient way to compress a file. The line only gets interesting when you ask what happens when input.txt is ten gigabytes. Without streams, you would have to load the entire file into memory before compression could even start. With pipe, Node reads a chunk, compresses it, writes it, and only then does the next chunk get its turn – and automatically only as fast as the write target can keep up. That’s backpressure: a built-in queue that prevents a fast source from flooding a slow destination with data until the process chokes on its memory limit.

flowchart LR
  Source["Readable<br/>(e.g. file)"] --> Transform["Transform<br/>(e.g. gzip)"]
  Transform --> Sink["Writable<br/>(e.g. target file)"]
  Sink -. "Backpressure" .-> Transform
  Transform -. "pause / resume" .-> Source

For the architecture of a backend, this isn’t niche knowledge for file conversion. Every file upload, every CSV export, every log tail and every forwarded HTTP response body benefits from exactly the same principle. If you instead collect the entire request body in a buffer before anything happens with it, you have built in a memory limit that never shows up in a test with a small test file and very much does show up in production with real user files.

Express is not an architecture pattern#

This finally brings us to the question participants actually wanted to start with. Express is an excellent, lean routing tool, but it doesn’t make a single one of the decisions that actually define a web architecture. Those decisions live elsewhere: Does the server respond with fully rendered HTML, as in classic server-side rendering? Does it respond with structured data to an RPC-style call, where a function and its parameters sit in the body? Or does it follow the RESTful idea, where resources are addressed through URIs and HTTP methods carry their own meaning?

For the latter, I like to use the Richardson Maturity Model in the training as a small orientation aid, because it makes the levels tangible. At level 0, there is only a single URI, usually with POST, and the actual action sits in the body – basically RPC over HTTP. Level 1 adds several URIs for different resources, but still without proper use of HTTP methods. Level 2 uses GET, POST, PUT, DELETE and status codes the way they are meant: 200 for success, 201 for created, 204 for no content, 404 when the resource is missing. Level 3 adds hypermedia, meaning links in the response that tell the client which next steps are possible, instead of the client having to know that up front. Most systems I see in projects stop at level 2, and that’s usually perfectly fine. What matters is that the decision is made deliberately and isn’t simply the result of whichever Express examples you happened to copy first.

What Express actually contributes is something else, and it has a surprising connection to streams: a middleware pipeline.

const express = require("express");
const app = express();

app.use(express.json());
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  next();
});

app.get("/invoices/:id", async (req, res, next) => {
  try {
    const invoice = await loadInvoice(req.params.id);
    if (!invoice) return res.status(404).json({ error: "not_found" });
    res.status(200).json(invoice);
  } catch (err) {
    next(err);
  }
});

app.use((err, req, res, next) => {
  console.error(err);
  res.status(500).json({ error: "internal" });
});

app.listen(3000);

Each middleware gets the request and the response, does something and passes control on with next(), or it aborts with an error that ends up in the four-parameter error handler. Structurally, that’s the same principle as the streams above: a source, a chain of transformations, a destination and a separate channel for the error case. As soon as participants see this kinship, Express stops being a list of calls to memorize. It becomes one of several forms of the same pipeline idea that runs through the whole training.

Scaling without illusions#

A single Node process uses exactly one CPU core. That regularly surprises participants with servers that have eight or sixteen cores, because under load only one of them gets anything to do unless you take further steps. For this, Node offers child_process with three tools of different granularity: spawn starts any system command and delivers its output as a stream, exec does something similar but collects the output entirely in memory before it returns, and fork specifically starts another Node script as a separate process with a built-in message channel. For compute-heavy work that would otherwise block the event loop, that’s the clean way: offload the work instead of sacrificing the only thread.

In the repo, a fork looks like this, for example:

const { fork } = require("child_process");

const worker = fork("./heavy-computation.js");
worker.send({ numbers: [1, 2, 3, 4, 5] });
worker.on("message", (result) => {
  console.log("Result from worker process:", result);
});

The main process stays free while heavy-computation.js computes in its own process and sends the result back through the built-in message channel. That’s coarser than a thread, because every child_process brings its own V8 context and its own memory, but in many cases this very isolation is an advantage: a crashed worker doesn’t take the main process down with it.

Right now, in spring 2019, this picture is getting more interesting. Node 10 is the long-term support version that currently runs in production in most projects, solid and mature. Node 12 came out a few weeks ago and brings two things I already talk about in the training without recommending them for production: Worker Threads, which now run without a command-line flag but which the Node maintainers themselves don’t yet call fully mature, and experimental support for ECMAScript modules behind the --experimental-modules flag. Both show where Node is heading, but if you ship something today, you stay with require, with CommonJS and with the 10 line until 12 becomes the LTS version. I find this distinction important enough to make it explicit: curiosity about the new and responsibility for what’s running are two different things, and a good training shows both.

Errors are architecture too, not just a try/catch#

In the Express example above, an error ends up in the four-parameter handler because I explicitly passed it there with next(err). That’s the clean case. It gets interesting with the errors nobody passed on explicitly. For those, Node offers two global safety nets, and I deliberately show participants that they are nets, not repair tools.

process.on("uncaughtException", (err) => {
  console.error("Unexpected error, process is in an undefined state:", err);
  // only synchronous cleanup, then exit
  process.exit(1);
});

process.on("unhandledRejection", (reason) => {
  console.error("Promise rejected without .catch:", reason);
});

The Node documentation is unusually clear at this point: after an uncaughtException, the process is in an undefined state. That sentence is meant literally. Some module may have stopped in the middle of an operation, a file half written, a connection half established. So you don’t carry on in the handler. You clean up as quickly and as synchronously as possible and end the process, so that a supervisor – pm2, systemd, Kubernetes, whatever runs in the project – restarts it fresh. unhandledRejection is the promise variant of the same problem: a promise that was rejected without a .catch waiting for it anywhere.

For participants who come from a world with central exception handling, this takes some getting used to. The actual lesson is this: a global handler never replaces the try/catch or the .catch at the place where the error means something for the domain – that an invoice wasn’t found, that a payment failed, that a file doesn’t exist. It’s the last safety net for whatever fell through all the deliberately placed nets. It fits that Node allows a controlled shutdown through process.on("SIGINT", ...) and related signals: finish serving open connections, close database connections cleanly, and only then exit. Behind this is the same idea as with backpressure: a system says honestly when it’s done instead of simply being killed.

Test before it hurts#

The last building block I deliberately don’t skip in the training is testing, for a simple reason: everything shown so far – backpressure, error paths, the order of middleware – can be broken invisibly in no time if nobody has captured an expectation about it. I work with Mocha, because in 2019 it’s a proven, unexcited standard, and with the built-in assert module, because you don’t need an extra library to understand the idea.

const assert = require("assert");
const { describe, it } = require("mocha");

describe("Array.reverse", () => {
  it("reverses the order of elements", () => {
    const sut = "ABC".split("");
    const actual = sut.reverse();
    assert.deepEqual(actual, ["C", "B", "A"]);
  });
});

Arrange, Act, Assert: set up test data, run the function, check the result. These three steps sound trivial, but most hard-to-read tests violate exactly this separation by happily mixing setup and checks. With asynchronous code, Mocha pays off even more, because a test either accepts a done callback or simply returns a promise:

it("resolves with the expected value after the async call", () => {
  return computeAsync().then((actual) => {
    assert.equal(actual, 2);
  });
});

If the test function returns a promise, Mocha automatically waits for it before evaluating the result. If you forget the return, the test may report success before the actual assertion has even run – a bug that’s easy to miss in code reviews, because the test is green after all. For integration tests, before, after, beforeEach and afterEach come in, for example to set up a test database once and bring it back to a known state after each test. The test pyramid remains the guardrail: many fast unit tests at the base, fewer but meaningful integration tests in the middle, a handful of end-to-end tests at the top. If you invert this distribution, you usually only notice it in the runtime of the build pipeline, when it’s too late to change it cheaply.

The repository itself is architecture#

One point I like to explain to participants only at the end, because it would be too abstract earlier: introduction-nodejs is itself built as a Yarn Workspaces monorepo and not just a folder full of Markdown files. The root directory has a package.json with "private": true and a workspaces field that points to a packages folder, and each example lives below it as a standalone package: ARCHITECTURE, BASICS, ECMA, EVENTEMITTER, EXPRESSJS, FUNCTIONALJS, HTTP2, RXJS, STREAMS, TESTING, TYPESCRIPT. Each of these packages has its own dependencies and can be installed and run on its own, without the examples polluting each other.

That isn’t a coincidence, and it isn’t just a way of keeping things tidy. It’s the same lesson that already came up with streams and with Express, one level higher: clear boundaries between building blocks, each with its own responsibility, connected through an explicit, visible mechanism instead of silent dependencies. I deliberately show participants this structure of the repo itself, because a monorepo with clean workspace boundaries solves pretty much the same architecture problem as a backend made up of several services: Where may something be shared, and where must it stay separate so that a change in one place doesn’t surprisingly break something somewhere else?

How I actually run the training#

I rarely show a slide without opening the code right after it. The slide overview for the training is available for reference and for anyone who wants to see the overview again between sessions, here: Introduction to Node.js – slides. But the slide is the signpost, not the path itself. The real learning happens in the repository, together: I type, a participant types, we deliberately introduce a bug and look at the error message together, then we fix it together. If you only watch, you remember the syntax for the moment. If you type yourself and forget to return the callback yourself or put the await in the wrong place, you remember the boundary – and boundaries are what you can still recall a year later, not syntax.

That’s why the training is carried by the repo introduction-nodejs and not by the slide deck. The 23 chapters are set up as standalone Markdown files that you can look up in any order and that, as a whole, form a learning curve from the first script to production readiness – from the introduction through the event loop, streams and error handling to Express, testing, promises, RxJS and TypeScript. The accompanying EXAMPLES are runnable code, not pseudocode – exactly the code we change together in the room.

What should stick at the end#

On the last day of the training, I sometimes ask participants what they’re taking away. The answer that makes me happiest is rarely “I know Express now.” It’s more like: “I now know when to reach for a callback and when for a stream, and I know why an await is still something I have to think about.” That’s exactly the difference between a list of tools and an understanding of architecture. You can pick up a framework over a weekend. A feel for which decision will come back to bite you later takes practice on real, sometimes deliberately broken code.

Node.js works as a training subject for a reason that has nothing to do with being current or popular: its central design decision – non-blocking I/O in a single thread – is so uncompromising that it forces its own consequences. You can’t ignore it without the server eventually behaving strangely. And it’s exactly in these strange moments that you learn the most.

Even Ryan Dahl, who invented Node ten years ago, publicly questioned some of his own design decisions a while ago in a widely noted talk and has been experimenting with a possible successor ever since. Regardless of where this experiment leads, I find that remarkably healthy for an ecosystem: the inventor himself is willing to say what he would do differently today. That’s exactly the attitude I try to convey in the training. Node.js isn’t a finished, closed worldview that you memorize. It’s a series of decisions, each with its price, each open to debate. Once you have internalized that, you’ll also read the next technology that will be in vogue in five years as another set of decisions that you can understand and, if needed, refute – and not as the truth.

Further reading#

Revised and translated from German with the help of AI.