Callbacks

The callback pattern

A callback is a function you pass to another function, to be called later when an operation completes. This was JavaScript’s original approach to async work — pass a function, and the runtime will call it when the result is ready.

setTimeout(function() {
  console.log('This runs after 1 second');
}, 1000);

The second argument to setTimeout is a callback. You hand control to the runtime and your function is called back when the timer fires.

The error-first convention

Node’s built-in APIs use a consistent signature for callbacks:

const fs = require('node:fs');

fs.writeFileSync('data.txt', 'hello from data.txt');

fs.readFile('data.txt', 'utf8', function(err, data) {
  if (err) {
    console.error('Read failed:', err.message);
    return;
  }
  console.log('File contents:', data);
});

The node: prefix marks a built-in module explicitly — it works everywhere require('fs') does, and is required (not just preferred) for a few newer built-ins like node:test and node:sqlite.

The pattern is (err, data) — error always first, result second. If the operation succeeded, err is null. If it failed, err is an Error object and data is undefined.

Always check err before using data. If you ignore a non-null err and try to use data, you will get confusing errors.

Callback nesting

When one async operation depends on the result of another, you nest callbacks:

function step1(callback) {
  setTimeout(function() { callback(null, 'A'); }, 0);
}
function step2(input, callback) {
  setTimeout(function() { callback(null, 'B'); }, 0);
}
function step3(input, callback) {
  setTimeout(function() { callback(null, 'C'); }, 0);
}
function handleError(err) {
  console.error('Error:', err.message);
}

step1(function(err, resultA) {
  if (err) return handleError(err);
  step2(resultA, function(err, resultB) {
    if (err) return handleError(err);
    step3(resultB, function(err, resultC) {
      if (err) return handleError(err);
      console.log('Final:', resultC);
    });
  });
});

This deep nesting — sometimes called callback hell or the pyramid of doom — is hard to read and error-prone. Promises and async/await (covered in the next lessons) solve this.

Runnable demo

The snippet below simulates two async steps using setTimeout. Each step uses the error-first callback pattern. Run it to see the output order.

JavaScriptRun ▸Open in StackBlitz ▸

// @browser function step1(callback) { setTimeout(function() { callback(null, 'result-A'); }, 0); } function step2(input, callback) { setTimeout(function() { callback(null, 'result-B'); }, 0); } step1(function(err, dataA) { if (err) { console.log('Error in step 1:', err); return; } console.log('Step 1 done: ' + dataA); step2(dataA, function(err, dataB) { if (err) { console.log('Error in step 2:', err); return; } console.log('Step 2 done: ' + dataB); }); });

The output is always Step 1 done: result-A then Step 2 done: result-B — each step fires only after the previous one completes.

🟢 Error-first is the Node convention

Node’s built-in APIs pass errors as the first callback argument. Always check err before using data — if err is truthy, handle it and return early.

Waiting for an event without nesting: events.once and events.on

EventEmitter predates Promises, but node:events now ships two helpers that turn event callbacks into modern async code without changing how EventEmitter itself works. once(emitter, name) returns a Promise that resolves with the event’s arguments the first time it fires — useful for a one-shot “wait for this” instead of registering and later removing a listener by hand. on(emitter, name) returns an async iterator, so a stream of repeated events can be consumed with for await instead of a callback that fires forever:

Node.jsOpen in StackBlitz ▸

import { EventEmitter, once, on } from 'node:events'; const emitter = new EventEmitter(); setTimeout(function () { emitter.emit('ready', 'payload-A'); }, 0); const [value] = await once(emitter, 'ready'); console.log('once() resolved with:', value); async function consumeTicks() { for await (const [n] of on(emitter, 'tick')) { console.log('on() saw tick', n); if (n === 2) break; } } const ticks = consumeTicks(); let i = 0; const iv = setInterval(function () { i++; emitter.emit('tick', i); if (i >= 2) clearInterval(iv); }, 0); await ticks; console.log('done');

Output (verified on Node 24)

once() resolved with: payload-A
on() saw tick 1
on() saw tick 2
done

Both helpers still use the same EventEmitter underneath — once/on just wrap the callback registration in a Promise or async iterator so the rest of your code can await it instead of nesting a handler.

Mental Model

An error-first callback is a contract, not a suggestion: the function you receive is called exactly once, with err in the first slot. Everything downstream — retries, logging, the next step in a pipeline — depends on every caller honoring that contract every single time, including the times it is inconvenient (an early return after handling err, not falling through to use data anyway). events.once/events.on do not replace this contract; they sit on top of it, converting “register a callback, remember to remove it” into “await a Promise” or “iterate a stream” for the common case of waiting on one or more EventEmitter events.

Trade-offs

Callbacks have no built-in composition — chaining three callback-based steps means three levels of nesting, three separate error-handling branches, and one easy-to-miss return away from a callback firing twice. That is precisely the pyramid of doom Promises and async/await were designed to flatten (next two lessons). Callbacks remain the right tool for anything that can fire more than once over time — a data event on a stream, a repeated timer tick — where a Promise’s “settle once” model does not fit; events.on’s async iterator is the modern way to consume that repeated-firing shape without writing the listener/cleanup dance by hand.

Common Misconceptions

• “Forgetting to return after handling err is a style nitpick.” It is a correctness bug: without the return, execution falls through and uses data — which is undefined on the error path — often throwing a confusing, unrelated TypeError far from the real cause.
• “events.once and the .once() listener method are the same thing.” They are related but different: emitter.once(name, fn) registers a listener that auto-removes after firing once (still callback-style); once(emitter, name) (imported from node:events) returns a Promise for that same one-shot wait.
• “A callback-based API is inherently slower or worse than a Promise-based one.” Performance is not the difference — ergonomics are. Both ultimately hand control back to the event loop; callbacks just require you to manage nesting, error propagation, and cleanup by hand.

Reading AI-generated code

AI-generated code that “modernizes” a callback API often wraps an already-Promise-returning function in new Promise(...) anyway — a leftover reflex from converting callback APIs, applied to something that was never callback-based to begin with.

🐛 Spot the bug

function loadConfig() {
return new Promise(function (resolve, reject) {
  fetchConfigFromApi().then(resolve, reject); // fetchConfigFromApi() already returns a Promise
});
}

Show the answer

fetchConfigFromApi() already returns a Promise, so wrapping it in new Promise(...) adds a pointless extra layer — this is the “Promise constructor anti-pattern” (sometimes called the “deferred anti-pattern”). It is not just redundant: if the executor forgets to attach reject (a single .then(resolve) with no error argument, easy to type by accident), a rejection from fetchConfigFromApi() is silently swallowed instead of propagating. The fix is to skip the wrapper entirely — return fetchConfigFromApi(); — since a function that already returns a Promise needs no new Promise around it.

🟢 The one-line takeaway

Error-first callbacks are a contract you must honor on every call path, including a return right after handling err; when you find yourself wrapping something that already returns a Promise in new Promise(...), delete the wrapper and return the Promise directly.

What is the correct signature for a Node.js error-first callback?

function(data, err) function(err, data) function(result) function(status, data, err)

In the error-first callback pattern, what value does err hold on success?

undefined false null 0

What is "callback hell"?

Callbacks that throw exceptions instead of passing errors Deeply nested callbacks that form a rightward-growing pyramid of indentation Using callbacks inside Promises Calling the same callback more than once

What does this print? If the file does not exist, what happens?

function readConfig(cb) {
  fs.readFile('config.json', 'utf8', function (err, data) {
    if (err) console.error(err); // missing return
    cb(null, JSON.parse(data));
  });
}

cb is called once with the error only The error is logged, then cb still runs JSON.parse(undefined) and throws a TypeError Node automatically skips the rest of the callback after console.error cb is called twice — once with the error, once with the parsed data

Why is wrapping an already-Promise-returning function in new Promise((resolve, reject) => fn().then(resolve, reject)) considered an anti-pattern?

It is slower than calling fn() directly It is redundant, and if reject is ever left off the .then(), a rejection is silently swallowed instead of propagating new Promise() cannot be used inside another function It is not an anti-pattern — it is the recommended way to convert callbacks to Promises

Submit

Mark as complete