DEV Community: Aman Kumar Singh

Node.js Error Handling: Operational vs Programmer Errors

Aman Kumar Singh — Fri, 24 Jul 2026 10:09:58 +0000

Error handling is where a lot of Node.js applications quietly fall apart. Not with a dramatic crash — with a request that hangs forever because a rejected Promise went unhandled, or a process that dies without explanation because an error was thrown somewhere no try/catch could reach. Node's asynchronous, single-threaded nature makes errors behave in ways that trip up people coming from other languages, and getting error handling right is less about writing more try/catch blocks than about understanding where errors surface and which ones you can actually recover from.

This is part of the Node.js runtime series. Here we cover the different ways errors propagate, the process-level safety nets, and the distinction that should drive your whole strategy.

Errors propagate differently depending on the pattern

The first thing to internalize is that how an error reaches you depends on which async pattern produced it, and mixing them up is how errors get lost.

Synchronous errors are the easy case. A throw in synchronous code is caught by an enclosing try/catch, exactly as you would expect:

try {
  JSON.parse(invalidInput) // throws synchronously
} catch (err) {
  handle(err)
}

Callback errors follow Node's error-first convention: the error arrives as the first argument, not by throwing. A try/catch around a callback-based call will not catch an error the callback reports, because the error is passed in, not thrown. You have to check the first argument every time:

fs.readFile("x", (err, data) => {
  if (err) return handle(err) // the only way the error reaches you
})

Promise and async/await errors surface as rejections. With async/await, a rejected Promise makes the await throw, so try/catch works again — which is a big part of why async/await is the modern default. The trap is the Promise you forget to await or .catch. A rejection with no handler becomes an unhandled rejection, which does not go to any try/catch and, in current Node, crashes the process by default.

The through-line: try/catch catches synchronous throws and awaited rejections, but not error-first callbacks and not un-awaited Promises. Most "the error just vanished" bugs come from expecting try/catch to catch something it structurally cannot. Know which pattern you are in, and handle the error the way that pattern delivers it.

The process-level safety nets

Node gives you two global handlers for errors that escape everything else, and understanding their role — as last resorts, not primary handling — matters.

process.on("uncaughtException") fires when an error is thrown and nothing catches it anywhere. process.on("unhandledRejection") fires when a Promise rejects with no handler. It is tempting to treat these as a convenient catch-all: log the error, keep running, move on. That is a mistake. When one of these fires, your application is in an unknown state — an operation was interrupted at an arbitrary point, and whatever invariants it was maintaining may now be half-broken. Continuing to serve requests from a process in an undefined state can produce corrupted data and behavior far more confusing than a clean crash.

The accepted practice is to treat an uncaught exception as fatal: log it with full detail through your structured logger, and then let the process exit and be restarted fresh by your process manager or orchestrator. A clean restart returns you to a known-good state; limping along in a corrupted one does not. These handlers are for logging the thing you failed to handle and shutting down gracefully, not for pretending the error did not happen. Their real value is observability — knowing what escaped — plus a chance to flush logs and close connections before exiting.

The distinction that drives everything: operational vs programmer errors

The single most useful idea in Node error handling is separating two fundamentally different kinds of errors, because they call for opposite responses.

Operational errors are expected problems that a correct program will still encounter because the world is unreliable: a network request timed out, a database connection dropped, a file was not found, user input failed validation, a downstream service returned a 503. These are not bugs. They are runtime conditions you should anticipate and handle gracefully — retry the request, return a clean 400 to the user, fall back to a cache, surface a helpful message. Your application should recover from these and keep running, because they will happen in normal operation no matter how good your code is.

Programmer errors are bugs: calling a function with the wrong arguments, reading a property of undefined, a typo that throws a TypeError. These are not conditions to handle; they are mistakes in the code. Trying to "recover" from them is usually wrong, because you do not actually know what state the bug left things in. The right response to a programmer error is to let it crash the process, get logged, and be fixed — the fail-fast principle. Papering over a TypeError with a broad try/catch that swallows it just hides the bug and lets a corrupted process continue.

Once you hold this distinction, your strategy clarifies. Handle operational errors deliberately and specifically, close to where they occur, with real recovery logic. Let programmer errors fail fast and loud so you find and fix them. The mistake to avoid in both directions is a giant try/catch that catches everything and logs it the same way, which turns recoverable operational errors and fatal programmer bugs into the same undifferentiated "something went wrong" — losing the recovery you wanted for the first and hiding the second.

Practical guidelines

A few habits fall out of all this. Always attach a .catch (or wrap in try/catch with await) to every Promise; the un-awaited rejection is the most common lost error in Node. In an Express-style app, funnel operational errors to a central error-handling middleware so you produce consistent responses rather than scattering ad-hoc handling through every route — the thin-controller principle that keeps error logic in one place. Create custom error classes for your operational errors so you can distinguish a ValidationError from a NotFoundError and respond appropriately, using the type narrowing that instanceof gives you. And make sure everything that reaches a global handler is logged with enough context to actually debug it.

Done well, error handling is not defensive clutter spread through the codebase. It is a clear model: know how each async pattern delivers its errors, handle operational errors close to where they happen with real recovery, let programmer errors crash so you fix them, and keep the process-level handlers as logging-and-exit safety nets rather than catch-alls. That model, more than any amount of try/catch, is what keeps a Node service both resilient to the messy real world and honest about its own bugs.

Originally published at amanksingh.com.

Node.js Memory Leaks and Profiling: Finding What Holds Memory

Aman Kumar Singh — Fri, 24 Jul 2026 10:07:18 +0000

A Node.js memory leak rarely announces itself. The service runs fine in testing, ships, and then over hours or days its memory creeps up until it hits the limit and the process is killed and restarted. Because a restart temporarily fixes it, leaks often hide for a long time behind an automatic restart policy, quietly costing you reliability and money. Finding them is a specific skill: you have to know the handful of patterns that cause leaks in Node, and the tools that let you see what is actually holding memory.

This is part of the Node.js runtime series. Here we cover how memory works in Node, the common leak sources, and how to profile.

How memory works in Node

Node uses V8's garbage collector, which automatically frees objects that are no longer reachable — that is, objects nothing in your running program can still reference. You do not free memory manually; you just stop referencing things, and the collector reclaims them. This is why a "leak" in a garbage-collected runtime is not memory you forgot to free. It is memory you are unintentionally still referencing. Something is holding a reference to objects you are done with, so from the collector's point of view they are still in use and cannot be reclaimed.

That reframing is the key to finding leaks. You are not hunting for a missing free(). You are hunting for a reference that should have been dropped and was not — a growing structure, a listener never removed, a closure that captured more than you realized. Almost every Node leak is one of a few recognizable shapes.

The common leak sources

Unbounded growth of a module-level structure. The most common leak by far: a Map, array, or object at module scope that you keep adding to and never remove from. A cache that never evicts, a Map keyed by request ID that you populate but never delete, an array you push to on every event. Each entry holds its objects alive forever. Any collection that only ever grows is a leak waiting to happen; every cache needs an eviction policy or a size bound, which is exactly why Redis caches use TTLs rather than growing without limit.

Listeners that are added but never removed. Every emitter.on(...) holds a reference to its listener function, and through the closure, to everything that function captured. Add listeners without removing them — on every request, say — and they accumulate, along with everything they close over. Node even warns about this: the "possible EventEmitter memory leak detected, 11 listeners added" message is a direct signal you are registering listeners you never clean up. The fix is to remove listeners when you are done, or use once for one-shot events so they clean themselves up.

Timers and intervals never cleared. A setInterval that is never cleared runs forever and keeps its callback — and its captured scope — alive for the life of the process. If you create intervals or timeouts tied to some resource, clear them when that resource goes away.

Closures holding more than expected. A closure keeps alive everything in the scope it captured, even parts you do not use. A callback stored somewhere long-lived that happened to capture a large object keeps that whole object in memory. This one is subtle because the capture is implicit, and it is often the answer when a leak does not match the more obvious patterns.

Detecting that you have a leak

Before profiling, confirm the leak is real and get a shape for it. Watch the process's memory over time under normal load. The signal of a leak is heap usage that trends upward and does not come back down after garbage collection — a sawtooth that ratchets higher rather than returning to a stable baseline. Normal memory rises and falls as the collector works; a leak is the baseline steadily climbing. Your monitoring and structured logs should track heap-used over time so this trend is visible on a graph rather than discovered when the process gets killed. If memory grows unbounded under steady load, you have a leak worth chasing.

Profiling with heap snapshots

The core tool for finding what is holding memory is the heap snapshot: a complete picture of every object in the heap at a moment in time. You capture one through the Chrome DevTools inspector (start Node with --inspect and connect from Chrome, or use the v8 module or a library to write snapshots to disk) or through your platform's profiler.

A single snapshot tells you what is in memory now, but the powerful technique is comparison. Take a snapshot, exercise the suspected leaky path many times, force a garbage collection, and take a second snapshot. Then compare the two. Anything that grew substantially between the snapshots — thousands more of some object than before — is your leak, or the path to it. The comparison cuts through the noise of everything that is legitimately in memory and points at what is accumulating. From the growing object, the snapshot lets you trace the retainer path: the chain of references keeping it alive, which leads you straight back to the module-level Map, the un-removed listener, or the uncleared interval that is the actual cause.

For CPU issues rather than memory, the equivalent tool is a CPU profile, which shows where execution time is spent and is how you find the function pinning a core — often the same investigation that reveals work that should move to a worker thread.

Preventing leaks in the first place

Most leaks are prevented by a few habits rather than found by heroic debugging. Bound every cache — a size limit or a TTL, never an unbounded growing Map. Remove listeners and clear intervals when the thing they belong to goes away, and prefer once for one-shot events. Be conscious of what your long-lived closures capture. And put heap metrics on a dashboard so a slow climb is visible early, while it is a graph trending up rather than a 3 a.m. page about a process that keeps dying.

The mental model to carry: in Node, memory is not freed, it is released by becoming unreachable, so a leak is always a reference you failed to drop. When memory climbs, the question is never "what did I forget to free" but "what am I still holding onto." Answer that — usually with a snapshot comparison pointing at a growing collection — and the fix is almost always to drop the reference: evict the cache entry, remove the listener, clear the timer. It ties back to the same discipline that runs through the whole runtime: understand what the process is actually holding, and keep it bounded.

Originally published at amanksingh.com.

Scaling Node.js with the Cluster Module: Using All Your Cores

Aman Kumar Singh — Fri, 24 Jul 2026 10:04:54 +0000

A single Node.js process uses a single CPU core. Your server has eight. Out of the box, seven of them sit idle while one does all the work — which means a default Node deployment leaves most of the machine you are paying for unused. The cluster module is how you fix that: it runs multiple Node processes that share the same port, so all your cores serve requests. Understanding it, and where it sits relative to worker threads and horizontal scaling, is what lets you actually use the hardware you have.

This is part of the Node.js runtime series. Here we cover clustering, why it works, and how it fits into a broader scaling strategy.

Why one process is not enough

The event loop is single-threaded, and that single thread runs on one core. This is fine for the I/O concurrency Node excels at — one thread juggles thousands of connections happily — but it means a single Node process can never use more than one core's worth of CPU. On a multi-core machine, that is a lot of wasted capacity, and it caps how much a single process can handle before the one core it uses is saturated.

The cluster module solves this by running several Node processes instead of one. You start a master process that forks multiple worker processes — typically one per CPU core — and they all listen on the same port. Incoming connections are distributed across the workers, so requests are handled in parallel across all your cores. Eight cores, eight workers, eight requests being processed at once instead of one.

const cluster = require("node:cluster")
const os = require("node:os")

if (cluster.isPrimary) {
  for (let i = 0; i < os.availableParallelism(); i++) {
    cluster.fork() // one worker per core
  }
  cluster.on("exit", (worker) => {
    cluster.fork() // replace a worker that died
  })
} else {
  startServer() // each worker runs the app
}

The operating system and Node handle distributing connections across the workers, so from your application's perspective each worker is just your normal server, running on its own core.

Processes, not threads

A key distinction from worker threads: cluster workers are separate processes, not threads. Each has its own memory, its own event loop, its own everything — they share nothing except the listening port. This is exactly why clustering works cleanly for scaling a web server: since the workers share no memory, there is no coordination between them at the application level, and one crashing does not corrupt the others. The master can simply fork a replacement, as in the exit handler above, giving you a basic resilience win alongside the throughput one.

It also means clustering and worker threads solve different problems and can be used together. Clustering multiplies your request-handling capacity across cores. Worker threads offload CPU-bound tasks off the main thread within a single process. A service might cluster across eight cores for throughput, and each worker might use a worker thread for the occasional heavy computation. They are complementary, not alternatives.

The catch: workers share no state

Because cluster workers have separate memory, anything you stored in process memory is per-worker, and this breaks two common patterns the moment you cluster.

The first is in-memory state. If you cache data in a module-level variable, or keep user sessions in memory, each worker has its own copy, and a user whose requests land on different workers sees inconsistent data — logged in on one, logged out on the next. The fix is the same statelessness that horizontal scaling demands: push shared state out of process memory into something all workers reach, like Redis. Sessions, caches, and rate-limit counters all belong in a shared store, not a local variable, the moment you run more than one process.

The second is anything that must happen exactly once. Scheduled jobs are the classic trap — if every worker runs the same cron task, a job meant to fire once now fires eight times, once per worker. You have to elect a single worker (or move the scheduler out of the clustered process entirely) so the job runs once. These are not clustering bugs; they are the natural consequence of going from one process to many, and they are exactly the constraints you also hit when scaling to multiple machines.

Clustering versus running multiple containers

Here is a question worth answering honestly, because the modern deployment landscape changes the calculus. The cluster module scales you across the cores of one machine. But if you deploy on a platform that runs your app in containers and scales by adding more container instances — which most cloud and container platforms do — then the platform is already giving you multiple processes across cores, and adding the cluster module inside each container can be redundant or even counterproductive.

The general guidance: if you self-host on a big multi-core box and run the process directly, the cluster module is how you use all the cores, and it is the right tool. If you deploy in containers behind an orchestrator that scales instances for you, prefer running one process per container and letting the platform scale the instance count — it is simpler, and the orchestrator handles the distribution, health checks, and replacement that you would otherwise be reimplementing with cluster. Either way the goal is identical: use every core, keep each process stateless, and let something distribute the load. Whether that "something" is the cluster master or a container orchestrator is a deployment choice.

Where clustering fits in scaling

Clustering is the bridge between a single process and true horizontal scaling. It gets you from one core to all the cores on one machine — vertical scaling of your process count, in effect. Beyond that, when one machine is not enough, you scale out to multiple machines behind a load balancer, and the statelessness you were forced into by clustering is exactly what makes that next step easy: a stateless app that runs correctly across eight cluster workers already runs correctly across eight machines. The disciplines compound. Get the app stateless for clustering and you have done most of the work for scaling it as far as you will ever need.

Originally published at amanksingh.com.

Node.js Worker Threads: Moving CPU Work Off the Main Thread

Aman Kumar Singh — Fri, 24 Jul 2026 10:02:31 +0000

Node.js is superb at I/O and helpless at CPU-bound work on the main thread — a direct consequence of the single-threaded event loop. The moment your code has to do something genuinely computational — resize an image, parse a huge document, hash passwords, run a data transformation — that work holds the one JavaScript thread and every other request waits behind it. Worker threads are Node's answer: a way to run JavaScript on separate threads so heavy computation happens off the main thread, leaving the event loop free to keep serving requests.

This is part of the Node.js runtime series. Here we cover what worker threads are for, when to use them, and — just as important — when not to.

The problem: CPU work blocks everything

Recall the core constraint. Node runs your JavaScript on a single thread, and that thread's availability is what lets Node juggle thousands of connections. A CPU-heavy function does not yield — it runs straight through, holding the thread the entire time:

app.post("/resize", (req, res) => {
  const output = resizeImageSynchronously(req.body) // 800ms of pure CPU
  res.send(output)
})

For those 800 milliseconds, the event loop cannot advance. No other request is served, no queued I/O callback runs, health checks time out. One CPU-bound endpoint can make an entire otherwise-fast service unresponsive under load. Making the function faster only shrinks the problem; it does not remove it. The real fix is to run that computation somewhere other than the main thread.

What worker threads are

The worker_threads module lets you spawn additional threads that each run JavaScript in their own isolated environment — their own V8 instance, their own event loop, their own memory. You hand a worker a task, it runs on a separate thread, and it sends the result back when done. Because it is a different thread, the heavy computation runs in parallel with the main thread, which stays free to keep the event loop turning.

const { Worker } = require("node:worker_threads")

function runTask(data) {
  return new Promise((resolve, reject) => {
    const worker = new Worker("./resize-worker.js", { workerData: data })
    worker.on("message", resolve)
    worker.on("error", reject)
  })
}

app.post("/resize", async (req, res) => {
  const output = await runTask(req.body) // main thread stays free
  res.send(output)
})

Now the main thread offloads the work and awaits the result like any other async operation, so the event loop keeps serving other requests while the worker computes. The CPU work still takes 800 ms, but it no longer freezes the process.

Communication and its cost

Worker threads do not share ordinary variables with the main thread — each has isolated memory — so they communicate by passing messages. You send data in with workerData or postMessage, and the worker sends results back with its own postMessage. This message passing is the model to keep in mind, because it has a cost: data sent between threads is, by default, copied. For large payloads that copy is not free, and if you are shuttling big buffers back and forth constantly, the copying overhead can eat into the benefit of parallelizing.

Node offers ways to reduce this. ArrayBuffers can be transferred rather than copied — ownership moves to the worker and the sender loses access, which is instant regardless of size — and SharedArrayBuffer lets threads share a block of memory directly. These are worth knowing for high-throughput cases, but for most uses the plain copy is fine; just be aware that the boundary between threads is a real cost, not a free function call.

Use a pool, not a worker per task

Spawning a worker is not free — each one starts a fresh V8 instance, which takes time and memory. Creating a new worker for every request would trade your CPU problem for a startup-overhead problem. The standard pattern is a worker pool: create a fixed set of workers up front and hand incoming tasks to whichever one is free, reusing them across many tasks. This amortizes the startup cost and bounds how many threads you run, since spawning unlimited workers would oversubscribe your cores and slow everything down. Libraries like Piscina implement a solid pool so you do not have to build the queuing and lifecycle management yourself.

When NOT to use worker threads

This is the part people get wrong, so it deserves emphasis: worker threads are for CPU-bound work, not I/O-bound work. If your task is waiting on a database, an API, or the disk, worker threads are the wrong tool, and reaching for them will make your code more complex for no gain. Node already handles I/O concurrently on the main thread through the event loop — that is its whole strength. Wrapping a database query in a worker adds thread overhead and message-passing cost to solve a problem that did not exist, because the query was never blocking the thread in the first place.

The test is simple: is the task spending its time computing or waiting? If it is computing — crunching numbers, transforming data, compressing, hashing — that is CPU-bound and a candidate for a worker. If it is waiting on something external, it is I/O-bound, and it belongs on the main thread with ordinary async patterns. Getting this distinction right is most of using worker threads well.

Workers versus clustering versus a separate service

Worker threads are one of three ways to get past the single-thread limit, and they solve a specific slice of it. Use worker threads to move CPU-bound work off the main thread within one process. Use the cluster module to run multiple Node processes so you use all the machine's cores for handling requests, which is about throughput across the whole app rather than offloading one heavy task. And for very heavy or long-running computation, moving the work to a separate service behind a message queue is often cleaner than keeping it in the request process at all, because it isolates the heavy work entirely and lets you scale it independently.

Worker threads fit in the middle: heavier than an async call, lighter than a separate service, and exactly right when you have occasional CPU-bound tasks that would otherwise block the loop. Reach for them when the profiler shows the main thread pinned on computation — and leave them alone when it is just waiting on I/O.

Originally published at amanksingh.com.

Node.js Streams and Backpressure: Processing Data Without Running Out of Memory

Aman Kumar Singh — Fri, 24 Jul 2026 10:00:21 +0000

The difference between a Node service that handles a 2 GB file on a 512 MB server and one that crashes trying is almost always streams. The naive approach reads the whole thing into memory, does something, and writes it out — and it works beautifully until the input is bigger than the memory you have. Streams process data in chunks as it flows, so memory stays flat regardless of how large the data gets. They are one of Node's most powerful features and one of its most avoided, usually because backpressure — the mechanism that keeps a fast producer from overwhelming a slow consumer — is misunderstood.

This is part of the Node.js runtime series. Here we cover the stream types, piping, and the backpressure that makes it all safe.

Why streams instead of buffering everything

Consider serving a large file. The obvious version reads it entirely, then sends it:

const data = await fs.readFile("huge-video.mp4") // entire file into memory
res.end(data)

If the file is 2 GB, this allocates 2 GB before sending a single byte, and a handful of concurrent requests exhausts your memory and takes the process down. The streaming version never holds more than a small chunk at a time:

fs.createReadStream("huge-video.mp4").pipe(res)

This reads the file in pieces and writes each piece to the response as it goes, so memory usage stays low and constant no matter the file size, and the client starts receiving data immediately instead of after the whole file is buffered. The principle generalizes: any time you process data that is large, unbounded, or arriving over time, streaming keeps memory flat where buffering grows without limit. This is the same "process it in pieces, do not hold it all" instinct behind message queues at the system level.

The four stream types

Node has four kinds of streams, and once you know them the API stops looking arbitrary.

Readable streams are sources you read from: a file being read, an incoming HTTP request, process.stdin.
Writable streams are destinations you write to: a file being written, an HTTP response, process.stdout.
Duplex streams are both readable and writable, with the two sides independent — a TCP socket, which you both send to and receive from.
Transform streams are duplex streams where the output is a transformation of the input: compression, encryption, or parsing, where bytes go in one side and modified bytes come out the other.

Streams are built on the EventEmitter pattern — a readable stream emits data events as chunks arrive and an end event when it is done. You can listen to those events directly, but you rarely should, because doing so by hand is where the backpressure bugs come from.

Piping connects streams safely

The idiomatic way to move data from a readable to a writable stream is pipe, which connects them and handles the flow control for you:

readable.pipe(transform).pipe(writable)

This reads from the source, passes chunks through the transform, and writes to the destination, and it manages the pace automatically. You can chain pipes to build a pipeline — read a file, gzip it, write it out — and each stage only receives data as fast as the next stage can accept it. That automatic pacing is backpressure, and it is the reason to prefer pipe (or the modern pipeline helper) over wiring up data events yourself.

Backpressure: the concept that makes streams safe

Here is the problem streams have to solve. A readable stream might produce data far faster than a writable stream can consume it — reading from a fast local disk and writing to a slow network socket, for instance. If the reader just keeps pushing chunks at the writer, the unconsumed chunks pile up in memory, and now you have reinvented the exact out-of-memory problem streams were supposed to prevent, just with extra steps.

Backpressure is the feedback signal that prevents this. When you write to a writable stream, its write() method returns a boolean: true means "keep going," false means "my buffer is full, pause." A properly behaved reader sees that false, stops producing, and waits for the writable stream to emit a drain event signaling it has caught up, then resumes. This back-and-forth keeps the amount of in-flight data bounded no matter how mismatched the two speeds are. The producer is throttled to the consumer's pace, so memory stays flat even when a fast source feeds a slow sink.

The good news is that pipe and pipeline implement this handshake for you. When you pipe a readable into a writable, Node automatically pauses the source when the destination's buffer fills and resumes it on drain. This is the single biggest reason to use piping rather than manual data event handlers: the moment you write your own on("data") loop that calls write() without checking its return value, you have disabled backpressure and reintroduced the memory blow-up. Let piping do it, and backpressure is handled correctly by default.

Use pipeline for error handling

One practical upgrade over raw pipe: the stream.pipeline function. Plain pipe does not forward errors well — if a stage fails mid-flow, you can leak file descriptors or leave streams half-open. pipeline wires the stages together with proper error propagation and cleanup:

const { pipeline } = require("node:stream/promises")

await pipeline(
  fs.createReadStream("input.txt"),
  zlib.createGzip(),
  fs.createWriteStream("output.txt.gz")
)
// resolves when done, rejects (and cleans up) if any stage fails

This gives you the memory safety of streaming, the automatic backpressure of piping, and error handling that does not leak resources — which is what you want in production. It ties directly into the error-handling patterns for the rest of your Node code.

When to reach for streams

The signal is data that is large, unbounded, or time-based. Big file uploads and downloads, processing a multi-gigabyte log or CSV, proxying data between services, real-time feeds, anything where the total size is unknown or could exceed memory — all of these are streams. If you ever find yourself reading an entire large thing into a variable before processing it, that is the moment to ask whether a stream would keep your memory flat instead. Streams have a reputation for being fiddly, but nearly all of that reputation comes from people handling data events manually and getting backpressure wrong. Use pipeline, let it manage the flow, and streams become the straightforward, memory-safe tool they were designed to be — a direct application of keeping the event loop free and memory bounded that defines good Node.

Originally published at amanksingh.com.

Node.js Async Patterns: Callbacks, Promises, and async/await

Aman Kumar Singh — Fri, 24 Jul 2026 09:57:34 +0000

Asynchronous code is the native language of Node.js. Because the runtime hands off I/O and keeps the event loop free, almost everything useful you do — reading a file, querying a database, calling an API — returns its result later, not immediately. How you express "do this, then when it finishes do that" has evolved through three generations in Node, and while modern code lives almost entirely in the third, understanding all three is what lets you read any codebase and avoid the traps each one carries.

This is part of the Node.js runtime series. Here we walk from callbacks through Promises to async/await, plus the EventEmitter pattern that sits alongside them.

Callbacks and the pyramid problem

The original async pattern in Node is the callback: you pass a function that gets called when the operation completes. Node's convention is the "error-first" callback, where the first argument is an error (or null) and the rest is the result.

fs.readFile("config.json", "utf8", (err, data) => {
  if (err) return handleError(err)
  console.log(data)
})

This works, and for a single operation it is perfectly clear. The trouble starts when operations depend on each other, because each dependent step nests inside the previous callback:

readFile("a.json", (err, a) => {
  if (err) return handleError(err)
  readFile("b.json", (err, b) => {
    if (err) return handleError(err)
    readFile("c.json", (err, c) => {
      if (err) return handleError(err)
      // finally do something with a, b, c
    })
  })
})

This is "callback hell" — the rightward drift, the repeated error checks, the difficulty of following the flow. Worse than the ugliness is the error handling: every callback has to check and forward its own error, and forgetting one means a silent failure. Callbacks are not wrong, and you will still see them in older APIs and event-based code, but for sequential async logic they scale badly.

Promises make async composable

A Promise is an object representing a value that will exist eventually — it is pending, then either fulfilled with a value or rejected with an error. The shift Promises bring is that async operations become values you can pass around and chain, rather than callbacks you nest.

readFile("a.json")
  .then(a => readFile("b.json"))
  .then(b => readFile("c.json"))
  .then(c => { /* ... */ })
  .catch(handleError)

The nesting flattens into a chain, and — the big win — a single .catch at the end handles an error from any step. A rejection skips the remaining .then handlers and jumps to the nearest .catch, so you get centralized error handling for free instead of a check in every callback. Promises also compose in ways callbacks cannot. Promise.all runs several operations concurrently and waits for all of them, which is how you parallelize independent work:

const [a, b, c] = await Promise.all([
  readFile("a.json"),
  readFile("b.json"),
  readFile("c.json"),
])

Running independent operations with Promise.all instead of sequentially is one of the easiest performance wins in Node, since the three reads happen at once rather than one after another. Related combinators — Promise.allSettled when you want every result regardless of failures, Promise.race for the first to finish — cover the other common shapes.

async/await is Promises that read like sync code

async/await is not a replacement for Promises; it is syntax built on top of them. An async function returns a Promise, and await pauses the function until a Promise settles, giving you the value. The payoff is that asynchronous code reads top-to-bottom like ordinary synchronous code, while still being non-blocking underneath.

async function loadConfig() {
  try {
    const a = await readFile("a.json")
    const b = await readFile("b.json")
    return merge(a, b)
  } catch (err) {
    handleError(err)
  }
}

This is the same logic as the Promise chain, but the control flow is linear, and errors are handled with an ordinary try/catch — the same construct you use for synchronous errors, which is exactly the unification covered in the error handling post. It is the right default for essentially all new Node code.

The one pitfall to name: await in a loop runs operations one at a time, which is correct when each depends on the last but a silent performance killer when they are independent. If the iterations do not depend on each other, collect the Promises and await Promise.all instead of awaiting inside the loop. And remember the event-loop lesson — await only yields on genuinely async work; awaiting something that does heavy synchronous computation still blocks the thread.

EventEmitter for streams of events

Callbacks, Promises, and async/await all model a single future value. Some things in Node are not one value but a stream of events over time — a server receiving many requests, a file being read in chunks, a socket emitting data repeatedly. For those, Node uses the EventEmitter pattern: an object emits named events, and you register listeners that run each time an event fires.

server.on("request", (req, res) => { /* runs for every request */ })
emitter.on("data", chunk => { /* runs for every chunk */ })
emitter.once("end", () => { /* runs one time */ })

on subscribes to every occurrence, once to a single one. This is a different shape from a Promise — a Promise resolves exactly once, while an emitter fires as often as the event occurs — and it is the foundation that streams are built on. When you find yourself wanting a Promise to resolve multiple times, an EventEmitter (or an async iterator) is the pattern you actually want.

Which to use

For new code, async/await is the default, backed by Promises and their combinators for concurrency. Reach for Promise.all whenever independent operations can run at once. Use EventEmitter when you are modeling repeated events rather than a single result. And recognize callbacks when you meet them in older APIs — you can usually wrap a callback-based function in a Promise (Node's util.promisify does exactly this) to bring it into the modern style. Underneath all of them is the same runtime behavior: the operation is handed off, the thread stays free, and your continuation runs when the result is ready. The patterns are just increasingly pleasant ways to express that one idea.

Originally published at amanksingh.com.

The Node.js Event Loop Explained: How Single-Threaded Serves Thousands

Aman Kumar Singh — Fri, 24 Jul 2026 09:54:37 +0000

Almost every confusing thing about Node.js — why a slow function freezes your entire server, why setTimeout(fn, 0) does not run immediately, why a Promise resolves before a timer you set first — traces back to one mechanism: the event loop. Node runs your JavaScript on a single thread, and the event loop is how a single thread manages to serve thousands of concurrent connections without blocking. Understand it and the rest of Node stops being a collection of quirks and becomes a coherent system. Misunderstand it and you will eventually write the one function that takes the whole process down.

This is the anchor of a series on the Node.js runtime, which goes deep on async patterns, streams, worker threads, clustering, memory and profiling, and error handling. Start here, because all of them assume this model.

Single-threaded, but not single-tasking

The headline fact is that your JavaScript in Node runs on a single thread. There is one call stack, and only one thing executes at a time. The obvious question is how that serves thousands of simultaneous requests, and the answer is the distinction that everything hinges on: Node does your JavaScript on one thread, but it does not do your I/O there.

When your code asks to read a file, query a database, or make a network call, Node does not sit and wait. It hands that operation off — to the operating system, or to a small pool of background threads managed by a C library called libuv — and immediately moves on to run other JavaScript. When the I/O finishes, the result comes back as a callback that Node queues up to run when the thread is free. So the single thread is almost never blocked waiting; it is constantly doing useful work while dozens of I/O operations proceed in the background. This is why Node is exceptional at I/O-heavy workloads like APIs and proxies, and it is the whole reason the runtime exists.

The critical corollary: this only works if your JavaScript never hogs the thread. Node's concurrency comes from the thread being free to pick up the next callback. A function that runs a long synchronous loop holds the thread and every other request waits behind it. That is the failure mode to keep in mind through everything below.

What the event loop actually is

The event loop is the coordinator that decides what runs next on that single thread. It is a loop that runs continuously, and on each turn it works through a series of phases, each with its own queue of callbacks. Simplified, the phases in order are:

Timers — callbacks scheduled by setTimeout and setInterval whose time has come.
Pending callbacks — certain deferred I/O callbacks.
Poll — where the loop spends most of its time: it retrieves new I/O events and runs their callbacks (an incoming request, a finished file read).
Check — callbacks scheduled with setImmediate.
Close — cleanup callbacks like a socket closing.

On each iteration, the loop enters a phase, drains that phase's queue of ready callbacks, and moves to the next. When it has gone through all phases, it loops again. If there is nothing left to do — no timers pending, no I/O outstanding — the loop exits and the process ends. This phase structure explains a lot of Node's ordering behavior, including why setTimeout(fn, 0) and setImmediate(fn) can fire in either order depending on context: they live in different phases.

Microtasks jump the queue

There is a second, higher-priority queue layered on top of the phases: the microtask queue, which holds resolved Promise callbacks (the .then handlers, and the continuations after await) and process.nextTick callbacks. The rule that matters: microtasks run between every operation, not on a phase of their own. After each individual callback finishes, and before the loop moves on, Node completely drains the microtask queue.

This is why a Promise resolved "later" in your code can run before a setTimeout(fn, 0) you scheduled "first":

setTimeout(() => console.log("timeout"), 0)
Promise.resolve().then(() => console.log("promise"))
// Output:
// promise
// timeout

The Promise's callback is a microtask, so it runs as soon as the current synchronous code finishes, before the loop even gets to the timers phase. The timer, despite a delay of zero, has to wait for the next timers phase. Once you internalize that microtasks drain between operations while timers and I/O wait for their phase, Node's execution order stops being surprising. It also carries a warning: because microtasks run to exhaustion before the loop proceeds, a Promise chain that endlessly schedules more microtasks can starve the loop and block I/O just as badly as a synchronous loop can.

Blocking the loop is the cardinal sin

Everything about Node's performance model comes down to keeping the event loop turning. Because there is one thread for your JavaScript, any single piece of code that runs too long delays every pending callback behind it — every queued request, every ready I/O result. A CPU-heavy task is the classic culprit:

app.get("/report", (req, res) => {
  const result = crunchNumbersForTwoSeconds() // blocks the whole process
  res.json(result)
})

While crunchNumbersForTwoSeconds runs, the event loop cannot advance. Not one other request is served, no matter how many are waiting. For those two seconds, your multi-thousand-connection server handles exactly nobody. This is the single most important thing to understand about Node in production: the runtime is superb at juggling I/O, and helpless against CPU-bound work on the main thread.

The fix is not to make the main thread do the heavy work faster; it is to get the heavy work off the main thread entirely. Genuinely CPU-bound tasks belong in worker threads, which run JavaScript on separate threads for exactly this purpose, or in a separate service reached through a message queue. To use every core on the machine rather than one, you run multiple Node processes with the cluster module. Both are ways of respecting the same rule: the event loop must stay free.

The model to carry forward

Hold onto this picture and the rest of Node follows from it. One thread runs your JavaScript. I/O is handed off and comes back as queued callbacks, so the thread stays busy instead of waiting. The event loop cycles through phases, draining callbacks, with microtasks squeezing in between every operation at higher priority. And the whole thing works only as long as no callback monopolizes the thread. Async patterns are how you write code that cooperates with this model, streams are how you process large data without blocking, and profiling is how you find the code that accidentally does. It all comes back to the loop.

Originally published at amanksingh.com.

Structured Logging for Node.js

Aman Kumar Singh — Fri, 24 Jul 2026 07:06:18 +0000

In Monitoring a SaaS in Production we wired up metrics and alerts so the team knows something is wrong within minutes of it happening. Metrics tell you a spike exists. They rarely tell you why. That's a logging problem, and it's the one we're solving here.

This is part of the Full Stack SaaS Masterclass, a build-it-for-real series taking a multi-tenant SaaS from an empty folder to production. Module 4 covers the operational concerns that separate a demo from a product a team can actually run. Logging sits at the base of that stack: incident response, support tickets, and audit trails all eventually route back to "what does the log say."

Most Node.js apps start with console.log and stay there far longer than they should, because it works fine on a laptop with one request at a time. It stops working the moment two requests are in flight concurrently and their log lines interleave in a shared terminal, or a customer support ticket needs an answer and the only tool available is grep against a wall of unstructured text. Structured logging fixes that, and it's cheap enough to set up early that there's little reason to defer it.

Why plain text logs stop working

A console.log call produces a string. Strings are fine for a human staring at a terminal, and actively hostile to any system trying to query logs at scale. Once logs move to CloudWatch, Datadog, or any aggregator, every downstream tool ends up parsing that string back apart with regex to extract the fields it actually needs: request ID, user ID, status code, duration. Regex-based parsing is brittle. A one-word change to a log message breaks every saved search and alert built against it.

Structured logging inverts the approach: instead of writing a sentence and hoping someone can parse it later, you write a JSON object with named fields from the start.

{
  "level": "error",
  "time": "2023-09-14T10:22:31.482Z",
  "requestId": "8f14e45f-ceea-467e-add1-a889b9f6bfaa",
  "organizationId": "org_9f2c1a",
  "userId": "usr_71b30d",
  "route": "POST /invoices",
  "statusCode": 500,
  "durationMs": 812,
  "msg": "Failed to create invoice: unique constraint violation"
}

Every field here is queryable without parsing. "Show me every 500 for organization org_9f2c1a in the last hour" is a filter, not a regex. That difference is the entire value proposition, and it compounds as the system grows: the tenth engineer debugging an incident benefits from the same structured fields the first one set up.

Picking a logging library and wiring it into NestJS

Node.js has a few solid structured logging libraries. pino is a reasonable default for a NestJS backend. It's built around minimizing per-call overhead (JSON serialization with a fast path, rather than the general-purpose JSON.stringify most loggers rely on), and it integrates cleanly with NestJS through nestjs-pino.

// main.ts
import { NestFactory } from '@nestjs/core';
import { Logger } from 'nestjs-pino';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { bufferLogs: true });
  app.useLogger(app.get(Logger));
  await app.listen(3000);
}
bootstrap();

// logger.module.ts
import { Module } from '@nestjs/common';
import { LoggerModule } from 'nestjs-pino';

@Module({
  imports: [
    LoggerModule.forRoot({
      pinoHttp: {
        level: process.env.LOG_LEVEL ?? 'info',
        redact: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.token'],
        serializers: {
          req: (req) => ({ method: req.method, url: req.url }),
          res: (res) => ({ statusCode: res.statusCode }),
        },
        transport:
          process.env.NODE_ENV === 'development'
            ? { target: 'pino-pretty', options: { singleLine: true } }
            : undefined,
      },
    }),
  ],
})
export class AppLoggerModule {}

Two things matter in that config beyond the obvious. First, redact is not an afterthought; it's the difference between a log line and a leaked credential, and it belongs in the initial setup rather than a follow-up ticket after a security review flags it. Second, the pino-pretty transport is scoped to development only. In production you want raw JSON going to stdout, because that's what your log aggregator expects, and pretty-printing it first just adds CPU work nobody reads.

With that in place, injecting the logger into a service is direct:

import { Injectable } from '@nestjs/common';
import { InjectPinoLogger, PinoLogger } from 'nestjs-pino';

@Injectable()
export class InvoiceService {
  constructor(@InjectPinoLogger(InvoiceService.name) private readonly logger: PinoLogger) {}

  async createInvoice(organizationId: string, amount: number): Promise<void> {
    this.logger.info({ organizationId, amount }, 'Creating invoice');

    try {
      // ... invoice creation logic
    } catch (error) {
      this.logger.error({ organizationId, err: error }, 'Invoice creation failed');
      throw error;
    }
  }
}

The err field matters here: pino's default error serializer expands an Error object into its message and stack trace as separate JSON fields, rather than the string interpolation you'd get from console.log(error). That's what lets you search for a specific exception type across every service without opening individual log lines.

Threading a correlation ID through every log line

A single log line is rarely useful on its own during an incident. What you actually want is every log line that belongs to one request, across every service it touched, and structured fields alone don't get you there unless every one of those lines shares a common ID. That's what a correlation ID (often called a request ID or trace ID) is for.

The cleanest way to propagate it through a NestJS app without threading it as a parameter through every function call is Node's AsyncLocalStorage, which gives each request its own isolated context that survives across await boundaries.

// request-context.ts
import { AsyncLocalStorage } from 'async_hooks';
import { randomUUID } from 'crypto';

interface RequestContext {
  requestId: string;
  organizationId?: string;
}

export const requestContext = new AsyncLocalStorage<RequestContext>();

export function getRequestId(): string {
  return requestContext.getStore()?.requestId ?? 'no-context';
}

// request-context.middleware.ts
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { randomUUID } from 'crypto';
import { requestContext } from './request-context';

@Injectable()
export class RequestContextMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction): void {
    const requestId = (req.headers['x-request-id'] as string) ?? randomUUID();
    res.setHeader('x-request-id', requestId);

    requestContext.run({ requestId }, () => next());
  }
}

Any logger call anywhere in that request's call stack, including inside a queue job triggered by it if the ID is forwarded onto the job payload, can now pull getRequestId() and attach it automatically. Wire it into the pino config's mixin option so it's never something an engineer has to remember to pass explicitly:

LoggerModule.forRoot({
  pinoHttp: {
    mixin() {
      return { requestId: getRequestId() };
    },
  },
});

This is the single highest-leverage addition to a logging setup after structure itself. Without it, reconstructing "everything that happened during this one failed checkout" means guessing at timestamps and hoping nothing else was happening concurrently. With it, it's one query.

Tradeoffs: what structured logging costs you

None of this is free, and the costs deserve an honest look before you treat it as an obvious win.

Structured logs are less pleasant to read directly in a terminal during local development, which is why the pino-pretty transport above exists specifically to soften that for local work while keeping production output as raw JSON. Serialization has a real, if small, CPU cost per log call, which matters if a hot path logs on every iteration of a loop rather than once per request. And redaction configuration needs upkeep. Every new field that might carry a credential, a password, an API key, a session token, needs to be added to the redact list, and that list is easy to forget about once the initial setup is done.

The upside outweighs those costs for almost any SaaS backend past the earliest prototype stage, but it's worth naming them rather than pretending structured logging is a pure upgrade with no maintenance surface.

Production pitfalls worth planning for

Logging PII into unstructured fields. Structure doesn't prevent someone from putting a customer's email address into a free-form msg string or a properties object nobody's reviewing. Redaction rules only catch fields they know about by name; treat any new field added to a log call with the same scrutiny you'd apply to an API response.

Log volume outpacing what you're willing to pay for. Structured JSON logs are larger per line than a terse text message, and verbose debug-level logging left on in production multiplies that. Set LOG_LEVEL per environment, default to info in production, and reserve debug for a deliberate, time-boxed investigation rather than a permanent setting.

Losing logs during a graceful shutdown. If the process exits before the transport finishes flushing buffered log lines, whatever explains a crash is exactly what's missing from the aggregator. Make sure your shutdown hook waits for the logger to flush before the process exits, particularly if logs are batched before being sent off-box.

Correlation IDs that stop at the HTTP boundary. A request ID that only exists inside the API process is far less useful than one forwarded onto every downstream call: the BullMQ job it enqueues, the outbound HTTP call to a third-party API, the message published to another service. Forward it deliberately at every boundary, or the trail goes cold exactly where an incident usually gets interesting.

Key takeaways

Structured logs are JSON objects with named fields, not sentences, which makes them queryable by an aggregator instead of requiring brittle regex parsing.
Pino is a solid default for a NestJS backend: fast JSON serialization, first-class NestJS integration through nestjs-pino, and built-in redaction and error serialization.
Redaction rules for credentials and tokens belong in the initial setup, not a follow-up ticket after a security review.
AsyncLocalStorage lets you attach a request-scoped correlation ID to every log line automatically, which is the difference between reconstructing an incident in one query versus guessing at timestamps.
Keep production log level at info by default and reserve debug for deliberate, time-boxed investigation, since verbose logging has a real cost once it's shipped to an aggregator.
Forward correlation IDs across every boundary, HTTP calls, queue jobs, webhooks, or the trail goes cold exactly where an incident gets hard to debug.

FAQ

What is structured logging?
Structured logging means writing log entries as objects with named, typed fields (like requestId, statusCode, organizationId) instead of free-form text sentences. It lets log aggregators and query tools filter and search on those fields directly, rather than parsing a message string with regex.

Is pino better than winston for a Node.js backend?
Both are capable structured logging libraries. Pino is generally the faster choice for JSON serialization and integrates directly with NestJS through nestjs-pino, which is why it's a common default for new NestJS projects. Winston has a longer track record and a larger plugin ecosystem, which can matter if you need a specific transport it already supports.

How do I correlate logs across multiple services in a request?
Generate or forward a correlation ID (often called a request ID or trace ID) at the edge of your system, store it in an AsyncLocalStorage context for the duration of the request, and forward it explicitly on every downstream call, including queue jobs and outbound HTTP requests. Every log line that reads from that context can then attach the same ID automatically.

What should never appear in a log line?
Passwords, session tokens, API keys, authorization headers, and full payment card details should never be logged in plain form. Configure redaction rules for known sensitive field names at the logger level, and treat any new field added to a log call with the same review scrutiny you'd apply to an API response.

Should I log at debug level in production?
Generally no. Default production log level to info and reserve debug for a deliberate, time-boxed investigation, since debug-level logging multiplies volume and cost across every request without a corresponding benefit most of the time.

Does structured logging replace the need for a metrics or tracing system?
No. Metrics tell you something is wrong quickly, tracing shows you how a request moved across services, and logs explain the specific reason a given request failed. They're complementary, and the correlation ID described here is what lets you move between all three during an incident without losing context.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Audit Logs You Can Trust

Aman Kumar Singh — Fri, 24 Jul 2026 07:06:16 +0000

In Structured Logging for Node.js, I covered how to turn scattered console.log calls into structured, queryable events. That solves the "what happened in the system" problem. It does not solve a different, harder problem: proving what a specific user did to a specific piece of data, at a specific time, in a way that a customer's compliance team or your own support engineer can trust months later.

That is what an audit log is for. This is part of the Full Stack SaaS Masterclass series, and it sits at the point in a product's life where "we should probably log who deleted that" stops being a nice-to-have and starts being a support ticket, a security incident, or a line item in an enterprise contract.

Why audit logs are a different beast than application logs

Application logs answer "why did this request fail" or "how long did this query take." They're written for engineers, they're allowed to be noisy, and losing a percentage of them during an incident is an acceptable tradeoff for keeping the system up.

Audit logs answer "who did this, and can we prove it." The audience is different too: support staff investigating a complaint, a security team responding to an incident, an auditor checking SOC 2 evidence, or a customer's own admin looking at their organization's activity feed. Each reader needs a record that is complete, immutable, and attributable to a real actor.

This changes the requirements in three ways:

Completeness matters more than throughput. Dropping an audit entry under backpressure is worse than slowing down the request that triggered it.
Immutability matters. If the same code path that writes the log can also update or delete it, the log has no evidentiary value.
Actor identity matters more than a stack trace. You need "user 412 in organization 9, acting through API key X," not just "PATCH /invoices/88 returned 200."

A team building a SaaS product from scratch often reaches for audit logs too early, wiring them into every table with a generic trigger before they know which actions need auditing. I'd resist that. Start with the actions a customer, an auditor, or your support team would actually ask about, and expand as real questions come in.

What actually belongs in an audit entry

A useful audit record needs enough context to answer "who, what, when, where, and what changed" without a database migration to add a missing column later. A reasonable baseline schema:

create table audit_logs (
  id            bigserial primary key,
  occurred_at   timestamptz not null default now(),
  organization_id uuid not null references organizations(id),
  actor_id      uuid references users(id),
  actor_type    text not null default 'user', -- 'user' | 'api_key' | 'system'
  action        text not null,                -- e.g. 'invoice.updated'
  target_type   text not null,                -- e.g. 'invoice'
  target_id     text not null,
  ip_address    inet,
  user_agent    text,
  before_state  jsonb,
  after_state   jsonb,
  metadata      jsonb not null default '{}'::jsonb
);

create index idx_audit_logs_org_time on audit_logs (organization_id, occurred_at desc);
create index idx_audit_logs_target on audit_logs (organization_id, target_type, target_id);

A few of these choices are worth explaining rather than assuming.

action is a stable string, not a free-text description. Something like invoice.updated or member.role_changed lets you filter, alert, and build a customer-facing activity feed without parsing prose. Treat this naming with the same discipline you'd use for event names in an event-driven system: pick a convention early (resource.verb) and don't deviate per team.

Storing before_state and after_state as separate JSONB columns, rather than one combined diff, makes it trivial to render "changed status from draft to sent" without re-deriving anything from a patch document. There's a storage cost, though. For large records, log only the fields that changed, not the entire row, or a customer's big JSON blob will bloat this table fast.

organization_id on every row is non-negotiable in a multi-tenant system. Every query against this table should assume tenant scoping is the first filter, not an afterthought applied at the API layer.

Writing audit entries without polluting business logic

The naive approach is to call an auditLogService.log(...) at the end of every controller method that changes something. It works, but it's easy to forget, and it couples business logic to audit concerns in a way that makes both harder to test.

A cleaner pattern in NestJS is an interceptor that reads metadata off the route and emits an audit event after the handler succeeds, combined with a decorator so the intent is visible on the route itself:

// audit-log.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const AUDIT_ACTION_KEY = 'auditAction';

export interface AuditOptions {
  action: string;
  targetType: string;
}

export const Audit = (options: AuditOptions) =>
  SetMetadata(AUDIT_ACTION_KEY, options);

// audit-log.interceptor.ts
import {
  CallHandler,
  ExecutionContext,
  Injectable,
  NestInterceptor,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';
import { AUDIT_ACTION_KEY, AuditOptions } from './audit-log.decorator';
import { AuditLogService } from './audit-log.service';

@Injectable()
export class AuditLogInterceptor implements NestInterceptor {
  constructor(
    private readonly reflector: Reflector,
    private readonly auditLogService: AuditLogService,
  ) {}

  intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {
    const options = this.reflector.get<AuditOptions | undefined>(
      AUDIT_ACTION_KEY,
      context.getHandler(),
    );

    if (!options) {
      return next.handle();
    }

    const request = context.switchToHttp().getRequest();

    return next.handle().pipe(
      tap((result) => {
        void this.auditLogService.record({
          organizationId: request.user.organizationId,
          actorId: request.user.id,
          actorType: 'user',
          action: options.action,
          targetType: options.targetType,
          targetId: result?.id ?? request.params.id,
          ipAddress: request.ip,
          userAgent: request.headers['user-agent'],
          metadata: {},
        });
      }),
    );
  }
}

// invoices.controller.ts
import { Controller, Patch, Param, Body, UseInterceptors } from '@nestjs/common';
import { AuditLogInterceptor } from '../audit-log/audit-log.interceptor';
import { Audit } from '../audit-log/audit-log.decorator';

@Controller('invoices')
@UseInterceptors(AuditLogInterceptor)
export class InvoicesController {
  @Patch(':id')
  @Audit({ action: 'invoice.updated', targetType: 'invoice' })
  update(@Param('id') id: string, @Body() dto: UpdateInvoiceDto) {
    return this.invoicesService.update(id, dto);
  }
}

This keeps the service method free of audit-specific code and makes audited actions visible by scanning routes rather than reading every service. The interceptor only runs after the handler succeeds, which is deliberate: you generally want to audit what happened, not what was attempted and rejected. If you also need to record failed or denied attempts, useful for security-sensitive actions like permission changes, add a second interceptor or a guard-level hook rather than overloading this one.

One thing this pattern does not capture well is before_state. If you need the previous value for a diff, fetch it in the service before the mutation and pass it through request-scoped context, or have the service call the audit writer directly for that case. Don't force every audited action through the same mechanism if the data shape genuinely differs; an inconsistent implementation that captures the right data beats a uniform one that captures the wrong data.

Making the log tamper-evident, not just tamper-resistant

Restricting write access to the audit_logs table with database permissions is the first layer: no application role should have UPDATE or DELETE grants, only INSERT and SELECT. But permissions protect against accidental misuse, not against someone with superuser access or a compromised deployment credential.

For genuine tamper-evidence, the common technique is hash chaining. Each row stores a hash of its own content plus the hash of the previous row, so altering any historical entry breaks the chain and is detectable on verification.

import { createHash } from 'crypto';

function computeEntryHash(entry: {
  previousHash: string;
  occurredAt: string;
  action: string;
  targetId: string;
  actorId: string;
}): string {
  const payload = `${entry.previousHash}|${entry.occurredAt}|${entry.action}|${entry.targetId}|${entry.actorId}`;
  return createHash('sha256').update(payload).digest('hex');
}

Whether you need this depends entirely on your compliance target. Most early-stage SaaS products don't need cryptographic hash chains; restricted database grants, an append-only table, and shipping a copy of the logs to a write-once store (S3 with Object Lock, for instance) cover the realistic threat model. Reach for hash chaining when a specific compliance framework or a customer's security review demands proof of non-tampering, not by default. Building it earlier than that is complexity your team maintains for years without a corresponding benefit.

Retention, access, and the customer-facing activity feed

An audit log that nobody can query is just storage cost. Two consumers usually want access: your internal support and security teams, and the customer's own admins, who increasingly expect an "activity log" tab in the product itself.

For the internal case, keep the raw audit_logs table as the source of truth and build read paths on top of it rather than giving broad database access to support staff. For the customer-facing case, expose only a filtered subset: internal actions like background jobs, staff impersonation, or debugging generally should not appear in a customer's activity feed, and fields like raw IP addresses may need scrubbing.

Retention is a policy decision as much as a technical one. Regulated customers commonly expect years of retention; a typical SaaS product without that requirement can move audit rows older than a year or two into cheaper storage, keeping the hot table fast for recent activity and active investigations. Partitioning audit_logs by month, similar to a high-volume event table in PostgreSQL, makes this rollover mechanical instead of a manual job you have to remember to run.

Production pitfalls worth naming directly

A few mistakes show up repeatedly once teams start relying on audit logs for real incidents:

Writing the audit entry inside the same transaction as the business mutation, then rolling both back on an unrelated later error. A failure elsewhere in the transaction can silently erase evidence that something was attempted. Decide deliberately whether audit writes should be transactional or best-effort and asynchronous; both are valid, but pick one on purpose.
Logging the actor as a service account instead of the real user when actions go through a background job. If a scheduled job acts on a user's behalf, the entry should still record which user's data triggered it, ideally alongside the original request that queued the job.
No index on (organization_id, occurred_at). Without it, "show recent activity" becomes a sequential scan on a table that only grows, and it gets slower every month rather than staying flat.
Treating audit logs and structured application logs as the same system. They have different durability, access control, and retention needs. Mixing them into one log stream makes it hard to give a customer's admin visibility into their activity without exposing internal debug traces.

Key takeaways

Audit logs answer "who did this and can we prove it," a different requirement from application logging that deserves its own storage, schema, and access controls.
Design the schema around actor identity, a stable action name, and before/after state, not a free-text description that's hard to query later.
Use a decorator plus interceptor in NestJS to keep audit writes visible on the route and out of business logic, but don't force every action through the same mechanism if the data genuinely differs.
Restrict write access to append-only at the database level first; add cryptographic hash chaining only when a real compliance requirement asks for it.
Separate the customer-facing activity feed from the raw internal audit table, scrubbing internal-only actions before exposing it.
Plan retention and partitioning early; an unindexed, unpartitioned audit table is a quiet way a SaaS database slows down over time.

FAQ

What is the difference between an audit log and an application log?
An application log helps engineers debug behavior and can tolerate sampling or occasional loss. An audit log is a compliance and trust artifact recording who did what to which resource, and it needs completeness, immutability, and a real actor identity.

Should audit log writes be synchronous or asynchronous with the business action?
Either can work, but decide on purpose. Same-transaction writes guarantee the log and the action succeed or fail together, at the cost of coupling. Asynchronous writes protect the request path from audit-write latency, at the cost of needing their own retry or dead-letter handling.

Do I need blockchain or cryptographic hash chaining for audit logs?
Only if a specific compliance framework or customer security review requires proof of non-tampering beyond restricted database access. For most SaaS products, an append-only table with revoked update and delete permissions is a proportionate starting point.

How long should I retain audit logs?
It depends on customer compliance needs more than any general rule. Regulated industries often expect multi-year retention; otherwise, keep recent data in a fast, indexed table and move older rows to cheaper storage on a schedule.

Should the customer-facing activity feed show the same data as the internal audit table?
No. Show customers their own actions in a readable format, and exclude internal-only entries like staff impersonation. The raw table is your source of truth; the feed is a filtered view over it.

Where should audit logging live in a NestJS application?
As a dedicated module invoked through a decorator and interceptor, rather than scattered service.log() calls. This keeps audited actions visible on route definitions and testable in isolation from the business logic they observe.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Feature Flags and Safe Rollouts

Aman Kumar Singh — Fri, 24 Jul 2026 07:06:14 +0000

In Audit Logs You Can Trust, we built a system that answers "who changed what, and when." Feature flags answer a related question: "who gets to see this, and how much of it." Once you trust your audit trail, the natural next step is controlling what actually ships behind it. A flag toggle is exactly the kind of change your audit log should be recording.

This is part of the Full Stack SaaS Masterclass, a build-it-for-real series that takes a multi-tenant SaaS from an empty repo to production. We're deep into Module 4 now: the unglamorous plumbing that separates a demo from something you can run a business on.

Feature flags get a bad reputation because teams either skip them and ship risky all-or-nothing deploys, or bolt on a full experimentation platform before they have a single paying customer. What you actually need, most of the time, is much simpler than either extreme.

Why feature flags earn their place

The core problem a flag solves is decoupling deployment from release. Without flags, "merge to main" and "customers see this" are the same event. That's fine until it isn't: a half-finished billing rewrite sits in a long-lived branch for weeks, and the eventual merge is a nerve-wracking event instead of a routine one.

With flags, you can merge incomplete work behind a flag that's off in production. The code ships continuously; the behavior ships when you decide it's ready. That single decoupling is worth more than the fancier things flags enable later, like percentage rollouts or experiments.

There's a second benefit that gets less attention: flags give you a fast, code-free rollback. If a new feature causes an incident, flipping a boolean in the flags table is a lot faster than reverting a deploy and waiting for CI to build and ship a new image. For anything touching payments, auth, or data integrity, that speed difference matters.

The tradeoff is real, though. Flags are conditional logic, and conditional logic nobody cleans up is technical debt with a timer running. A flag left in after a full rollout becomes a permanent if statement nobody remembers the reason for. Codebases accumulate a dozen "temporary" flags from a year ago, still checked on every request, still branching in tests nobody wants to write. Plan for removal on the day you add the flag, not as an afterthought.

Flag types, and picking the right one

Not every flag needs the same lifecycle or the same evaluation logic. Lumping them together is how flag systems become unmanageable. I find it useful to separate them into four categories:

Release toggles guard incomplete or risky features during rollout. They're meant to be short-lived: turn on, verify, delete the flag and the branching code within a sprint or two.

Ops toggles (kill switches) protect the system itself. Think "disable the recommendation engine if the third-party API is down" or "turn off background email digests during a database migration." These can live indefinitely; they're a safety valve, not a rollout mechanism.

Permission toggles gate a feature by plan tier or organization, like exposing SSO configuration only to enterprise customers. These are effectively long-lived entitlements, closer to authorization than to a rollout flag, and they usually deserve their own model rather than reusing your rollout table.

Experiment toggles split traffic to compare outcomes. This is the category people usually mean by "feature flags" in a growth context, and it carries the most operational overhead: consistent bucketing, an analytics pipeline, and a plan for what happens when the experiment ends. Don't reach for it until you have a hypothesis worth testing and enough traffic for a meaningful signal.

For most SaaS teams before product-market fit, release toggles and a handful of ops toggles cover nearly everything. Permission toggles come naturally once you have paid tiers. Experiment toggles are the category worth deferring the longest.

Building a flag service: Postgres and Redis

You don't need a vendor for this. A table, a cache, and a small service take you a long way, and the mental model stays simple: flags are just rows you query and update like anything else in your system.

CREATE TABLE feature_flags (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  key TEXT NOT NULL UNIQUE,
  description TEXT NOT NULL,
  enabled BOOLEAN NOT NULL DEFAULT false,
  rollout_percentage SMALLINT NOT NULL DEFAULT 0
    CHECK (rollout_percentage BETWEEN 0 AND 100),
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE feature_flag_overrides (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  flag_id UUID NOT NULL REFERENCES feature_flags(id) ON DELETE CASCADE,
  organization_id UUID NOT NULL,
  enabled BOOLEAN NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (flag_id, organization_id)
);

The overrides table matters more than it looks. It's how you handle "turn this on for one pilot customer" without touching the global rollout percentage. Overrides always win over the percentage rule, and that precedence needs to be explicit in the evaluation logic.

Evaluation happens on every request that touches a flagged code path, so it needs to be fast and it needs to survive a Redis outage gracefully. Cache-aside with a short TTL handles the common case; a Postgres fallback handles the cache being cold or down.

// feature-flags.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { createHash } from 'crypto';
import Redis from 'ioredis';
import { FeatureFlag } from './feature-flag.entity';
import { FeatureFlagOverride } from './feature-flag-override.entity';

interface FlagContext {
  organizationId: string;
}

const CACHE_TTL_SECONDS = 30;

@Injectable()
export class FeatureFlagsService {
  private readonly logger = new Logger(FeatureFlagsService.name);

  constructor(
    @InjectRepository(FeatureFlag)
    private readonly flags: Repository<FeatureFlag>,
    @InjectRepository(FeatureFlagOverride)
    private readonly overrides: Repository<FeatureFlagOverride>,
    private readonly redis: Redis,
  ) {}

  async isEnabled(key: string, context: FlagContext): Promise<boolean> {
    const flag = await this.getFlag(key);
    if (!flag) {
      return false;
    }

    const override = await this.getOverride(flag.id, context.organizationId);
    if (override) {
      return override.enabled;
    }

    if (!flag.enabled) {
      return false;
    }

    if (flag.rolloutPercentage >= 100) {
      return true;
    }

    if (flag.rolloutPercentage <= 0) {
      return false;
    }

    return this.isInRolloutBucket(key, context.organizationId, flag.rolloutPercentage);
  }

  private isInRolloutBucket(key: string, organizationId: string, percentage: number): boolean {
    const hash = createHash('sha256').update(`${key}:${organizationId}`).digest();
    const bucket = hash.readUInt32BE(0) % 100;
    return bucket < percentage;
  }

  private async getFlag(key: string): Promise<FeatureFlag | null> {
    const cacheKey = `flag:${key}`;
    const cached = await this.redis.get(cacheKey).catch((err) => {
      this.logger.warn(`Redis unavailable for ${cacheKey}: ${err.message}`);
      return null;
    });

    if (cached) {
      return JSON.parse(cached) as FeatureFlag;
    }

    const flag = await this.flags.findOne({ where: { key } });
    if (flag) {
      await this.redis
        .set(cacheKey, JSON.stringify(flag), 'EX', CACHE_TTL_SECONDS)
        .catch(() => undefined);
    }
    return flag ?? null;
  }

  private async getOverride(flagId: string, organizationId: string) {
    return this.overrides.findOne({ where: { flagId, organizationId } });
  }
}

Hashing the flag key with the organization ID makes the rollout consistent: the same organization always lands in the same bucket for a given flag, so a customer doesn't flicker between "has the feature" and "doesn't" on every request. Changing the flag key changes the bucket assignment too, which stops one flag's rollout from correlating with another's in unplanned ways.

Wrap the check in a small guard or decorator so route handlers stay clean:

// feature-flag.decorator.ts
import { SetMetadata } from '@nestjs/common';

export const FEATURE_FLAG_KEY = 'featureFlag';
export const RequireFeatureFlag = (key: string) => SetMetadata(FEATURE_FLAG_KEY, key);

// feature-flag.guard.ts
import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { FeatureFlagsService } from './feature-flags.service';
import { FEATURE_FLAG_KEY } from './feature-flag.decorator';

@Injectable()
export class FeatureFlagGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly flags: FeatureFlagsService,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const key = this.reflector.get<string>(FEATURE_FLAG_KEY, context.getHandler());
    if (!key) {
      return true;
    }

    const request = context.switchToHttp().getRequest();
    return this.flags.isEnabled(key, { organizationId: request.organizationId });
  }
}

Every write to feature_flags or feature_flag_overrides should go through the audit logging service from the previous article. "Who turned this on" is exactly the question you'll want answered during an incident retro.

Rollout strategy and rolling back

A percentage rollout only helps if you pair it with something to watch. Ramping 5 percent, then 25, then 100 over a few days catches a regression before it reaches everyone, but only if someone is actually watching error rates and support tickets during that window. A rollout plan without a monitoring plan is just a slower way to break things for everyone.

The other half of a safe rollout is a documented, low-friction path back to off: the person on call knows where the flags table lives, has permission to flip it, and doesn't need a deploy to do so. If your only rollback mechanism is redeploying an older image, you haven't actually decoupled deployment from release.

For genuinely risky operations, an ops toggle checked at the top of a job or worker, not just in the HTTP layer, is worth the extra wiring. A queue consumer checking isEnabled('new-billing-sync', ...) before processing a job can be paused independently of the API tier, which matters when the risky code runs outside a request-response cycle entirely.

Tradeoffs and where teams get burned

The most common failure mode is flag accumulation. Teams rarely get the implementation itself wrong. Every flag is a fork in your test matrix; ten flags produce something closer to two to the tenth power of possible states, most of which nobody tests. Set a rule early: release toggles get removed within a sprint or two of reaching 100 percent, with a backlog ticket created the day the flag is added.

Build versus buy is worth an honest look. Vendors like LaunchDarkly, Unleash, and Flagsmith solve real problems: multivariate flags, SDKs across languages, targeting UIs, and analytics tied to experiments. If your team runs many experiment-style flags with product managers who need a UI, that tooling earns its cost quickly. But release and ops toggles, which cover most of what a small SaaS team needs, are simpler to reason about with a Postgres table and a Redis cache, and they don't add another vendor to your uptime dependency graph. Reach for the vendor only when usage actually demands it.

A subtler pitfall: flags gating database schema changes. If a flag controls whether code writes to a new column, and you roll it back after data has already been written under the new behavior, you can end up with inconsistent rows that neither code path expects. Schema-affecting flags need a data rollback plan, not just a code rollback plan, and that plan should exist before the flag reaches 100 percent.

Key takeaways

Feature flags decouple deployment from release, which turns merges into routine events and rollbacks into a config change instead of a redeploy.
Separate flags by purpose: release toggles, ops toggles, permission toggles, and experiment toggles each have different lifecycles and different owners.
A Postgres table plus a Redis cache handles release and ops toggles well; save vendor platforms for when you have real experimentation or targeting needs.
Hash the flag key with a stable identifier (organization or user ID) for consistent, sticky percentage rollouts.
Every flag needs a removal plan from the day it's created, and schema-affecting flags need a data rollback plan, not just a code rollback plan.
Route flag changes through the same audit logging you already built; a toggle in production is a change worth recording.

FAQ

What's the difference between a feature flag and a kill switch?
A kill switch is a specific type of feature flag, usually what we'd call an ops toggle. It stays in the codebase indefinitely and exists to disable a risky or unstable code path quickly, rather than to manage a rollout.

Should feature flag state live in the database or in environment variables?
Environment variables require a redeploy or restart to change, which defeats the main benefit of flags: changing behavior without shipping code. Database-backed flags, cached in Redis, let you toggle behavior instantly while keeping a change history.

How long should a feature flag live before it's removed?
For a release toggle, days to a couple of sprints after it reaches full rollout. Ops toggles and permission toggles can live indefinitely by design, since they serve a different, ongoing purpose.

Do I need a third-party feature flag service like LaunchDarkly for a small SaaS?
Not at first. A flags table with a Redis cache covers release and ops toggles, which is what most small teams need. Consider a vendor once you need multivariate experiments, non-engineer-facing targeting UIs, or SDKs across many languages.

How do I test code that's behind a feature flag?
Write tests for both states explicitly, don't rely on the default. Treat the off state as current production behavior and the on state as the new behavior under test, and keep both covered until the flag is removed.

Can feature flags cause data inconsistency?
Yes, particularly when a flag controls a schema change or new write path. Rolling a flag back after it's written data under the new behavior can leave rows in a state neither code path handles. Plan the data rollback alongside the flag, not just the code rollback.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Deploying a Full Stack SaaS

Aman Kumar Singh — Fri, 24 Jul 2026 07:06:11 +0000

The previous article in this series covered feature flags: how to decouple deploying code from releasing it, so a bad idea can be turned off without a rollback. That only pays off if deploying itself is a boring, repeatable event rather than a stressful one. This article is about making it boring.

This is part of the Full Stack SaaS Masterclass, and it sits at a point where the temptation to overbuild is strongest. Deployment invites that kind of overreach. Engineers reach for Kubernetes and blue-green everything before they have the traffic or the team that justifies any of it. I want to walk through the choices in the order I'd actually make them, honest about which ones are earned early and which aren't.

None of what follows assumes a platform team. It assumes a small team shipping a real product, choosing infrastructure that won't fight them at 2am.

Picking a deployment target without overbuilding

There are roughly three tiers of deployment target, and the right one depends on where you actually are, not where you expect to be in two years.

A single VM (or a couple) running Docker Compose is the honest starting point for most SaaS products. It's the same compose discipline from the local Docker setup article, pointed at a real box instead of your laptop, fronted by Caddy or Nginx for TLS. It's unglamorous. It's also completely capable of running a real product with real paying customers. The failure mode people worry about, a VM going down and taking the app with it, is a real risk, but one you can measure against your actual uptime requirements instead of assuming away.

A managed container platform, ECS Fargate on AWS, Cloud Run on GCP, or a PaaS like Render or Fly.io, is the next tier. You give up some control over the machine in exchange for the platform handling restarts, health checks, and scaling. This is where I'd point most teams once more than one engineer touches infrastructure, since the operational surface area stays small enough that nobody needs to become a full-time platform engineer.

Kubernetes is the tier I'd defer the longest. It solves real problems, multi-service orchestration and fine-grained scaling across a large team, but demands operational maturity (RBAC, network policies, ingress, cluster upgrades) most SaaS products never need. Reaching for it because "serious companies use it" is exactly the complexity this series argues against taking on early. Once you have several services and teams with genuinely different scaling needs, the calculus changes. Until then, it's a cost with no offsetting benefit.

The tradeoff repeats throughout this series: more control costs more operational effort, and that effort should go only where a concrete problem justifies it.

The build and release pipeline

Whatever the target, the pipeline shape is the same: build once, test the build, then promote the same artifact through environments. Building separately for staging and production is a subtle trap: what you test in staging and what you ship to production end up being two different builds.

# .github/workflows/deploy.yml
name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - run: npm run lint

      - run: npm run test

      - name: Build API image
        run: |
          docker build \
            --target production \
            -t ${{ secrets.ECR_REGISTRY }}/api:${{ github.sha }} \
            -f apps/api/Dockerfile .

      - name: Push image
        run: |
          aws ecr get-login-password --region us-east-1 | \
            docker login --username AWS --password-stdin ${{ secrets.ECR_REGISTRY }}
          docker push ${{ secrets.ECR_REGISTRY }}/api:${{ github.sha }}

  deploy-production:
    needs: build-and-test
    runs-on: ubuntu-latest
    environment: production
    steps:
      - name: Update ECS service
        run: |
          aws ecs update-service \
            --cluster saas-production \
            --service api \
            --force-new-deployment \
            --task-definition saas-api:${{ github.sha }}

Two decisions here matter more than they look. Tests run before the image is even built, so a broken build never gets tagged with a commit SHA and never becomes a deploy candidate. And the image is tagged with the git SHA rather than latest, which is what makes rollback a one-line command instead of an archaeology project: you always know exactly which commit is running, and reverting just means pointing the service at a previous SHA.

The environment: production block does real work too. GitHub Environments let you require a manual approval before that job runs, a cheap, low-ceremony gate that catches the "I meant to push to a feature branch" class of mistake before it reaches real users.

Zero-downtime deploys and health checks

A deploy that drops requests, even for a few seconds, is a deploy your users notice. Avoiding that has little to do with clever infrastructure. It comes down to the platform knowing when a new instance is actually ready before it stops sending traffic to the old one.

That starts with an honest health check endpoint, not just a 200 OK that ignores whether the app can actually do its job:

// apps/api/src/health/health.controller.ts
import { Controller, Get } from '@nestjs/common';
import {
  HealthCheckService,
  HealthCheck,
  TypeOrmHealthIndicator,
} from '@nestjs/terminus';
import { RedisHealthIndicator } from './redis-health.indicator';

@Controller('health')
export class HealthController {
  constructor(
    private readonly health: HealthCheckService,
    private readonly db: TypeOrmHealthIndicator,
    private readonly redis: RedisHealthIndicator,
  ) {}

  @Get()
  @HealthCheck()
  check() {
    return this.health.check([
      () => this.db.pingCheck('database'),
      () => this.redis.isHealthy('redis'),
    ]);
  }
}

This endpoint checks the dependencies the API actually needs to serve a request, not just whether the Node process is alive. A process can run perfectly fine while its database connection pool is exhausted, and a health check that only pings the process itself will happily route traffic to an instance that can't serve it.

Point your platform's readiness probe at this endpoint and give it a real grace period before marking an instance unhealthy. On ECS, that's the target group's health check on the load balancer; behind Nginx in Compose it's a manual healthcheck, though Compose alone doesn't give you the traffic draining a real load balancer does. The platform should wait for a new instance's health check to pass, then drain in-flight connections from the old instance rather than killing it outright. That draining step is the actual mechanism behind "zero-downtime," not anything magical about the deploy command itself.

Database migrations as part of the deploy

Migrations are where deploys go wrong in ways that are hard to notice until they've caused an incident. The core rule: a migration has to be safe while the previous version of the code is still serving traffic, because during a rolling deploy, old and new code run side by side for some window of time, however short.

That rules out dropping a column the old code still reads, or renaming something the old code references by its previous name, in the same deploy that ships the code change. The safe pattern splits it into stages: add the new column, deploy code that writes to both old and new, backfill, deploy code that reads only the new column, then drop the old one in a later migration once nothing depends on it.

-- Stage 1: additive, safe with old code still running
ALTER TABLE organizations ADD COLUMN billing_email VARCHAR(255);

-- Stage 2, a later migration, once new code is the only code running:
-- ALTER TABLE organizations DROP COLUMN legacy_billing_contact;

Run migrations as an explicit release step, not something the app does on boot. Letting every instance run migrations on startup means N instances racing to apply the same migration during a rolling deploy, an intermittent failure that's miserable to debug because it only shows up under real deploy timing.

# One-off migration step before the ECS service update in deploy.yml
- name: Run migrations
  run: |
    aws ecs run-task \
      --cluster saas-production \
      --task-definition saas-migrate:${{ github.sha }} \
      --launch-type FARGATE \
      --network-configuration "..." \
      --overrides '{"containerOverrides":[{"name":"migrate","command":["npm","run","migration:run"]}]}'

Running it as a separate task before the service update means the schema is ready before any new code that depends on it receives traffic. It also happens exactly once, regardless of how many instances the service scales to.

Rollback and production pitfalls

Because every image is tagged with a git SHA, rolling back is the same command as rolling forward, pointed at a previous tag:

aws ecs update-service \
  --cluster saas-production \
  --service api \
  --force-new-deployment \
  --task-definition saas-api:a1b2c3d

Keep that command, or its equivalent, somewhere every engineer can find it without digging, ideally in a runbook rather than someone's shell history. The value of a fast rollback comes entirely from how quickly someone can find and run it under pressure.

A few pitfalls show up repeatedly once a team deploys for real. Coupling migrations and code into one inseparable step is the big one, already covered above. Skipping a genuine health check in favor of a bare liveness probe is another: it hides exactly the failures, a dead connection pool, an unreachable Redis, that a deploy is most likely to introduce. Not tagging images with something traceable to a commit turns rollback into guesswork. And treating staging as optional because "it's basically the same as prod" removes the one environment where a broken migration gets caught before it reaches customers.

It comes down to deciding, deliberately, what "safe to deploy" means for your app, then encoding that decision into the pipeline so it doesn't depend on someone remembering it under pressure. No exotic tooling required.

Key takeaways

Match deployment complexity to your actual team and traffic: a single VM with Docker Compose is a legitimate production target, ECS/Cloud Run/a PaaS is the right next step for most teams, and Kubernetes should wait for a concrete multi-service, multi-team problem.
Build one artifact per commit, tag it with the git SHA, and promote that same artifact through environments instead of rebuilding per environment.
A real health check verifies dependencies (database, Redis), not just that the process is alive; the platform should wait for it before draining the previous instance's traffic.
Run database migrations as an explicit, single release step before the code deploy, and design schema changes to be safe while old and new code run side by side.
Rollback should be the same mechanism as deploy, pointed at a previous SHA; keep that command in a runbook, not in someone's memory.
Deploying isn't about clever tooling. It's about deciding what "safe" means for your app and encoding that decision into the pipeline.

FAQ

Do I need Kubernetes to deploy a production SaaS?
No. Kubernetes solves orchestration problems that show up with many services and teams. A single VM with Docker Compose, or a managed platform like ECS Fargate or Cloud Run, is a legitimate production target until a concrete multi-service problem justifies the cost.

How do I achieve zero-downtime deploys?
The platform waits for a new instance's health check to pass before routing traffic to it, then drains in-flight connections from the old instance before terminating it. That depends on a health check verifying real dependencies and a load balancer that supports draining, not on any single deploy command.

Should database migrations run automatically when the app starts?
No. Running migrations on boot means every instance in a rolling deploy races to apply the same one. Run migrations as a single, explicit step before the code deploy, ideally as a one-off task rather than baked into startup.

What's the fastest way to roll back a bad deploy?
Tag every built image with its git SHA and keep a runbook command that redeploys a previous tag. Because the artifact for any past commit already exists, rollback is the same operation as a forward deploy, just pointed at an older tag.

Is it safe to rename or drop a database column in the same deploy as the code change?
Not if the deploy is rolling, since old and new code briefly run side by side. Split the change: add the new column, deploy code that writes both, backfill, deploy code that reads only the new column, then drop the old one once nothing references it.

When should I move from a single VM to a managed platform like ECS or Cloud Run?
When keeping the VM healthy and scaled starts costing real engineering time, or when you need more than one instance and want the platform to handle health checks and traffic shifting for you. It's a reasonable second step for most teams, well before Kubernetes is worth it.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

Scaling a SaaS Beyond One Server

Aman Kumar Singh — Fri, 24 Jul 2026 07:06:09 +0000

In Deploying a Full Stack SaaS, I got the app running in production on a single instance: Docker images, a CI/CD pipeline, one NestJS container and one Postgres database behind it. That setup will carry a real SaaS further than most people expect. It also has a hard ceiling. The day you hit it, "just add another server" turns out to be a much bigger sentence than it sounds.

This is Module 4 of the Full Stack SaaS Masterclass, and this article is about what actually changes when you go from one instance to several. It's less about picking an autoscaling number and more about the assumptions your app quietly made when it only ever ran on one box.

What follows is the application-level changes that have to happen before more servers help you at all, rather than a walkthrough of configuring Kubernetes. Get those wrong and adding capacity just spreads the same bugs across more machines.

Why one server works until it very suddenly doesn't

A single instance is simple because everything lives in one place: in-memory session storage, an in-process rate limiter, a WebSocket connection map, a scheduled job that runs "once" because there's only one process to run it. None of that is wrong on day one. It's the correct amount of complexity for the traffic you have.

The problem is that these shortcuts are invisible until you add a second instance. Then a user logs in, the load balancer routes their next request to a different container, and their session doesn't exist there. A cron job that ran "once" now runs twice, because both instances think they're the only one. A rate limiter that tracked requests per process now lets through double the traffic, because each instance has its own counter.

None of this shows up in code review. It shows up in production, as a support ticket that says "I got logged out for no reason" or "I got charged twice." So before scaling out, the real task is finding every place your app assumed there was exactly one of it.

Make the process stateless before you make it plural

The single most important property for horizontal scaling is that any instance can handle any request, with no memory of what happened before. If that's true, a load balancer can route however it wants and you can add or remove instances without anyone noticing.

Sessions are the classic offender. If you're using JWTs for auth (as covered earlier in this series), you're already stateless on that front, since the token carries everything the server needs to verify the user. If you're using server-side sessions, they need to live in Redis, not in process memory, so every instance reads the same session store.

Health checks matter just as much here, because a load balancer that can't tell a broken instance from a healthy one will happily send traffic to a dying container.

// health.controller.ts
import { Controller, Get } from '@nestjs/common';
import {
  HealthCheck,
  HealthCheckService,
  TypeOrmHealthIndicator,
  MemoryHealthIndicator,
} from '@nestjs/terminus';

@Controller('health')
export class HealthController {
  constructor(
    private health: HealthCheckService,
    private db: TypeOrmHealthIndicator,
    private memory: MemoryHealthIndicator,
  ) {}

  @Get('live')
  live() {
    // Liveness: is the process even running? No dependency checks.
    return { status: 'ok' };
  }

  @Get('ready')
  @HealthCheck()
  ready() {
    // Readiness: can this instance actually serve traffic right now?
    return this.health.check([
      () => this.db.pingCheck('database', { timeout: 1500 }),
      () => this.memory.checkHeap('memory_heap', 500 * 1024 * 1024),
    ]);
  }
}

The distinction matters once you're behind a load balancer or an orchestrator. Liveness answers "should this container be restarted?" Readiness answers "should traffic be sent here right now?" A container can be alive but not ready, for instance while it's warming up a database connection pool during startup, or draining connections during a graceful shutdown.

Graceful shutdown is the other half of this. When an instance is about to be terminated (during a deploy, a scale-down, or a spot instance reclaim), it needs to stop accepting new work, finish in-flight requests, and close its database and Redis connections cleanly.

// main.ts
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableShutdownHooks();

  const server = await app.listen(process.env.PORT ?? 3000);

  process.on('SIGTERM', async () => {
    server.close(); // stop accepting new connections
    await app.close(); // run onModuleDestroy hooks: DB, Redis, queues
    process.exit(0);
  });

  return app;
}

Skip this and every deploy or scale-down event drops requests mid-flight. It's a common source of intermittent 502s that never show up in local testing, because locally you never kill the process while it's handling a request.

The database becomes the real bottleneck

Once the app tier is stateless and horizontally scaled, the next constraint shows up almost immediately: Postgres. Every app instance opens its own connection pool, and Postgres connections are not cheap; each one holds a backend process and a meaningful chunk of memory. Five instances with a pool of 20 each is 100 connections before you've served a single extra user, well past what Postgres defaults expect from a busy fleet.

This is where connection pooling at the infrastructure level earns its keep. PgBouncer sits between your app instances and Postgres, multiplexing many app-level connections onto a much smaller number of real database connections.

# pgbouncer.ini (relevant section)
[databases]
saas_prod = host=postgres-primary port=5432 dbname=saas_prod

[pgbouncer]
pool_mode = transaction
max_client_conn = 1000
default_pool_size = 25

transaction pooling mode is the one that actually helps at scale: a client (your app) borrows a real connection only for the duration of a transaction, then gives it back. It does mean you lose session-level features like advisory locks held across statements or SET commands that are meant to persist, so it's worth auditing anything relying on session state before flipping this on.

The other lever is read replicas. Reporting queries, dashboards, and analytics reads don't need to hit the primary, and separating them protects write throughput for the paths that actually matter, like checkout or signup.

// database.module.ts
export const databaseProviders = [
  {
    provide: 'PRIMARY_CONNECTION',
    useFactory: () =>
      new DataSource({
        type: 'postgres',
        host: process.env.DB_PRIMARY_HOST,
        // writes and anything read-after-write sensitive
      }).initialize(),
  },
  {
    provide: 'REPLICA_CONNECTION',
    useFactory: () =>
      new DataSource({
        type: 'postgres',
        host: process.env.DB_REPLICA_HOST,
        // dashboards, analytics, exports
      }).initialize(),
  },
];

The honest tradeoff is replication lag. A user who just updated their profile and immediately reloads the page can hit a replica that hasn't caught up yet and see stale data. The usual fix is routing anything read-after-write (the response to a mutation, or a page loaded right after a form submit) to the primary, and reserving replicas for reads that can tolerate a little staleness. Most reporting and list views fall into that category comfortably.

Move shared state into Redis, deliberately

Once you have more than one instance, anything that needs to be shared across the fleet has to live somewhere all instances can see it. Redis is the natural home for this because it's fast enough to sit in the request path and simple enough to reason about.

Rate limiting is the clearest example. An in-memory rate limiter on each instance only limits requests to that instance, so a user hitting five instances effectively gets five times the limit.

// redis-rate-limiter.ts
import { Injectable } from '@nestjs/common';
import Redis from 'ioredis';

@Injectable()
export class RedisRateLimiter {
  constructor(private readonly redis: Redis) {}

  async isAllowed(key: string, limit: number, windowSeconds: number): Promise<boolean> {
    const count = await this.redis.incr(key);
    if (count === 1) {
      await this.redis.expire(key, windowSeconds);
    }
    return count <= limit;
  }
}

The same pattern applies to WebSockets. If your app supports live features (notifications, presence, collaborative editing), a socket connected to instance A can't broadcast directly to a client connected to instance B. Socket.IO's Redis adapter solves this by publishing events through Redis pub/sub, so any instance can reach any connected client regardless of which instance it's on.

// socket-adapter.ts
import { IoAdapter } from '@nestjs/platform-socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { createClient } from 'redis';

export class RedisIoAdapter extends IoAdapter {
  private adapterConstructor: ReturnType<typeof createAdapter>;

  async connectToRedis(): Promise<void> {
    const pubClient = createClient({ url: process.env.REDIS_URL });
    const subClient = pubClient.duplicate();
    await Promise.all([pubClient.connect(), subClient.connect()]);
    this.adapterConstructor = createAdapter(pubClient, subClient);
  }

  createIOServer(port: number, options?: any) {
    const server = super.createIOServer(port, options);
    server.adapter(this.adapterConstructor);
    return server;
  }
}

The same reasoning extends to scheduled jobs and locks. A cron-style job that assumes "there's only one process" will fire once per instance once you scale out. Distributed locks (Redis's SET NX with an expiry, or a library that wraps that pattern) keep only one instance actually executing the job while the others no-op.

Scaling the fleet without scaling the chaos

With the app stateless and shared state centralized, horizontal scaling becomes mostly an infrastructure decision. On AWS, that usually means an Application Load Balancer in front of an ECS or Fargate service, with a target-tracking scaling policy based on CPU or request count per target.

The tradeoff worth naming: autoscaling adds capacity reactively, after a metric crosses a threshold, and new containers take time to start and pass their readiness check. If traffic spikes faster than a new instance can come online, you'll see elevated latency during the gap. Capacity planning still matters here: autoscaling only handles the variance around a baseline you've already sized reasonably.

A few pitfalls show up reliably here. Deploys that don't drain connections drop requests exactly when you're proving the new version works. Health checks that only check "is the process up" rather than "can it reach the database" let broken instances stay in rotation. And a thundering herd on cache expiry, where many instances simultaneously miss a Redis key and hammer Postgres at once, can turn a scaling event into an outage. Staggered TTLs or a simple lock around cache repopulation avoids that specific failure mode.

Key takeaways

Horizontal scaling only helps once the application is stateless: no in-memory sessions, no per-process rate limits, no assumptions about being the only running instance.
Health checks need to distinguish liveness (is the process alive) from readiness (can it serve traffic), and graceful shutdown must drain in-flight requests before a container exits.
The database, not the app tier, is usually the first real bottleneck. PgBouncer and read replicas buy headroom, but replication lag means read-after-write traffic still needs the primary.
Redis becomes the shared brain for the fleet: rate limiting, distributed locks, and WebSocket fan-out via the Redis adapter all rely on it.
Autoscaling reacts to load after the fact; it complements capacity planning, it doesn't replace it.
Most scaling incidents come from state assumptions baked in during the single-server phase, not from the load balancer or the orchestrator itself.

FAQ

When should a SaaS move from one server to multiple instances?
When you have concrete evidence of a ceiling: CPU or memory consistently near limits during normal traffic, response times degrading under real load, or a single point of failure that's become an actual operational risk. Scaling out before that just adds coordination overhead for no benefit.

Do sticky sessions solve the statelessness problem?
They mask it rather than solve it. Sticky sessions route a user's requests back to the same instance, avoiding in-memory session bugs, but losing that instance logs out everyone attached to it, and they defeat even load distribution. Fixing statelessness at the source (Redis-backed sessions or JWTs) is more durable.

How many app instances does a typical SaaS need?
There's no universal number; it depends on request volume, average response time, and how much headroom you want for traffic spikes and deploys. What matters more than the count is that each instance is interchangeable, so you can adjust the number without touching application logic.

Does PgBouncer replace connection pooling in the ORM?
No, they solve different layers. The ORM's pool manages connections from a single app process; PgBouncer manages connections across all your app processes to the database itself. You typically want both, with the ORM's pool sized modestly since PgBouncer is doing the heavy multiplexing.

What breaks first when a stateful app is scaled out without fixing that?
Usually sessions and rate limiting, since both silently assume a single process. Scheduled jobs running multiple times is the next common one, followed by WebSocket features that only reach some connected clients depending on which instance they land on.

Is Kubernetes required to scale a SaaS beyond one server?
No. ECS or Fargate behind an Application Load Balancer gets you horizontal scaling with far less operational overhead, and it's a reasonable place to stay for a long time. Kubernetes earns its complexity once you have many services, teams, or workloads that genuinely need its scheduling and orchestration flexibility.

About the Author

Hi, I'm Aman Singh — Senior Full Stack Engineer specializing in scalable SaaS products, distributed systems, cloud architecture, and AI-powered applications.

I write about System Design, Full Stack Engineering, Distributed Systems, Redis, PostgreSQL, AWS, Node.js, and NestJS.

Portfolio: https://amanksingh.com
GitHub: https://github.com/amansingh1501
Product: https://vowerole.com
Email: aman97aman@gmail.com

DEV Community: Aman Kumar Singh

Node.js Error Handling: Operational vs Programmer Errors

Errors propagate differently depending on the pattern

The process-level safety nets

The distinction that drives everything: operational vs programmer errors

Practical guidelines

Node.js Memory Leaks and Profiling: Finding What Holds Memory

How memory works in Node

The common leak sources

Detecting that you have a leak

Profiling with heap snapshots

Preventing leaks in the first place

Scaling Node.js with the Cluster Module: Using All Your Cores

Why one process is not enough

Processes, not threads

The catch: workers share no state

Clustering versus running multiple containers

Where clustering fits in scaling

Node.js Worker Threads: Moving CPU Work Off the Main Thread

The problem: CPU work blocks everything

What worker threads are

Communication and its cost

Use a pool, not a worker per task

When NOT to use worker threads

Workers versus clustering versus a separate service

Node.js Streams and Backpressure: Processing Data Without Running Out of Memory

Why streams instead of buffering everything

The four stream types

Piping connects streams safely

Backpressure: the concept that makes streams safe

Use pipeline for error handling

When to reach for streams

Node.js Async Patterns: Callbacks, Promises, and async/await

Callbacks and the pyramid problem

Promises make async composable

async/await is Promises that read like sync code

EventEmitter for streams of events

Which to use

The Node.js Event Loop Explained: How Single-Threaded Serves Thousands

Single-threaded, but not single-tasking

What the event loop actually is

Microtasks jump the queue

Blocking the loop is the cardinal sin

The model to carry forward

Structured Logging for Node.js

Why plain text logs stop working

Picking a logging library and wiring it into NestJS

Threading a correlation ID through every log line

Tradeoffs: what structured logging costs you

Production pitfalls worth planning for

Key takeaways

FAQ

Further reading

About the Author

Audit Logs You Can Trust

Why audit logs are a different beast than application logs

What actually belongs in an audit entry

Writing audit entries without polluting business logic

Making the log tamper-evident, not just tamper-resistant

Retention, access, and the customer-facing activity feed

Production pitfalls worth naming directly

Key takeaways

FAQ

Further reading

About the Author

Feature Flags and Safe Rollouts

Why feature flags earn their place

Flag types, and picking the right one

Building a flag service: Postgres and Redis

Rollout strategy and rolling back

Tradeoffs and where teams get burned

Key takeaways

FAQ

Further reading

About the Author

Deploying a Full Stack SaaS

Picking a deployment target without overbuilding

The build and release pipeline

Zero-downtime deploys and health checks

Database migrations as part of the deploy