Technology handbook

Node.js — Runtime, APIs, Streams & Operations

Server-side JavaScript with the event loop, modules, streams, HTTP, processes and production operations.

Topics: 20
Sections: 6

Runtime foundations

Event loop

Understand how Node schedules timers, I/O callbacks, microtasks and CPU work.

Timers, I/O callbacks and microtasks run in phases, not in the order they were written.
Microtasks drain fully between phases, so a promise chain can starve I/O.
A CPU-bound function blocks every phase, because there is one thread doing all of it.

EventEmitter

Publish and subscribe to events while managing listener lifetime and errors.

Events are published and subscribed to, with listener lifetime managed.
A listener never removed is a leak that grows with every subscription.
An error event with no listener throws instead of being ignored.

Worker threads

Move CPU-bound JavaScript to worker threads without blocking the event loop.

CPU-bound JavaScript moves off the thread that serves requests.
Each worker has its own heap, so data is copied or shared deliberately.
Spawning one per task costs more than the work for anything small.

Modules

ES modules and imports

Choose module boundaries and import syntax that match Node and your package configuration.

The module system is decided by the package type field and the file extension.
Imports are resolved statically, so a specifier cannot be built at runtime.
Top-level await is available here and is not in CommonJS.

CommonJS and package exports

Bridge require and import while defining explicit package entry points.

require and import interoperate, with entry points declared explicitly.
The exports field is what makes internal files genuinely private.
A default export does not cross the two systems the way it appears to.

npm and dependency management

Keep package scripts, lockfiles and dependency boundaries reproducible.

Scripts, lockfiles and dependency boundaries stay reproducible.
The lockfile is what makes two installs produce the same tree.
A dependency only needed to build belongs in devDependencies, not in the runtime.

Platform APIs

fs and paths

Read files safely and build cross-platform paths without string concatenation.

Paths are composed with the path module rather than by joining strings.
Separators and drive roots differ per platform, which string concatenation ignores.
A user-supplied path must be resolved and checked, or it escapes the directory.

Buffers

Work with bytes for files, sockets, encodings and binary protocols.

Bytes are handled directly for files, sockets, encodings and binary protocols.
A Buffer is raw bytes, so an encoding must be named to read it as text.
Slicing shares memory with the original rather than copying it.

URL and URLSearchParams

Parse and construct URLs without unsafe string concatenation.

URLs are parsed and constructed without concatenating strings.
The parser encodes each component correctly, which manual joining does not.
Parameters can repeat, so reading one key can silently drop the rest.

Child processes

Run external programs safely with argument boundaries, streams and exit handling.

External programs run with argument boundaries, streams and exit codes handled.
Passing arguments as an array is what prevents shell injection.
A child whose output is never consumed blocks when its pipe fills.

Networking

HTTP servers

Handle requests, responses, headers, status codes and streaming bodies explicitly.

Requests, responses, headers and status codes are handled explicitly.
The body is a stream, so it does not exist until it is read.
A response that is never ended leaves the client waiting until it times out.

HTTP fetch

Make outbound requests with timeouts, abort signals and explicit response checks.

Outbound requests carry timeouts, abort signals and checked responses.
fetch does not reject on a 404 or a 500, so the status must be read.
Without a signal, a hung request holds the caller indefinitely.

WebSocket servers

Maintain real-time connections while handling backpressure and disconnects.

Real-time connections are maintained through backpressure and disconnects.
A connection can vanish without a close frame, so heartbeats detect it.
Slow clients need their send buffer bounded or memory grows per socket.

Performance

Streams and backpressure

Process large data incrementally and respect backpressure instead of buffering everything.

A write returning false means the buffer hit its highWaterMark.
The 'drain' event is the signal that writing may resume.
Continuing to write regardless is what turns a large input into unbounded memory.

File streams

Read and write large files incrementally with backpressure.

Large files are read and written incrementally with backpressure respected.
Reading a file whole is fine until the file is larger than the memory.
The stream must be closed on error, or the descriptor leaks.

Transform streams

Process data as it flows through a pipeline without loading everything into memory.

Data is processed as it flows rather than loaded and then converted.
A transform sits between a source and a sink without materialising either.
An error in the middle of a pipeline must be propagated, not swallowed.

Readable and writable streams

Compose stream sources and sinks with correct lifecycle and error handling.

pipeline composes streams and destroys them all if any one fails.
.pipe() leaves the destination open when the source errors, which leaks.
That difference is why the documentation steers toward pipeline.

Operations

Process errors and signals

Handle failures, shutdown signals and exit behavior without hiding operational problems.

Failures, shutdown signals and exit codes are handled rather than hidden.
An unhandled rejection terminates the process by default in modern Node.
Swallowing an error to keep the process alive leaves it in an unknown state.

Diagnostics and logging

Emit structured logs and inspect memory, CPU and event-loop behavior in production.

Structured logs, memory, CPU and event-loop behaviour are observable in production.
Event-loop delay is the measurement that reveals blocking work.
Logging to stdout synchronously makes logging itself a bottleneck.

Graceful shutdown

Stop accepting work, drain connections and exit cleanly on deployment signals.

The process stops accepting work, drains connections and exits cleanly.
Keep-alive connections hold the server open unless they are closed deliberately.
Exiting immediately on a signal drops requests that were mid-flight.

Ask follow-up questions on any topic in your dashboard.

Start learning