Escaping Callback Hell

You convert the callback-based functions into ones that return promises, and then you write the sequence as a flat chain or as an async function with awaits. The nesting disappears because each step now produces a value you can pass to the next one.

// The promise version of a two step sequence.
const readFileAsync = (name) =>
  new Promise((resolve) => setTimeout(() => resolve("content of " + name), 5));

const parseAsync = (text) =>
  new Promise((resolve) => setTimeout(() => resolve({ lines: text.length }), 5));

async function run() {
  const text = await readFileAsync("notes.txt");
  const parsed = await parseAsync(text);
  console.log(parsed.lines);
}

run();

The change is small and mechanical. A callback function becomes a function that returns a promise, and the call site changes from passing a callback to using await. The steps keep their order, but they sit next to each other rather than nested inside each other.

Two techniques are worth naming. The first is a generic promisify helper, which turns any function that follows the error-first callback convention into one that returns a promise. Write it once and every legacy API in your codebase becomes chainable. The second is to wrap a whole callback-based module at its boundary, so the rest of your code only ever sees promises.

There is a middle option too. Some teams keep the callback API but give each step a named function and pass the next step in explicitly, which is the continuation passing style. It flattens the structure without changing the underlying contract, and it is a reasonable choice when you cannot change the API you are calling.

Callback hell is a name for the shape you get when asynchronous steps depend on each other and each one is written inside the callback of the previous one. The code ends up as a pyramid of indentation, with the actual logic at the bottom and the setup at the top.

It is a problem for four reasons. The structure of the code stops matching the structure of the process, so it is much harder to read and to reorder. The error handling has to be repeated in every level, and one forgotten check means a failure disappears. There is no way to run two of these in parallel and wait for both, or to give the whole sequence a timeout, without writing the coordination by hand. And the deepest level is the most indented, which is exactly where indentation stops working well.

It is worth being fair about the severity. Callback hell is a readability problem, not a correctness problem in itself. The code works, and for two or three steps it is perfectly readable. The pain starts when you have five or more dependent steps, when you need to handle errors in every one of them, or when you need to combine them.

The modern answer is promises for sequencing and error handling, and the promise combinators for the cases where you need parallelism or a timeout. Promises also give you a uniform way to compose work from different libraries, which matters more in real code than the shape of the nesting does.

The example below starts with a three step callback chain and refactors it into an async function. The promisify helper at the top is the piece that makes the refactor short, because it adapts any error-first callback function into one that returns a promise.

// Wrap any error-first callback function as a promise.
const promisify = (fn) => (...args) =>
  new Promise((resolve, reject) => {
    fn(...args, (err, value) => (err ? reject(err) : resolve(value)));
  });

const getUser = promisify((id, cb) => setTimeout(() => cb(null, { id }), 5));
const getOrders = promisify((userId, cb) => setTimeout(() => cb(null, [{ id: "o1", userId }]), 5));
const getItems = promisify((orderId, cb) => setTimeout(() => cb(null, [{ id: "i1", orderId }]), 5));

async function loadAll(id) {
  const user = await getUser(id);
  const orders = await getOrders(user.id);
  const items = await getItems(orders[0].id);
  return items;
}

loadAll(1)
  .then((items) => console.log("items:", items))
  .catch((err) => console.log("failed:", err.message));

The refactor does three things. Each step becomes a single await, so the nesting is gone. The error handling moves to a single catch at the end of the chain, and because an await throws when the promise rejects, the chain stops at the first failure without running the later steps. And the promisify helper means you did not have to rewrite the underlying callback functions, only their call sites.

Two details to point out. The error-first convention maps onto the promise world directly: the first argument becomes the rejection reason and the second becomes the resolved value. And if a callback API calls its callback more than once, promisify would resolve the promise on the first call and ignore the rest, which is usually the behaviour you want but is worth knowing.