DEV Community

Cover image for Callbacks and promises: from the nested pyramid to the value that arrives later
Javi Palacios
Javi Palacios

Posted on Originally published at fjp.es

Callbacks and promises: from the nested pyramid to the value that arrives later

There's a mistake everyone has made once, and it sums up a decade of style: read a file with a callback, forget to check the error, and crash while asking undefined for its length.

readFile("./missing.json", "utf8", (error, data) => {
  console.log(data.length);
});
Enter fullscreen mode Exit fullscreen mode
TypeError: Cannot read properties of undefined (reading 'length')
Enter fullscreen mode Exit fullscreen mode

The real error — the file doesn't exist — gets lost, and the message you see is about something else. That small, irritating detail is why promises exist. They didn't arrive to make code prettier: they arrived so the error can't be ignored by accident.

The callback: a function that runs later

A callback is a function you pass as an argument so something else can call it when it has news. In Node it takes a very specific shape: error first.

import { readFile } from "node:fs";

readFile("./package.json", "utf8", (error, data) => {
  if (error) {
    console.log("error:", error.code);
    return;
  }
  console.log("read", data.length, "characters");
});
Enter fullscreen mode Exit fullscreen mode
read 48 characters
Enter fullscreen mode Exit fullscreen mode

That (error, data) isn't a whim: it's the convention Node chose so the first argument always exists and always means the same thing, whether or not there's a result. And when there is an error:

readFile("./missing.json", "utf8", (error, data) => {
  if (error) {
    console.log("error:", error.code, "·", error.message.split(",")[0]);
    return;
  }
  console.log(data.length);
});
Enter fullscreen mode Exit fullscreen mode
error: ENOENT · ENOENT: no such file or directory
Enter fullscreen mode Exit fullscreen mode

It works. And for years it was the only way. The trouble starts when you chain steps, because every step needs its callback, and every callback lives inside the previous one.

The pyramid

Three operations that depend on each other: read the config, fetch the data, write the result. With callbacks, the shape is this (each step is a function that takes a callback and takes a while to answer; the detail doesn't matter, the shape does):

step1((err1, one) => {
  if (err1) return console.log(err1);
  step2(one, (err2, two) => {
    if (err2) return console.log(err2);
    step3(two, (err3, three) => {
      if (err3) return console.log(err3);
      console.log("result:", three);
    });
  });
});
Enter fullscreen mode Exit fullscreen mode
step 1
step 2 with one
step 3 with two
result: three
Enter fullscreen mode Exit fullscreen mode

It works, and the problem is already visible. Every level adds an error check, a new parameter and one more indent. With ten steps you have a histogram. With serious error handling — cleanup, retries, alerts — you have a pyramid with more steps than a cathedral tower and worse views.

And there's a bigger problem than the shape: there's no return value. A function with a callback doesn't return the result, it hands it over. Which means you can't store it in a variable, return it, or compose it. You can only keep nesting.

The promise: a container for a future value

A promise is an object representing a value you don't have yet. Not the value: the promise that it will arrive.

It has three states: pending, fulfilled or rejected. And it moves once, in one direction. Printing one shows it nicely:

const p = new Promise((resolve) => setTimeout(() => resolve("done"), 50));
console.log(p);
setTimeout(() => console.log(p), 100);
Enter fullscreen mode Exit fullscreen mode
Promise { <pending> }
Promise { 'done' }
Enter fullscreen mode Exit fullscreen mode

The first console.log runs while it's pending; the second, once it's fulfilled and holds the value 'done'. That object is what you can pass from one function to another.

then, catch and finally

Promise.resolve(2)
  .then((n) => {
    console.log("step 1:", n);
    return n * 3;
  })
  .then((n) => {
    console.log("step 2:", n);
    throw new Error("deliberate failure");
  })
  .catch((error) => console.log("catch:", error.message))
  .finally(() => console.log("finally"));
Enter fullscreen mode Exit fullscreen mode
step 1: 2
step 2: 6
catch: deliberate failure
finally
Enter fullscreen mode Exit fullscreen mode

Four things, in order: then receives the value and returns a new one that feeds the next then. An exception thrown inside a then doesn't blow up the process: it travels to the nearest catch. catch can return a value and the chain continues. And finally always runs, with a result or with an error, which is where cleanup belongs.

And if the then returns a promise, the chain unwraps it: you don't end up with promises inside promises, you end up with the value.

const wait = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));

Promise.resolve(2)
  .then((n) => wait(10, n * 3))
  .then((n) => console.log("the then unwraps the promise:", n));
Enter fullscreen mode Exit fullscreen mode
the then unwraps the promise: 6
Enter fullscreen mode Exit fullscreen mode

It's flat instead of nested, and the error travels on its own: no checking at every level. That's the difference that matters.

One small trap that costs a while: a then without return propagates undefined.

Promise.resolve(2)
  .then((n) => {
    n * 3;
  })
  .then((n) => console.log("the next one receives:", n));
Enter fullscreen mode Exit fullscreen mode
the next one receives: undefined
Enter fullscreen mode Exit fullscreen mode

No return, so the function returns undefined and the chain carries on with that. If a later step fails on an empty value, start looking here.

Promise.resolve and Promise.reject

They exist for two things you do constantly: wrapping a value you already have, and manufacturing a rejection, usually in tests.

const ready = Promise.resolve("ok");
const failed = Promise.reject(new Error("nope"));

ready.then((value) => console.log("fulfilled:", value));
failed.catch((error) => console.log("rejected:", error.message));
Enter fullscreen mode Exit fullscreen mode
fulfilled: ok
rejected: nope
Enter fullscreen mode Exit fullscreen mode

And a rule that saves code: if a function can return either a value or a promise, always return a promise. Whoever calls it shouldn't have to ask which one is coming.

Several at once: Promise.all

Here's the reason promises changed the throughput of half the backend world. Three independent operations, 300 ms each:

const wait = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));

const t0 = Date.now();
Promise.all([wait(300, "a"), wait(300, "b"), wait(300, "c")]).then((results) => {
  console.log("Promise.all:", Date.now() - t0, "ms", results);
});

const t1 = Date.now();
wait(300, "a")
  .then(() => wait(300, "b"))
  .then(() => wait(300, "c"))
  .then(() => console.log("sequential:", Date.now() - t1, "ms"));
Enter fullscreen mode Exit fullscreen mode
Promise.all: 300 ms [ 'a', 'b', 'c' ]
sequential: 907 ms
Enter fullscreen mode Exit fullscreen mode

Three times faster without optimising anything: all three start together because nobody waits for anybody. The sequential version waits 300, then 300, then 300. It's the difference between asking for three things and asking for one, waiting, asking for another.

And its condition, which you need to be clear about: all or nothing. If one rejects, the Promise.all promise rejects as a whole, even if the other two are finishing fine.

Promise.all([wait(10, "a"), Promise.reject(new Error("boom"))])
  .then((results) => console.log("this should not run:", results))
  .catch((error) => console.log("Promise.all rejects as a whole:", error.message));
Enter fullscreen mode Exit fullscreen mode
Promise.all rejects as a whole: boom
Enter fullscreen mode Exit fullscreen mode

One warning you learn in production: Promise.all has no brake. It fires everything at once. With five requests that's free; with ten thousand database rows it's an attack you're running on yourself. Concurrency limits are a topic for somewhere else, but the warning belongs here: if the array can be big, Promise.all is not a queue.

When you don't want all or nothing: Promise.allSettled

If you need the result of all three even when one fails — a dashboard that shows whatever it can — there's another function:

Promise.allSettled([wait(10, "a"), Promise.reject(new Error("boom")), wait(10, "c")]).then((settled) =>
  console.log(settled.map((r) => r.status)),
);
Enter fullscreen mode Exit fullscreen mode
[ 'fulfilled', 'rejected', 'fulfilled' ]
Enter fullscreen mode Exit fullscreen mode

And inside each one there's either value or reason depending on the case:

Promise.allSettled([wait(10, "a"), Promise.reject(new Error("boom"))]).then((settled) =>
  console.log(settled.map((r) => (r.status === "fulfilled" ? r.value : r.reason.message))),
);
Enter fullscreen mode Exit fullscreen mode
[ 'a', 'boom' ]
Enter fullscreen mode Exit fullscreen mode

It never rejects: it returns an array with each one's status, and inside either value or reason depending on the case. It's the difference between "I need all three" and "I need to know how each one went".

And the first one to answer: Promise.any

It's the mirror image of all: the first one to fulfil wins and the others are ignored.

const wait = (ms, value) => new Promise((resolve) => setTimeout(() => resolve(value), ms));
const fail = (ms, reason) => new Promise((_, reject) => setTimeout(() => reject(new Error(reason)), ms));

Promise.any([fail(10, "down"), wait(50, "replica 2"), fail(20, "down 2")]).then((value) =>
  console.log("the first one to answer:", value),
);
Enter fullscreen mode Exit fullscreen mode
the first one to answer: replica 2
Enter fullscreen mode Exit fullscreen mode

And if they all fail, the error isn't one of them: it's an AggregateError carrying the reasons inside.

Promise.any([fail(10, "down"), fail(20, "down 2")]).catch((error) => {
  console.log("all of them failed:", error.name);
  console.log(
    "reasons:",
    error.errors.map((e) => e.message),
  );
});
Enter fullscreen mode Exit fullscreen mode
all of them failed: AggregateError
reasons: [ 'down', 'down 2' ]
Enter fullscreen mode Exit fullscreen mode

It's used for redundancy: two replicas of the same service, two sources for the same fact, and you keep whichever answers first.

Writing your own promises

Most modern code consumes promises rather than creating them. But when you wrap a callback API, you have to build them:

function readFileAsync(path) {
  return new Promise((resolve, reject) => {
    readFile(path, "utf8", (error, data) => {
      if (error) {
        reject(error);
        return;
      }
      resolve(data);
    });
  });
}

readFileAsync("./package.json").then((data) => console.log("by hand:", data.length));
Enter fullscreen mode Exit fullscreen mode
by hand: 48
Enter fullscreen mode Exit fullscreen mode

That pattern — wrap, check the error, resolve or reject — repeats so often that Node ships the tool for it:

import { promisify } from "node:util";

const read = promisify(readFile);
read("./package.json", "utf8").then((data) => console.log("promisify:", data.length));
Enter fullscreen mode Exit fullscreen mode
promisify: 48
Enter fullscreen mode Exit fullscreen mode

And in many cases not even that: the important modules already have their promise version. fs/promises is the same fs without callbacks.

import { readFile as readFilePromise } from "node:fs/promises";

readFilePromise("./package.json", "utf8").then((data) => console.log("fs/promises:", data.length));
Enter fullscreen mode Exit fullscreen mode
fs/promises: 48
Enter fullscreen mode Exit fullscreen mode

All three return the same thing. Rule of thumb: reach for node:fs/promises and friends; use promisify for older libraries; write new Promise by hand only when the API you're wrapping has no other way out. For a few years there was even an npm package to promisify things. Yes, one. And another to tell you whether a number was even.

Common problems

Cannot read properties of undefined after a read

You forgot to check the callback's error. With the (error, data) convention, if there's an error then data is undefined, and the real error goes untold.

A then receives undefined and you don't know why

The previous then is missing its return. The chain doesn't guess: it propagates whatever the function returns, and without return that's undefined.

Promise.all fails and I lose the results that did arrive

That's its contract: all or nothing. If you need the partials, Promise.allSettled.

Three independent requests are slower than they should be

You're awaiting them one after another. If they don't depend on each other, they go in Promise.all: three of 300 ms are 300, not 900.

I'm creating promises everywhere and the code keeps growing

If you wrap functions that already return promises in new Promise, you're building something that existed. And if you find yourself nesting then inside then, it's time for the next lesson.

What you take from this lesson

  • A callback is a function that runs later; in Node, with (error, result).
  • Nesting callbacks isn't a cosmetic problem: you lose the return value and error handling multiplies.
  • A promise is a container for a future value, with three states and a single transition.
  • then chains, catch collects errors from any earlier point, finally always cleans up.
  • A then without return propagates undefined.
  • Promise.all runs in parallel and is all or nothing; Promise.allSettled gives you each outcome.
  • You almost never need new Promise: fs/promises, promisify and modern APIs already ship it.

You now know what's inside a promise and how they combine. What you don't know yet is how to write async code that reads like normal code, without chains of then. That's async/await, and it's the next lesson.

Never stop coding!

Top comments (0)