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.
getTea()runs. Its only job is to start the timer (hand the waiting to Node.js).getTeareaches its end. It has noreturnof its own, so it returnsundefined.teaisundefined, and that prints right away.- 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
doneis just a parameter name: it holds the function we passed in. (cb,callback,nextare common names too.)- After one second,
getTeacallsdone("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.
fsis Node's built-in file system module: functions to read, write and delete files.require("fs")loads a module and gives you its functions. (requireis Node's classic way to import code; you'll seeimportlater.)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:erranddata.
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("...")), anErrorobject with amessage. - Worked:
callback(null, result).nullmeans "intentionally nothing": here, no error. - The receiver checks
errfirst, 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
- Write
boilTea(cb)that prints "Boiling..." and calls back with "tea is ready" after 1 second. - Write
divide(a, b, cb)with an error-first callback that fails whenbis 0. - Read a missing file with
fs.readFileand printerr.code. - 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'
- See "A way out: name your callbacks" above:
takeOrderpassescook,cookpassespack,packpassesdeliver,deliverpassesenjoy. 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, thencb 7 - B.
cb 7, thenx 3 - C.
x 7, thencb 3 - D.
x undefined, thencb 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
returninside asetTimeoutcallback 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
nullmean there? - Why can't
try/catcharoundsetTimeoutcatch an error thrown inside the timer? - What does
ENOENTmean? - 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
fnand passingfn()?
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
returninside a timer goes nowhere: the outer function already returnedundefined. - 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 checkerrfirst. try/catchcan'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?