Async patterns and error handling

Callbacks: the error-first contract and its ceiling

Node’s original async style is the callback: you pass a function that runs when the work finishes. The convention is error-first — the callback’s first argument is an error (or null), the rest is the result. You check the error before touching the data, every time.

fs.readFile("config.json", "utf8", (err, data) => {
  if (err) return console.error("read failed:", err);
  const config = JSON.parse(data); // only safe once err is null
  console.log(config.port);
});

This works, but it does not compose. Sequence three dependent operations and you get the nesting that earned its own name — callback hell — where each step lives one indent deeper and error handling is copy-pasted into every level. Worse is the structural problem: inversion of control. You hand your continuation to someone else’s function and trust it to call you back exactly once, with the right arguments, on the right tick. A buggy library that calls the callback twice, or never, or synchronously when you expected async, corrupts your flow and there is nothing in the type system to stop it. Promises exist largely to take that control back.

Promises: a value you own, with combinators

Why did callbacks fail so badly that the language added an entirely new model? Because owning the result — instead of handing your continuation to someone else — is what makes composition possible.

A promise is an object representing a future value. It has three states — pending, then exactly one of fulfilled (resolved with a value) or rejected (failed with a reason) — and once settled it never changes. Because the promise is a first-class value you hold, you compose it instead of handing off control: .then chains transformations, .catch handles failures, and a rejection skips every .then until it hits a .catch. That single rejection path is the cure for copy-pasted error handling.

The real power is the combinators for running multiple promises together. Picking the wrong one is a common middle-level mistake:

Together these four cover every fan-out shape: all for all-or-nothing, allSettled for partial success, race for “whoever is fastest”, any for “first winner”. Without the right combinator, you either lose results you already have or hide failures you need to see.

The classic trap is using Promise.all for tasks where partial success should be tolerated — one rejection then discards the results of everything else that already succeeded. If you want every result regardless of individual failures, allSettled is the correct tool; all is for when any failure genuinely invalidates the whole batch.

async/await: the same promises, read top to bottom

async/await is syntactic sugar over promises, not a separate mechanism. An async function always returns a promise — even async () => 42 returns a promise that fulfills with 42 — and await simply pauses the function until a promise settles, unwrapping its value or throwing its rejection. Because rejections become thrown errors, you handle them with ordinary try/catch, which reads far better than chained .catch.

async function loadDashboard(userId) {
  try {
    // independent — run in parallel, not in sequence
    const [user, orders] = await Promise.all([
      fetchUser(userId),
      fetchOrders(userId),
    ]);
    return { user, orders };
  } catch (err) {
    // one catch covers both rejections
    throw new Error(`dashboard load failed for ${userId}`, { cause: err });
  }
}

The single most common performance bug here is sequential await in a loop when the iterations are independent. for (const id of ids) { await fetchOne(id); } runs the requests one after another; the total time is the sum of every latency. If the calls do not depend on each other, fire them together with Promise.all(ids.map(fetchOne)) and the total time collapses to roughly the slowest single call. Sequential await is correct only when each step genuinely needs the previous step’s result.

Error handling: never swallow, decide propagate vs handle

An async error you ignore does not go away — it becomes an unhandledRejection. In modern Node a promise that rejects with no .catch (and no surrounding try/catch on its await) emits the unhandledRejection process event and, by default, crashes the process. That default is deliberate: a half-finished request in an unknown state is more dangerous than a restart.

The rule is to never swallow errors — an empty catch {} that logs nothing is how outages become unexplainable. For each failure you make one decision: handle it (you can recover — retry, fall back to a default, return a 503) or propagate it (you cannot, so re-throw and let a caller who has more context decide). A catch block that neither recovers nor re-throws is almost always a bug.

Cancellation is the other half. A request the user abandoned, or a fetch that has run too long, should be stopped — and the modern, standard tool is AbortController. You pass its signal into an async API; calling controller.abort() rejects the operation with an AbortError. Wiring it to a timer gives you a clean timeout without leaking the in-flight work:

async function fetchWithTimeout(url, ms) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), ms);
  try {
    return await fetch(url, { signal: controller.signal });
  } finally {
    clearTimeout(timer); // always clean up the timer
  }
}

Event-loop ordering: microtasks drain before the next macrotask

The senior question is when your callbacks actually run. The event loop processes macrotasks (timers like setTimeout, and I/O callbacks) one at a time — but after each macrotask, before moving to the next one, it fully drains the microtask queue: resolved promise callbacks, queueMicrotask, and Node’s process.nextTick. Microtasks always run before the next macrotask, and within microtasks Node runs the nextTick queue ahead of the promise queue.

That ordering explains output that surprises people:

console.log("1: sync");
setTimeout(() => console.log("2: timeout (macrotask)"), 0);
Promise.resolve().then(() => console.log("3: promise (microtask)"));
queueMicrotask(() => console.log("4: queueMicrotask (microtask)"));
process.nextTick(() => console.log("5: nextTick (microtask, first)"));
console.log("6: sync");
// 1: sync → 6: sync → 5: nextTick → 3: promise → 4: queueMicrotask → 2: timeout

Both synchronous lines run first. Then the current operation finishes and the microtask queue drains — nextTick ahead of the promise/queueMicrotask jobs — and only after the queue is empty does the setTimeout macrotask fire, even though its delay was 0. The practical payoff: a process.nextTick callback can starve I/O if it keeps scheduling more nextTick work, and a promise chain never yields to a timer mid-drain. Knowing the order is how you reason about why a “0ms” timeout still runs last.