Promises, the Picture: A Token for a Value That Comes Later

Lima orders kacchi at a busy shop in Old Dhaka. The cook does not hand her a plate on the spot. The man at the counter gives her a token with a number on it. The token is not food. It is a promise that food will come, and it tells her where to stand.

Lima can do other things while she holds the token. She can buy a drink or call a friend. When the number is called, she swaps the token for the plate. If the kitchen runs out of rice, the token turns into an apology instead.

JavaScript has exactly this token. It is called a promise. In Module 12 you met the event loop and callbacks, and you saw callbacks nest into a pyramid. This module is the way out that Module 12 promised. You will learn the token first, then every method on it, then async and await, which make waiting read like plain code.

A value that is not there yet

Here is the problem a promise solves. A function asks for something slow: a price from a server, a file from a disk. It wants to return the answer. But the answer arrives after the function has already finished.

function getPrice() {
  let price;
  setTimeout(() => {
    price = 120;
  }, 10);
  return price;
}

console.log(getPrice());
console.log("the function has already returned");

undefined
the function has already returned

The function returns at once, before the timer has fired. So price is still empty when return price runs, and the program prints undefined. The 120 does arrive, ten milliseconds later, but nobody is listening any more.

Module 12's answer was a callback: pass in a function, and call it when the value arrives. That works for one step. With three slow steps in a row, each callback sits inside the one before it. A promise fixes this from the other side. The function returns something right away: a token for the value.

A promise is a token for a later value

A promise is an object that stands for a value that may not exist yet. You make one with new Promise. You hand it a function, called the executor, and JavaScript calls that function at once with two buttons: resolve and reject.

const token = new Promise((resolve) => {
  setTimeout(() => resolve("kacchi"), 10);
});

console.log(token);
token.then((dish) => {
  console.log("got " + dish);
  console.log(token);
});

Promise { <pending> }
got kacchi
Promise { 'kacchi' }

The first console.log(token) shows the promise before the timer fires. Node prints it as Promise { <pending> }: the token exists, the food does not. When the timer calls resolve("kacchi"), the promise fills. The then callback runs, and the second print shows the value inside.

Pressing resolve is how the slow code says "here is the value". Pressing reject says "it failed, and here is why". The executor decides which one to press, and when.

Three states, settled once

A promise is always in one of three states:

• pending: the value is not there yet. Every promise starts here.
• fulfilled: resolve was called, and the promise now holds its value.
• rejected: reject was called, and the promise now holds a reason, usually an Error.

Fulfilled and rejected together are called settled. The rule that makes promises safe is short: a promise settles once. After that, every later resolve or reject is ignored.

const p = new Promise((resolve, reject) => {
  resolve("first");
  resolve("second");
  reject(new Error("too late"));
});

p.then((value) => console.log("value:", value));
p.then((value) => console.log("again:", value));

value: first
again: first

Only "first" counts. The second resolve and the reject change nothing. And two separate then calls both get the same value, because the promise keeps it. A token, once swapped for a plate, stays a plate. This is what callbacks could not promise: with a callback, a buggy library could call you twice. Module 12's bug gallery showed that.

then: run this when the value arrives

then is how you say "when this promise fills, run this function with the value". The function you pass is a callback, but it is attached to the token, not passed into the slow code. Also then returns a new promise, so you can chain the next step onto it.

const cook = (dish, ms) => new Promise((resolve) => setTimeout(() => resolve(dish), ms));

cook("kacchi", 10)
  .then((dish) => dish + " with borhani")
  .then((meal) => meal.toUpperCase())
  .then((text) => console.log(text));

console.log("the counter keeps serving");

the counter keeps serving
KACCHI WITH BORHANI

Each then receives what the step before it returned. The first adds a drink, the second shouts it, the third prints it. Notice the order of the two lines in the output. The last line of the file prints first, because the chain only runs after the timer, on a later turn of the loop. The file did not stop and wait.

Compare this with Module 12's pyramid. Three steps are three flat lines, one under the other, not three levels of nesting.

catch: run this if it fails

When a promise is rejected, the then callbacks are skipped. The rejection falls down the chain until it meets a catch. A catch is a then for the failure path only.

const cook = (dish, ms) =>
  new Promise((resolve, reject) => {
    setTimeout(() => {
      if (dish === "kacchi") reject(new Error("rice is finished"));
      else resolve(dish);
    }, ms);
  });

cook("kacchi", 10)
  .then((dish) => console.log("eating " + dish))
  .catch((err) => console.log("sorry: " + err.message))
  .then(() => console.log("Lima goes home"));

sorry: rice is finished
Lima goes home

The then that would eat is skipped, the catch runs with the error, and the chain carries on after it. A catch that returns normally turns the chain back into a fulfilled one. That is why the last line still runs. Lesson 02 shows every rule of this flow.

await: wait inside an async function

Chains are flat, but they still read sideways. JavaScript has a second spelling for the same thing. Inside a function marked async, you can write await before a promise. The function pauses at that line until the promise settles. Then it carries on with the value, as if the value had been there all along.

The pause is the important part. Only this one function pauses. The rest of the program keeps running, and the loop keeps taking turns. When the promise settles, the function picks up exactly where it stopped.

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

async function countdown() {
  for (let n = 3; n >= 1; n--) {
    console.log(n);
    await sleep(10);
  }
  console.log("go");
}

countdown();
console.log("countdown started");

3
countdown started
2
1
go

sleep is the smallest useful promise: it fills after ms milliseconds, with no value. Inside countdown the loop reads top to bottom, with no callback in sight. But look at where "countdown started" lands. The function ran up to its first await, paused, and handed control back to the caller. The caller's next line ran while the countdown slept.

Watch one small chain in the widget below, one step at a time. The promises are on one side with their states, the functions paused at an await on another, and the printed lines below.

Step 3 is the one to remember: rider is paused, yet step 4 still prints. Steps 5 and 6 happen on later turns, when the timers fire. Only after packed fills does rider wake up and print.

const p = new Promise((resolve, reject) => { ... });  // the executor runs at once
resolve(value)        reject(new Error("why"))      // settle it, once
p.then((value) => next)                             // runs when p is fulfilled; returns a new promise
p.catch((err) => fallback)                          // runs when p is rejected
async function f() {                                // f always returns a promise
  const value = await p;                            // pause f until p settles
}

const step = (name, ms) =>
  new Promise((resolve) => setTimeout(() => resolve(name), ms));

step("wash rice", 10)
  .then((done) => {
    console.log(done);
    return step("cook rice", 20);
  })
  .then((done) => {
    console.log(done);
    return step("add mutton", 10);
  })
  .then((done) => console.log(done + ", ready"));

wash rice
cook rice
add mutton, ready

const step = (name, ms) =>
  new Promise((resolve) => setTimeout(() => resolve(name), ms));

async function cookKacchi() {
  console.log(await step("wash rice", 10));
  console.log(await step("cook rice", 20));
  const last = await step("add mutton", 10);
  return last + ", ready";
}

cookKacchi().then((text) => console.log(text));
console.log("the kitchen is busy");

the kitchen is busy
wash rice
cook rice
add mutton, ready

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const price = sleep(10).then(() => 120);
console.log(price);
console.log(price + 30);

Promise { <pending> }
[object Promise]30

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
function wait() {
  await sleep(10);
  console.log("done");
}
wait();

const ready = new Promise((resolve) => {
  console.log("cooking");
});

ready.then(() => console.log("served"));
console.log("waiting at the counter");

cooking
waiting at the counter

const ready = Promise.resolve("tea");
ready.then((drink) => console.log("2: " + drink));
console.log("1: order taken");

3 15
amar sonar bangla

const input = require("fs").readFileSync(0, "utf8");
const tokens = input.split(/\s+/).filter(Boolean);
let at = 0;
const next = () => tokens[at++];
const nextInt = () => Number(next());
const out = [];

// your code: read with next() and nextInt(), push every line of output to out

console.log(out.join("\n"));

amar
sonar
bangla
done

3
dal 40
bhaji 10
roti 20

const input = require("fs").readFileSync(0, "utf8");
const tokens = input.split(/\s+/).filter(Boolean);
let at = 0;
const next = () => tokens[at++];
const nextInt = () => Number(next());
const out = [];

// your code: read with next() and nextInt(), push every line of output to out

console.log(out.join("\n"));

bhaji
roti
dal

5
4
add 3
fail
add 100
fix 1

const input = require("fs").readFileSync(0, "utf8");
const tokens = input.split(/\s+/).filter(Boolean);
let at = 0;
const next = () => tokens[at++];
const nextInt = () => Number(next());
const out = [];

// your code: read with next() and nextInt(), push every line of output to out

console.log(out.join("\n"));

fulfilled 1

Next: every promise method one by one, and the rules for what each then returns.