Node.js Performance Basics: Event Loop Blocking, Streams, Workers

Browser developers already know the main-thread rule from rendering (Browser Contract, Lesson 08). On the server, the same rule has a different result. In the browser you get a choppy animation. On the server, one slow request makes other users time out.

Words used in this lesson

• Node.js is a program that runs JavaScript outside the browser, mostly for servers.
• Thread is one line of execution inside a program. It does one step at a time. Process is a running program with its own memory. A process has at least one thread. Difference in one line: threads inside a process can share memory, but separate processes cannot.
• Event loop is the part of Node that picks the next piece of work (a callback) and runs it. It runs on the single JavaScript thread.
• Blocking means the thread is busy and cannot do anything else. Non-blocking means the thread hands the job off and keeps working.
• I/O-bound work spends most of its time waiting for disks, networks or databases. CPU-bound work spends its time calculating, so the processor is the limit.
• Synchronous code runs and finishes before the next line starts. Asynchronous code starts a job and lets other code run until the job is done.
• Latency is how long one request takes. p99 latency is the time that 99 out of 100 requests beat. It shows the slow cases.
• Stream is data that you handle piece by piece (chunks) instead of all at once.

The event loop, server edition

The event loop is the part of Node that picks the next piece of work to run. Think of one waiter in a restaurant. The waiter takes an order, gives it to the kitchen, and goes to the next table while the food cooks. The waiter is fast because they never stand and wait.

Node can handle thousands of connections with one JavaScript thread because I/O does not block it. When you write await db.query(), Node gives the job to the operating system (or a worker pool) and moves on to other requests. The loop runs in phases: timers, pending callbacks, idle and prepare (used by Node itself), poll for I/O, check (where setImmediate callbacks run), and close callbacks. A callback is a function that Node runs later, when a job is done. The loop runs one callback at a time until that callback is finished.

Request A: parse → await DB ──(waiting, loop is free)──▶ continue → respondRequest B:        parse → await cache ─(waiting)─▶ continue → respond

This model is great for I/O-bound work. That means APIs that mostly wait for databases and networks. It is bad for CPU-bound work, where the CPU does the heavy lifting.

Node's hidden thread pool

Not everything runs on the loop. libuv (the C library under Node that does I/O) keeps a small thread pool. A thread pool is a fixed group of worker threads that take jobs from a queue. The default size is 4, and you can change it with UV_THREADPOOL_SIZE (set it before the process starts). The pool is used for:

• file system operations
• dns.lookup (turns a host name into an IP address using the operating system)
• some crypto functions (such as pbkdf2 and scrypt, which hash passwords on purpose slowly, and randomBytes)
• zlib compression (making data smaller, for example gzip)

Network I/O uses the operating system's non-blocking sockets instead. So if many password hashes or compression jobs arrive at once, they wait in a queue for four threads. This can slow down file or DNS operations that have nothing to do with them.

What blocks the event loop

// ❌ One request to /report blocks every other request for secondsapp.get("/report", (req, res) => {  const rows = loadAllRowsSync();          // sync I/O  const result = heavyAggregate(rows);     // pure CPU  res.json(result);});

Seeing it: event-loop lag

Event-loop lag is the delay between when the loop should run something and when it really does. To measure it, check how late timers fire. If the loop is blocked for 400 ms, a 10 ms timer fires about 400 ms late.

import { monitorEventLoopDelay } from "node:perf_hooks";const h = monitorEventLoopDelay({ resolution: 10 });h.enable();setInterval(() => {  logger.info({ p50: h.percentile(50) / 1e6, p99: h.percentile(99) / 1e6, max: h.max / 1e6 }, "event loop delay (ms)");  h.reset();}, 10_000).unref();// The timer fires every 10 ms (the resolution), so even an idle process reads about 10 ms.// Look at how far the numbers rise above that.

Send this number out as a metric and set an alert for a high p99 lag (Lesson 05). A metric is a number your app reports over time. (p99 means 99% of the measurements are faster than this value. p50 is the median.) The numbers include the 10 ms timer interval, so a healthy service shows about 10 to 15 ms. A value far above that, such as several hundred milliseconds, means the loop was blocked. For deeper checks, use a CPU profile (a record of which functions used the processor and for how long). Node can write one with --cpu-prof, or you can connect Chrome DevTools with node --inspect. Tools like Clinic.js and 0x draw flame graphs, which are charts that show where the time goes.

Scenario: p99 latency spikes whenever one report endpoint is hit

Symptoms: Most endpoints take 20 ms. Every few minutes, everything jumps to several seconds. This happens at the same time as calls to /reports/monthly.

Diagnosis: The report handler does heavy CPU work (or turns a giant object into JSON) on the main thread. While it runs, the event loop cannot serve any other request. You can confirm this with event-loop-lag metrics and a CPU profile.

Fixes, from best to last choice:

1. Move the work into the database. Use aggregates, GROUP BY and window functions instead of pulling rows into JavaScript.
2. Make it asynchronous. Accept the request, put a job in a queue (a list of jobs waiting to be done, for example in Redis, or in SQS, which is Amazon's queue service) and return 202 (the HTTP status "Accepted": I got it, I will do it later). A separate worker process makes the report and saves it (for example in S3, Amazon's object storage, with a status endpoint). Users check the status or get a message when it is ready (Practical Design Problems, Lesson 07).
3. Move CPU work to worker_threads. This is a Node module that runs JavaScript on extra threads, each with its own event loop. A library like piscina manages a pool of them. The main loop stays free.
4. Stream large results instead of building the whole result in memory.
5. Split the work into chunks. Process 1,000 rows, then give control back with setImmediate (it runs a function on the next loop turn, so other requests get a chance). This is a short-term fix.
6. Isolate it. Serve heavy endpoints from a separate deployment, so they cannot starve the main API.
7. Cache (keep a saved copy of) the result if many users get the same report.

Streams: handle big data without loading it

Reading a 2 GB file into memory with fs.readFile uses 2 GB of memory. fs.readFile also refuses files larger than 2 GiB. So one request can use up all the memory. Streams process data in small pieces (chunks). Think of a water pipe instead of a bucket: water flows through and you never hold all of it:

import { createReadStream } from "node:fs";import { pipeline } from "node:stream/promises";import { createGzip } from "node:zlib";app.get("/exports/:id", async (req, res) => {  res.setHeader("Content-Type", "text/csv");  res.setHeader("Content-Encoding", "gzip");  await pipeline(createReadStream(pathFor(req.params.id)), createGzip(), res); // constant memory, handles backpressure});

Key ideas:

• Backpressure means "slow down, I am not ready". The producer is the side that makes data. The consumer is the side that receives it (for example a slow client). If the consumer cannot keep up, the stream pauses the producer. It does not store everything in memory. Use stream.pipeline (or pipeline from node:stream/promises). It also handles errors and cleans up when something fails. A plain .pipe() does not do this.
• Stream database cursors, S3 objects, CSV or JSON-lines exports, and uploads (send the request straight into storage). Even better: let clients upload and download directly to object storage (a service like S3 that stores files) with presigned URLs (temporary signed links that allow one upload or download). Then your API never touches the bytes (Practical Design Problems, Lesson 04).
• For JSON, prefer NDJSON (newline-delimited JSON: one JSON object per line) for large exports. The reader can then parse it piece by piece.

Concurrency: cluster, worker threads, child processes, containers

In container setups, most teams run one Node process in each container (a container is a packaged app with its own isolated environment) and change the number of containers. cluster matters mostly on a plain VM (virtual machine).

Other practical Node performance habits

• Never use sync APIs on request paths. They are fine at startup.
• Use a fast JSON serialiser (a tool that turns objects into JSON text) or schema-based serialisation (Fastify's fast-json-stringify) for busy endpoints. Avoid huge responses. Paginate, and compress (gzip or Brotli, which is often better done at the proxy or CDN).
• Reuse connections. Use HTTP keep-alive (keeping a connection open for the next request) agents for outgoing calls, and a shared database pool.
• Limit concurrency (how many jobs run at the same time) when you send many requests at once (p-limit is a small library for this). Do not fire thousands at once.
• Set timeouts everywhere and limit request body sizes.
• Watch memory. Heap usage that keeps growing means a leak. Common causes are event listeners, caches with no limit, and closures (functions that keep old variables alive). The heap is the memory where objects live. Take heap snapshots (a saved picture of all objects in memory). Set --max-old-space-size (the heap size limit, in MB) to fit the container.
• Cache expensive work that repeats. Use an in-process LRU cache (it drops the least recently used items) for small hot data, and Redis for shared data.
• Use a current Node version and keep dependencies up to date. Engine improvements are free speedups.
• Test with realistic load (autocannon and k6 are tools that send many requests) and look at p95 and p99, not only throughput (requests per second).

Common mistakes

1. CPU-heavy work inside request handlers.
2. *Sync calls in busy code paths.
3. Loading whole files or result sets into memory instead of streaming.
4. Unbounded Promise.all over big lists.
5. Using .pipe() without error handling. Streams and file descriptors leak.
6. Not measuring event-loop lag. Blocking stays invisible until an incident.
7. Regexes on untrusted input without checking for catastrophic backtracking.
8. Believing "async/await" means "runs in parallel". It only avoids blocking while waiting, not while calculating.

Interview questions

Key takeaways

• One JS thread: keep request handlers short and async. Keep CPU-heavy and synchronous work out of them.
• Measure event-loop lag and set an alert. Use flame graphs to find the cause.
• Stream large data with pipeline and backpressure, or skip the server with presigned URLs.
• Move heavy calculation to the database, a queue plus a worker, or worker_threads. Scale out with more instances.
• The libuv thread pool (default 4) serves fs, DNS lookup, some crypto and zlib.

What's next

Lesson 11: Testing an API. We finish the series with how to prove that all of this works, and keeps working: unit, integration and contract tests.