SyntaxPilot
Courses/JavaScript/Lesson 25
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

JavaScript · Lesson 25 of 40

Callbacks

queued

These are the notes for JavaScript episode 25. Last episode you met the event loop: Node.js does the waiting, and finished work joins a queue. That leaves one big question: when the waiting is over, how does the result get back to your code? You'll try the obvious thing, return the value from inside a setTimeout, and get I got: undefined. You'll see why (the outer function already returned), and then invent the fix: pass a function in, and let the slow code call you back. That's a callback. You'll compare synchronous callbacks (forEach) with asynchronous ones (setTimeout, fs.readFile), read a real file, learn Node's error-first rule callback(err, result), see why try/catch can't catch an error thrown later, run async steps in the right order, and meet the famous pyramid of doom (callback hell) with a simple way out. Every output below is real Node.js output (node main.js); timings will differ slightly on your machine.

Builds on: functions and arrow functions (episode 9), scope and closures (10), arrays and forEach (11), try/catch and Error objects (13), the event loop (24). Leads to: promises (26), async/await (27).

The real-life idea: leave your phone number

You walk into a busy restaurant and order a biryani. It takes twenty minutes.

  • You could stand at the kitchen door for twenty minutes, staring at the cook. But then you can't sit, chat, or do anything else. That's the frozen program from episode 24.
  • Instead you leave your phone number at the counter: "When it's ready, here's how to reach me." Then you go and sit down.
  • Twenty minutes later your phone rings. They called you back, with the biryani.
Restaurant JavaScript
Your phone number ("how to reach you") a function you pass in: the callback
The kitchen, which does the slow work the slow function (getTea, fs.readFile): starts the job and returns at once
You go and sit down the rest of your program keeps running
"Ring! It's ready" the slow function calls done(result)
"Sorry, we're out of biryani" it calls back with an error instead: callback(err)

The problem: return inside setTimeout gives undefined

Making tea takes time, so getTea uses a one-second setTimeout and then returns the tea:

function getTea() {
  setTimeout(() => {
    return "masala chai";
  }, 1000);
}
const tea = getTea();
console.log("I got:", tea);
I got: undefined

No tea, and the program didn't even wait one second for it.

Why: a late return goes nowhere

Look at where the return is. It's inside the little arrow function () => { ... }, not inside getTea.

  1. getTea() runs. Its only job is to start the timer (hand the waiting to Node.js).
  2. getTea reaches its end. It has no return of its own, so it returns undefined. tea is undefined, and that prints right away.
  3. One second later the event loop runs the arrow function. It returns "masala chai"... to the timer system, which ignores it. Nobody is listening. The value is lost.

A function can only return once, at the moment it finishes. If the answer doesn't exist yet when it finishes, return can't deliver it. We need a way to deliver the result later.

The fix you invent: the callback

Copy the restaurant: instead of asking for the tea back, hand getTea your "phone number". In JavaScript, the phone number is a function.

A callback is a function you pass to another function as an argument, so that the other function can call it later (or now) with a result.

function getTea(done) {
  console.log("Order placed, boiling...");
  setTimeout(() => {
    done("masala chai");
  }, 1000);
}
getTea((tea) => console.log("I got:", tea));
console.log("Meanwhile, I read the newspaper");
Order placed, boiling...
Meanwhile, I read the newspaper
I got: masala chai
  • done is just a parameter name: it holds the function we passed in. (cb, callback, next are common names too.)
  • After one second, getTea calls done("masala chai"): the tea is passed in as an argument. They rang us back.
  • The newspaper line was written last but printed second. Anything that needs the tea must go inside the callback. Code after getTea(...) runs before the tea exists.

Functions are values: higher-order functions

Passing a function around works because in JavaScript functions are values, like numbers or strings: you can store them in variables and pass them as arguments. A function that takes a function (or returns one) is called a higher-order function.

function serve(customer, callback) {
  callback("Hello, " + customer);
}
serve("Asha", (msg) => console.log(msg.toUpperCase()));
serve("Ravi", console.log);
HELLO, ASHA
Hello, Ravi

serve is a higher-order function; the arrow function and console.log are the callbacks. Note: we pass console.log, not console.log(). Adding () would call it right now and pass its result instead.

Synchronous vs asynchronous callbacks

Surprise: you've used callbacks for weeks. The arrow function you give to forEach, map or filter is a callback. The difference is when it's called:

Synchronous (sync) callback Asynchronous (async) callback
Called right now, before the outer function returns later, from the queue, through the event loop
Examples forEach, map, filter, sort setTimeout, setInterval, fs.readFile
Runs before the next line? yes no: only when the stack is empty, after all current code
const prices = [10, 20, 30];
prices.forEach((p) => console.log("price", p));
console.log("forEach done");
setTimeout(() => console.log("timer callback"), 0);
console.log("end of script");
price 10
price 20
price 30
forEach done
end of script
timer callback

forEach finished all three callbacks before moving on. The timer callback came after end of script, even with a 0 ms delay. Same idea, a function passed in, called at a different time.

Real I/O: reading a file with fs.readFile

Timers are a toy. Callbacks really exist for I/O (input/output): files, the network, databases. These are slow, so Node.js does them outside your JavaScript and calls you back.

  • fs is Node's built-in file system module: functions to read, write and delete files.
  • require("fs") loads a module and gives you its functions. (require is Node's classic way to import code; you'll see import later.)
  • fs.readFile(name, encoding, callback) reads a whole file. "utf8" is the encoding: it tells Node to give you text instead of raw bytes. The callback gets two parameters: err and data.
const fs = require("fs");
fs.readFile("menu.txt", "utf8", (err, data) => {
  if (err) {
    console.log("Error:", err.message);
    return;
  }
  console.log(data);
});
console.log("Reading the menu...");

With no menu.txt in the folder:

Reading the menu...
Error: ENOENT: no such file or directory, open 'menu.txt'

Instead of crashing, Node handed us the error through the callback. ENOENT is Node's short code for "Error, NO ENTry": the file or folder doesn't exist. (err.code holds "ENOENT"; err.message holds the full sentence.)

Now create menu.txt with three lines and run the same code again:

Reading the menu...
Masala chai - 20
Veg biryani - 180
Masala dosa - 90

(The empty last line is there because the file ends with a newline, and console.log adds one more.) So a callback must carry two possible outcomes: the result, or what went wrong.

Error-first callbacks: callback(err, result)

Node settled on one simple rule, the error-first callback (also called "Node-style callback"):

  • The first argument is always the error; the second is the result.
  • Failed: callback(new Error("...")), an Error object with a message.
  • Worked: callback(null, result). null means "intentionally nothing": here, no error.
  • The receiver checks err first, every time, and stops (return) if there is one.

Every classic Node function (fs.readFile, fs.writeFile, ...) works this way. Writing our own:

function orderFood(item, callback) {
  setTimeout(() => {
    if (item === "pizza") callback(new Error("pizza is not on the menu"));
    else callback(null, item + " order #42");
  }, 300);
}
function handle(err, order) {
  if (err) return console.log("Sorry:", err.message);
  console.log("Confirmed:", order);
}
orderFood("dosa", handle);
orderFood("pizza", handle);
Confirmed: dosa order #42
Sorry: pizza is not on the menu

One callback, both outcomes handled. if (err) return ... is the early return pattern: handle the error and leave, so the success code below never runs with bad data.

Forgetting to check err

function orderFood(item, callback) {
  setTimeout(() => {
    if (item === "pizza") callback(new Error("pizza is not on the menu"));
    else callback(null, item + " order #42");
  }, 300);
}
orderFood("pizza", (err, order) => {
  console.log("Order:", order.toUpperCase());
});
  console.log("Order:", order.toUpperCase());
                              ^

TypeError: Cannot read properties of undefined (reading 'toUpperCase')

On failure only one argument was passed, so order is undefined, and calling a method on undefined crashes the whole program.

Why try/catch can't catch an error thrown later

Can't we just wrap the call in try/catch, like in episode 13?

try {
  setTimeout(() => {
    throw new Error("Stove broke!");
  }, 0);
} catch (e) {
  console.log("caught:", e.message);
}
console.log("try/catch finished");
try/catch finished
    throw new Error("Stove broke!");
    ^

Error: Stove broke!

caught: never prints, and the program crashes with an uncaught error. The try block only started the timer and ended long before the timer fired. When the error is thrown, the try/catch is gone from the call stack: nobody is there to catch it. That's exactly why async code passes errors as an argument instead of throwing them. (A try/catch inside the callback does work, because it runs at the same time as the throw:)

setTimeout(() => {
  try {
    throw new Error("Stove broke!");
  } catch (e) {
    console.log("caught:", e.message);
  }
}, 0);
console.log("timer started");
timer started
caught: Stove broke!

Running steps in order

A food delivery has steps: take the order, cook the biryani, pack it, deliver it. Each takes a different time. Calling them one after another, like normal code:

function step(name, ms) {
  setTimeout(() => console.log("done:", name), ms);
}
step("take order", 300);
step("cook biryani", 500);
step("pack it", 200);
step("deliver", 400);
done: pack it
done: take order
done: deliver
done: cook biryani

Packed and delivered before cooking! All four timers started at the same moment, so the quickest finished first. Async calls don't wait for each other: writing them one after another only starts them one after another. If a step needs the previous one to be finished, it must start inside the previous step's callback:

function step(name, ms, cb) {
  setTimeout(() => { console.log("done:", name); cb(null); }, ms);
}
step("take order", 300, (err) => {
  if (err) return console.log(err.message);
  step("cook biryani", 500, (err) => {
    if (err) return console.log(err.message);
    step("pack it", 200, (err) => {
      if (err) return console.log(err.message);
      step("deliver", 400, (err) => {
        if (err) return console.log(err.message);
        console.log("Enjoy your meal!");
      });
    });
  });
});
done: take order
done: cook biryani
done: pack it
done: deliver
Enjoy your meal!

The right order at last. But look at the shape.

The pyramid of doom (callback hell)

Every dependent step lives inside the previous callback, so the code drifts to the right: four steps, four levels deep, and an error check repeated at every level. Programmers call this callback hell, or the pyramid of doom, after its sideways-triangle shape (}); stacked at the bottom). It's hard to read, hard to change, and easy to forget one of the error checks.

There's also a quieter problem: inversion of control. When you hand over a callback, someone else's code decides when, and how many times, your function runs. You're trusting it to call you exactly once. A buggy library might call it twice, or never:

function buggyPay(amount, callback) {
  setTimeout(() => {
    callback(null, "paid " + amount);
    callback(null, "paid " + amount);
  }, 100);
}
let charges = 0;
buggyPay(250, (err, receipt) => {
  charges++;
  console.log(receipt, "| times charged:", charges);
});
paid 250 | times charged: 1
paid 250 | times charged: 2

The customer was charged twice, and there's nothing in the callback style to stop it. Keep that worry: promises (next episode) fix it.

A way out: name your callbacks

Give every step a name, and pass the next function as the callback:

function step(name, ms, cb) {
  setTimeout(() => { console.log("done:", name); cb(null); }, ms);
}
function takeOrder() { step("take order", 300, cook); }
function cook(err) { if (err) return; step("cook biryani", 500, pack); }
function pack(err) { if (err) return; step("pack it", 200, deliver); }
function deliver(err) { if (err) return; step("deliver", 400, enjoy); }
function enjoy(err) { if (!err) console.log("Enjoy your meal!"); }
takeOrder();
done: take order
done: cook biryani
done: pack it
done: deliver
Enjoy your meal!

Same correct order, and the code is flat: each step is a small named function you can read and test on its own. It helps, but the steps are still chained by hand, and the trust problem is still there.

Common mistakes (and what really happens)

You wrote What happens Why Fix
return value inside setTimeout I got: undefined the outer function already returned pass a callback
code after getTea(cb) uses the tea Drinking: undefined (runs before the tea exists) async callbacks run later use it inside the callback
(err, order) => order.toUpperCase() TypeError: Cannot read properties of undefined (reading 'toUpperCase') err was not checked if (err) return ... first
try { setTimeout(() => { throw ... }) } Error: Stove broke! (uncaught, program crashes) the try ended before the throw pass errors to the callback
stepA(); stepB(); stepC(); (async) steps finish in the wrong order async calls don't wait start B inside A's callback
setTimeout(shout(), 100) (where shout returns "done") shout runs now, then TypeError [ERR_INVALID_ARG_TYPE]: The "callback" argument must be of type function. Received type string ('done') () calls it and passes its result pass shout, not shout()

The second row, run for real:

let tea;
function getTea(done) {
  setTimeout(() => done("masala chai"), 1000);
}
getTea((t) => { tea = t; });
console.log("Drinking:", tea);
Drinking: undefined

Saving the result to an outer variable doesn't help: the console.log runs a whole second before tea is set.

Mini project: order and bill

Two async steps with error-first callbacks: place an order (fails for unknown items), then save the bill with fs.writeFile(name, text, callback), which writes text to a file and calls back with only err. items.find(...) returns the first item not on the menu (or undefined); reduce adds up the prices.

const fs = require("fs");
const menu = { chai: 20, samosa: 15, biryani: 180 };

function placeOrder(items, callback) {
  setTimeout(() => {
    const missing = items.find((item) => !(item in menu));
    if (missing) return callback(new Error(missing + " is not on the menu"));
    const total = items.reduce((sum, item) => sum + menu[item], 0);
    callback(null, items.join(" + ") + " = Rs " + total);
  }, 200);
}

function billCustomer(items) {
  placeOrder(items, (err, bill) => {
    if (err) return console.log("Order error:", err.message);
    fs.writeFile("bill.txt", bill + "\n", (err) => {
      if (err) return console.log("Save error:", err.message);
      console.log("Saved bill:", bill);
    });
  });
}

billCustomer(["chai", "samosa", "samosa"]);
billCustomer(["chai", "pizza"]);
console.log("Kitchen is working...");
Kitchen is working...
Order error: pizza is not on the menu
Saved bill: chai + samosa + samosa = Rs 50

bill.txt now contains chai + samosa + samosa = Rs 50. The pizza error prints before the first bill: both orders ran at the same time, and the first one still had a file to write. Extension: also read the menu from a file with fs.readFile, and rewrite billCustomer with named functions.

Practice

  1. Write boilTea(cb) that prints "Boiling..." and calls back with "tea is ready" after 1 second.
  2. Write divide(a, b, cb) with an error-first callback that fails when b is 0.
  3. Read a missing file with fs.readFile and print err.code.
  4. Rewrite the 4-step delivery pyramid with named functions.
Solutions

1.

function boilTea(cb) {
  console.log("Boiling...");
  setTimeout(() => cb("tea is ready"), 1000);
}
boilTea((msg) => console.log(msg));
console.log("I can do other things");
Boiling...
I can do other things
tea is ready

2.

function divide(a, b, cb) {
  setTimeout(() => {
    if (b === 0) return cb(new Error("cannot divide by zero"));
    cb(null, a / b);
  }, 100);
}
function show(err, result) {
  if (err) return console.log("Error:", err.message);
  console.log("Result:", result);
}
divide(10, 2, show);
divide(5, 0, show);
Result: 5
Error: cannot divide by zero

3.

const fs = require("fs");
fs.readFile("no-such-file.txt", "utf8", (err, data) => {
  if (err) {
    console.log("code:", err.code);
    console.log("message:", err.message);
    return;
  }
  console.log(data);
});
code: ENOENT
message: ENOENT: no such file or directory, open 'no-such-file.txt'
  1. See "A way out: name your callbacks" above: takeOrder passes cook, cook passes pack, pack passes deliver, deliver passes enjoy. Output: done: take order, done: cook biryani, done: pack it, done: deliver, Enjoy your meal!.

Quick quiz

What does this print?

function getNum(cb) {
  setTimeout(() => cb(7), 0);
  return 3;
}
const x = getNum((n) => console.log("cb", n));
console.log("x", x);
  • A. x 3, then cb 7
  • B. cb 7, then x 3
  • C. x 7, then cb 3
  • D. x undefined, then cb 7
Answer

A. getNum returns 3 right away, so x is 3 and prints first. The callback runs later, from the queue, with 7.

x 3
cb 7

Interview questions

  • What is a callback? Give one synchronous and one asynchronous example.
  • Why does return inside a setTimeout callback not return from the outer function?
  • What is a higher-order function? Name three built-in ones.
  • What is an error-first callback? Why is the error first, and what does null mean there?
  • Why can't try/catch around setTimeout catch an error thrown inside the timer?
  • What does ENOENT mean?
  • How do you make async steps run in a fixed order with callbacks?
  • What is callback hell (the pyramid of doom)? How can you reduce it without promises?
  • What is inversion of control, and what can go wrong when a callback is called twice or never?
  • What's the difference between passing fn and passing fn()?

Glossary

Term Meaning Example
Callback a function you pass to another function, to be called by it getTea((tea) => console.log(tea))
Synchronous callback a callback called right away, before the outer function returns forEach((p) => ...)
Asynchronous callback a callback called later, from the queue, after all current code setTimeout(fn, 1000)
Higher-order function a function that takes or returns a function forEach, serve(name, cb)
Functions are values functions can be stored and passed like numbers serve("Ravi", console.log)
setTimeout(fn, ms) run fn once after at least ms ms setTimeout(cb, 1000)
Event loop runs queued callbacks whenever the call stack is empty (episode 24) timer callbacks run last
I/O (input/output) reading or writing outside the program: files, network, databases fs.readFile
fs Node's built-in file system module fs.readFile, fs.writeFile
require(name) Node's classic way to load a module const fs = require("fs")
Module a file or package of code you can load and reuse fs
Encoding ("utf8") how bytes are turned into text fs.readFile(f, "utf8", cb)
fs.readFile read a whole file; calls back with (err, data) menu example
fs.writeFile write text to a file; calls back with (err) bill.txt
ENOENT Node error code: "Error, NO ENTry", the file/folder doesn't exist err.code === "ENOENT"
Error object an object describing what went wrong, with a message new Error("pizza is not on the menu")
err.message / err.code the error's sentence / short machine code "ENOENT: no such file..." / "ENOENT"
Error-first callback convention: callback(err, result), error first, result second handle(err, order)
null a value meaning "intentionally nothing"; here, no error callback(null, order)
Early return return as soon as you handle an error if (err) return ...
Uncaught error a thrown error that no try/catch catches; it crashes the program Error: Stove broke!
TypeError error for using a value the wrong way, e.g. a method on undefined order.toUpperCase()
Nesting putting one callback inside another the delivery steps
Callback hell / pyramid of doom deeply nested callbacks drifting right, hard to read and change 4-level delivery
Inversion of control handing control of when your code runs to someone else's function a library calling you twice
Named callback a callback defined as a named function and passed by name step("pack it", 200, deliver)
Promise an object representing a future result, ready only once (episode 26) next episode

Summary

  • A return inside a timer goes nowhere: the outer function already returned undefined.
  • A callback is a function you pass in; the slow function calls you back with the result. Code that needs the result goes inside the callback.
  • Sync callbacks (forEach, map) run now; async callbacks (setTimeout, fs.readFile) run later, after all current code.
  • Node uses error-first callbacks: callback(err) on failure, callback(null, result) on success. Always check err first.
  • try/catch can't catch an error thrown later in a callback, which is why errors are passed, not thrown.
  • Dependent async steps must nest, which grows into the pyramid of doom; named functions flatten it, but you still trust others to call you exactly once (inversion of control).

Next episode: Promises. What if, instead of handing out your phone number, the restaurant hands you a token, a promise that the food is coming, which can only ever be ready (or fail) once?