Promise chaining

Chains pass the baton

A promise chain is a row of .then calls, one after another. Each .then holds a handler: a function that runs when the step before it is done.

The handler does two things:

• It gets the value from the step before it.
• It returns the value for the next step.

The key word is return. The value a handler returns is the value the next handler gets. If the handler returns a promise, the chain waits for that promise first.

The Promises lesson showed then, catch, and finally on one promise. This lesson shows what happens when you join several steps together, and what each handler's return does. Errors get a short look here. The next lesson, Error handling with promises, covers them fully.

then always gives back a new promise. What your handler does decides what happens to that new promise.

How to read this table: each row is one thing a handler can do. The other columns say what happens to the new promise and what the next then gets.

Now step through a real chain. Pick what step 2 does, then press Replay. Before you look, guess what line 15 prints: what does step 3 get?

1function delay(value) {2  return Promise.resolve(value);3}4 5Promise.resolve("start")Run6  .then((value) => {7    console.log("step 1 received: " + value);8    return value + " → step 1";9  })10  .then((value) => {11    console.log("step 2 received: " + value);12    return delay(value + " → step 2");13  })14  .then((value) => {15    console.log("step 3 received: " + value);16    return value + " → step 3";17  })18  .then((value) => console.log("done: " + value));

Two things to notice:

• The second then does not change the first promise. It makes a new promise, and that new promise gets what step 2 returns.
• When step 2 returns a promise, step 3 does not get a promise. The chain waits for it and hands step 3 the value inside.

A thenable is any object (or function) that has a method called then. It is not a real promise. But a chain treats it like one: it calls the object's then method and waits for the value.

This lets older code libraries, or your own objects, join a promise chain.

const thenable = {
  then(resolve) {
    resolve(5);
    resolve(99);
  },
};

Promise.resolve("ticket")
  .then(() => Promise.resolve(5))
  .then((value) => console.log("promise: " + value));

Promise.resolve("ticket")
  .then(() => thenable)
  .then((value) => console.log("thenable: " + value));

The thenable on lines 1 to 6 calls resolve(5), then resolve(99). Only the first call counts, so the chain gets 5.

If a thenable throws an error before it calls resolve, the chain fails instead:

const thenable = {
  then(resolve) {
    throw new Error("broken ticket");
    resolve(5);
  },
};

Promise.resolve()
  .then(() => thenable)
  .catch((error) => console.log(error.message));

One more detail. If p is a real promise, Promise.resolve(p) gives back p itself. But new Promise((resolve) => resolve(p)) makes a different promise that waits for p. Both end the same way, but they are two different objects.

Flattening means this: when a handler returns a promise, the next handler gets the value inside it, not a promise inside a promise.

Flattening only happens for the one promise or thenable that a handler returns. It does not look inside other values. An array of promises is just an array, so the next handler gets the array. Waiting for many promises at once is covered in the Promise combinators lesson.

Returning a promise lets you write steps from top to bottom. You don't need to put each new step inside the step before it, where the code moves further right every time.

The code below does the same job twice:

• The nested version (lines 9 to 13) works, but every new step adds another level of indent.
• The flat version (lines 16 to 22) returns the inner promise, so the next then waits for it.

function getUser() {
  return Promise.resolve({ id: 7, name: "Ada" });
}
function getOrders(userId) {
  return Promise.resolve(["tea", "cake"]);
}

// Nested: it works, but the code moves further right each step.
getUser().then((user) => {
  return getOrders(user.id).then((orders) => {
    console.log(user.name + ": " + orders.join(", "));
  });
});

// Flat chain: return the promise so the next step waits.
getUser()
  .then((user) => {
    return getOrders(user.id).then((orders) => ({ user, orders }));
  })
  .then(({ user, orders }) => {
    console.log(user.name + ": " + orders.join(", "));
  });

A branch is something different. If you call .then twice on the same promise, you get two branches. Both handlers get the same value. Neither waits for the other.

You get a sequence only when the second then is called on the promise that the first then gave back.

const order = Promise.resolve("tea");

order.then((drink) => console.log("branch A: " + drink));
order.then((drink) => console.log("branch B: " + drink));

order
  .then((drink) => drink + " + cake")
  .then((combo) => console.log("chain: " + combo));

How to read this table: each row is one shape of code. The columns say what it means and when to use it.

If a handler inside then throws an error, the new promise from that then is rejected. Then:

• The next then handlers are skipped.
• The next catch gets the error.

Promise.resolve("cart")
  .then(() => {
    throw new Error("out of stock");
  })
  .catch((error) => {
    console.log("caught: " + error.message);
    return "use wishlist";
  })
  .finally(() => {
    console.log("cleanup");
    return "ignored";
  })
  .then((value) => console.log("next: " + value));

Here is what happens, step by step:

1. The first handler throws an error on line 3.
2. catch gets the error, prints it, and returns a new value, "use wishlist". Because catch returned a value, the chain is back on the success path.
3. finally runs to clean up. It gets no value and can't change the value. Even its return "ignored" is thrown away.
4. The last handler gets "use wishlist".

A good rule: put clean-up work in finally, and put "what do we do instead?" decisions in catch.

Chains help when step 2 needs the result of step 1. For example: load a session, then use its user ID to load the user, then make a greeting.

Each step returns the promise for the next job. That way, the code that calls your function can wait for the whole thing to finish.

function loadProfile() {
  return Promise.resolve({ userId: 3 })
    .then((session) => Promise.resolve({ id: session.userId, name: "Asha" }))
    .then((user) => "Hello " + user.name);
}

loadProfile().then((message) => console.log(message));

• Line 3: the first handler turns the session into a user object.
• Line 4: the next handler turns that user into "Hello Asha".
• Line 2 returns the whole chain, so on line 7 the caller can add its own last step, which prints the greeting.

Try the lab below. Change what one step returns and watch what the next step gets.

1Promise.resolve(1)2  .then((value) => {3    // Step 1: return a value, a promise, a thenable, nothing, or throw.4  })5  .then((value) => {6    // Step 2 gets what Step 1 handed on.7  })8  .then((value) => {9    // Step 3 gets what Step 2 handed on.10  })11  .catch((error) => {12    // A thrown error or a failed promise jumps here.13  });

• “then changes the old promise.” No. It makes a new promise. The old promise keeps its own value.
• “Returning a promise makes a promise inside a promise.” No. The chain waits for the returned promise and passes on its value.
• “An arrow function with curly braces returns its last line.” No. Inside curly braces you must write return.
• “.then(fn()) runs fn later.” No. The round brackets call fn right away, and then gets whatever fn returned.
• “An array of promises is unwrapped too.” No. An array is a normal value, so the next step gets the array.
• “Starting an inner chain is enough.” No. If you don't return it, the code that called your function can't wait for it.

// Mistake 1: the function runs immediately.
start.then(doStep());

// Mistake 2: curly braces but no return.
start.then((value) => {
  value + 1;
});

// Mistake 3: the inner chain starts but is not returned.
function saveThenEmail(user) {
  saveUser(user).then(() => sendEmail(user));
}

• Line 2: doStep() runs right away, not when start is done.
• Lines 5 to 7: the handler works out value + 1 but never returns it.
• Line 11: the inner chain starts, but saveThenEmail doesn't return it.

One more mistake: wrapping a promise you already have inside new Promise, just to pass on its result. It adds extra code and nothing else. Return the promise you have. Use new Promise only to turn old callback-style code into a promise.

// Avoid wrapping a promise just to forward it.
function loadMenuBad() {
  return new Promise((resolve, reject) => {
    getMenu().then(resolve, reject);
  });
}

function loadMenuGood() {
  return getMenu();
}

Key takeaways

• then always gives back a new promise.
• When a handler returns a plain value, the next handler gets that value.
• When a handler returns a promise or thenable, the chain waits and passes on its value.
• With no return, the next handler gets undefined.
• Calling .then twice on the same promise makes two branches, not a sequence.
• A thrown error skips to the next catch. Error handling with promises is up next.

Up next: Error handling with promises.