Callbacks

Callbacks that finish later

A callback is a function you pass to another function. The other function calls it for you, at the right time.

You met callbacks before, in Function expressions & callbacks. There, array methods like map called your function straight away, while they were still running.

This lesson is about callbacks that run later. For example: a timer that ends, a click on a button, a file that finishes loading, or an answer from a server. In each case, the answer arrives after the rest of your code has moved on.

So the question changes. You don't ask "what does this function return?" You ask three things:

• Who will call my function?
• What values will it pass in?
• When will it call it?

Callbacks are very useful, but they can go wrong in a few ways. This lesson covers each one: code nested deeper and deeper, handling errors, trusting other people's code, and timing bugs.

function greetUser(name, done) {
  done("Hello, " + name);
}

greetUser("Asha", (message) => console.log(message));

Line 1 makes a function, greetUser. It takes a name and a function called done. Line 2 calls done straight away with a greeting. Line 5 calls greetUser and passes in a small arrow function as done.

It prints Hello, Asha before greetUser finishes. A callback that runs before the other function finishes is called synchronous, or "sync".

Every example on this page runs real JavaScript. The step-through players replay a recorded run, one step at a time. The playgrounds use real setTimeout timers, and Reset stops any timer that is still waiting.

Sync code runs now, one line after another. An async callback runs later: after the current script has finished, when the host has something to report.

The host is the program that runs your JavaScript, like the browser or Node. It looks after timers, clicks, and files. An async callback is not magic. It is still a normal function call. The only difference is that the host makes the call, and it makes it later.

1console.log("drop off laptop");Run2setTimeout(() => {3  console.log("repair shop calls back");4}, 0);5console.log("walk home");

setTimeout does not pause the script. It hands your function to the host and finishes at once. So the script goes on to line 5 and prints walk home. Only after the whole script is done does the host call your callback. The event loop lesson explains why callbacks wait for the current script to finish.

function loadGreeting(done) {
  setTimeout(() => done("Hello, Asha"), 0);
}

loadGreeting((message) => console.log(message));

Line 1 makes loadGreeting, which takes one callback, done. Line 2 starts a timer, and loadGreeting finishes straight away, without a greeting. Later the timer calls done with "Hello, Asha". The callback from line 5 then decides what to do with the greeting: here, it prints it.

A plain return can't work here. The function returns before the timer ends, so it has no greeting to give back yet.

const shoppingList = ["tea", "soap"];
const food = shoppingList.filter((item) => item === "tea");
console.log(food.join(", "));

Line 2 runs filter. It calls your callback for "tea" and then for "soap", before filter finishes. Only "tea" passes the test, so line 3 prints tea. This is still a callback. It just runs now, not later.

Many Node functions call your callback with two values, in this order:

• First, the error. If the job worked, this is null, which means "no error".
• Second, the result. It is only there if the job worked.

So the callback looks like callback(err, result). This style is called an error-first callback. If the job fails, err is an Error object, and the result is missing or can't be trusted.

1function readProfile(id, callback) {2  setTimeout(() => {3    if (id === "missing") {4      callback(new Error("profile not found"));5      return;6    }7    callback(null, { name: "Ada" });8  }, 0);9}

1function finish(err, data) {2  if (err) {3    showError(err.message);4    return;5  }6  showProfile(data.name);7}

Look at the short return inside the error branch. It stops the callback, so the success code can't run too. People often forget it. Then the page shows an error, and also tries to show data that isn't there.

function saveNote(text, done) {
  if (!text) return done(new Error("empty note"));
  done(null, "saved");
}

saveNote("tea", (err, result) => {
  if (err) return console.log("error: " + err.message);
  console.log(result);
});

saveNote("", (err, result) => {
  if (err) return console.log("error: " + err.message);
  console.log(result);
});

The first call passes "tea", so saveNote calls back with null as the error. The callback prints saved.

The second call passes an empty text, so saveNote calls back with an Error. The callback prints error: empty note and returns before it touches the result. Don't trust the result until you have checked err.

Sometimes one job must wait for another. For example, you need the user before you can load their orders. With callbacks, you start each next job inside the callback of the job before it.

Each new step adds more indentation, the space at the start of a line. So the code moves further right with every step. This shape is nicknamed callback hell, or the pyramid of doom. It causes three problems:

• The code drifts to the right and gets hard to read.
• Every step repeats the same error check.
• The real story (user, then orders, then delivery) hides among the brackets.

1function orderPizza(userId, done) {2  getUser(userId, (userErr, user) => {3    if (userErr) return done(userErr);4    getOrders(user.id, (ordersErr, orders) => {5      if (ordersErr) return done(ordersErr);6      getDelivery(orders[0].id, (deliveryErr, delivery) => {7        if (deliveryErr) return done(deliveryErr);8        done(null, delivery.eta);9      });10    });11  });12}

Named functions don't remove the callbacks. They only remove the pyramid shape: each step gets a name and sits at the left edge.

Promises, in the next lessons, go further. A promise turns "a result that arrives later" into a value you can return, chain, and catch errors on. The Promisification lesson shows how to turn this exact error-first style into promises.

When you pass a callback, you let other code decide when your next step runs. This is called inversion of control: control moves from your code to the other code. You trust that code to call your callback:

• once,
• at the right time,
• with the right values.

Built-in functions like setTimeout do this reliably. Code written by other people, called a library, might not. It could call your callback twice, too early, or never.

1function once(callback) {2  let called = false;3  return (...args) => {4    if (called) return;5    called = true;6    callback(...args);7  };8}9 10function withTimeout(callback, ms) {11  const safeCallback = once(callback);12  const timer = setTimeout(() => {13    safeCallback(new Error("timed out"));14  }, ms);15  return (...args) => {16    clearTimeout(timer);17    safeCallback(...args);18  };19}

A once() guard is a small wrapper around your callback. The first call runs your callback. Every later call is ignored.

A time limit, or timeout, handles the other case. If nothing happens in time, it calls your callback with an error. Then your page doesn't wait forever.

function once(callback) {
  let called = false;
  return (value) => {
    if (called) return;
    called = true;
    callback(value);
  };
}

const logOnce = once((value) => console.log(value));
logOnce("first");
logOnce("second");

Line 2 makes a flag, called, set to false. Lines 3 to 7 return a new function that checks the flag. Line 11 calls it for the first time. The flag is still false, so it becomes true and first is printed. Line 12 calls it again. Now the flag is true, so line 4 returns and nothing prints.

The new function can still see called after once has finished. It keeps access to the variables around it; this is called a closure. The guard stops double calls. It can't fix a library that passes the wrong values, so check those values too.

Some functions call your callback right away in some cases, and later in others. Programmers have a nickname for this: Zalgo.

A common cause is a cache, a store of answers you already have:

• If the answer is in the cache (a cache hit), the function can call back right away.
• If it isn't (a cache miss), the function must fetch the answer first, and call back later.

This uneven timing breaks the code that runs right after the call. That code can't know whether the callback has run yet.

1const cache = new Map([["ada", "Ada Lovelace"]]);Run2 3function getName(id, callback) {4  if (cache.has(id)) {5    callback(cache.get(id));      // sync on cache hit6    return;7  }8  setTimeout(() => {9    callback("Grace Hopper");10  }, 0);11}12 13console.log("before");14getName("ada", (name) => console.log(name));15console.log("after");

The fix is not to make everything slow. The fix is to make it the same every time. If a function calls back later in one case, it should call back later in every case, even when the answer is in the cache.

queueMicrotask or setTimeout can delay the cache-hit callback. queueMicrotask(fn) runs fn as soon as the current script finishes. setTimeout(fn, 0) runs it a little later. Either one works here.

Where you'll use callbacks

Newer code often uses promises instead. But callbacks are still everywhere, because a function is how JavaScript says "do this later". You'll see them in:

• event listeners, like a click on a button,
• timers, like setTimeout,
• array methods, like map and filter,
• older Node functions, like fs.readFile,
• test tools and libraries written by other people.

The table below lists each callback problem from this lesson. Read each row as: "this goes wrong, here is the callback fix, and here is how promises handle it."

1import { readFile } from "node:fs";2 3readFile("profile.json", "utf8", (err, text) => {4  if (err) return console.error(err.message);5 6  const profile = JSON.parse(text);7  console.log(profile.name);8});

Line 3 starts reading profile.json and gives readFile a callback. readFile returns at once. Later, Node calls the callback with an error or with the file's text. Line 4 handles the error and stops. Line 6 turns the text into an object with JSON.parse, and line 7 prints the name.

You don't need Node for this page. But you'll see this pattern often: start a job, return now, and get an error or a result later.

Common misconceptions

For each question, first ask: does the callback run now, or later? Each answer explains why it is right or wrong.

Key takeaways

• A callback is a function you pass to another function. An async callback is called later, when a job finishes.
• Error-first callbacks look like callback(err, result). Check the error first, and return from that branch before you use the result.
• Callback hell is steps nested inside steps, with the same error check repeated. Named functions flatten it, and promises fix more of it.
• Inversion of control means other code decides if and when your callback runs. A once() guard and a time limit protect you.
• A function should never call back right away in some cases and later in others. That timing bug is called Zalgo.

Up next: Promises, which fix many callback problems.