Promise chaining

Chains pass the baton

A promise chain is a row of .then calls where each step receives the value from the previous step and decides what to hand on. The key word is return. The value a handler returns becomes the value the next handler receives. If it returns a promise, the chain waits for that promise first.

The Promises lesson introduced then, catch, and finally on a single promise. This lesson zooms in on what happens when those handlers return values and you connect several steps. Error travel gets only a quick preview here; the next lesson, Error handling with promises, studies rejections in detail.

then always returns a new promise. That new promise is fulfilled or rejected based on what your handler does. The everyday cases are straightforward:

Step through the race. Change step 2 before pressing Replay. Your job is to predict line 15: what does step 3 receive?

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));

Notice two important details. First, the second then does not change the original promise; it creates a new promise that follows step 2’s return. Second, returning a promise does not give the next handler a promise-in-a-box. The chain waits and hands on the fulfilled value.

JavaScript also recognizes thenables: objects or functions with a callable then method. They are not native promises, but promise resolution treats them as promise-shaped values. That lets older libraries or custom objects plug into promise chains.

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 above calls resolve(5) and then tries resolve(99). Only the first resolve counts. If a thenable throws before resolving, the adopting promise rejects:

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

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

Professional note: Promise.resolve(p) returns p itself when p is a native promise. By contrast, new Promise((resolve) => resolve(p)) creates a different promise that adopts p. Both eventually settle the same way, but they are not the same object.

Flattening applies to one returned promise or thenable. It does not recursively wait for every promise found inside every JavaScript value. An array of promises is just an array; waiting for many promises is the job of the Promise combinators lesson.

A returned promise lets you write async steps top to bottom instead of building a sideways pyramid. The nested version below works, but every new async step adds another level of indentation. The flat version returns the inner promise so the outside chain can wait for it.

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

// Nested pyramid: works, but the shape grows sideways.
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(", "));
  });

Branching is different. Calling .then twice on the same promise creates two branches. Both handlers receive the same original value. They do not form a sequence unless the second then is called on the promise returned by the first then.

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));

Chains are handy whenever step 2 needs step 1’s result: load a session, then use its user ID, then use the user data, then render. Each step returns the promise for the next piece of work so the whole function is waitable by its caller.

function loadProfile() {
  return getSession()
    .then((session) => getUser(session.userId))
    .then((user) => getAvatar(user.avatarId))
    .then((avatar) => renderProfile(avatar));
}

Try building chains yourself. The lab below executes real promises in your browser and shows the value each step received, with milliseconds since you pressed Run.

1Promise.resolve(1)2  .then((value) => {3    // Step 1: choose return value, promise, thenable, nothing, or throw.4  })5  .then((value) => {6    // Step 2 receives what Step 1 returns or adopts.7  })8  .then((value) => {9    // Step 3 receives what Step 2 returns or adopts.10  })11  .catch((error) => {12    // A thrown error or rejection skips here.13  });

• “then changes the old promise.” It returns a new promise; the original promise keeps its own result.
• “Returning a promise makes a nested promise.” It does not. Promise resolution adopts the returned promise’s state.
• “Braces in an arrow function return the last expression.” They do not. Use return.
• “.then(fn()) means run fn later.” It calls fn immediately and passes its result as the handler.
• “An array of promises is flattened automatically.” No; arrays are ordinary values.
• “Starting an inner chain is enough.” If you do not return it, the caller cannot wait for it.

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

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

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

Another smell is the explicit-construction anti-pattern: wrapping a promise in new Promise only to resolve or reject with the same promise. Return the existing promise unless you are adapting a callback-style API.

// 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 returns a new promise.
• A handler’s returned plain value becomes the next fulfillment value.
• A returned promise or thenable is adopted, so chains flatten.
• No return means the next handler receives undefined.
• Calling .then twice on the same promise creates branches, not a sequence.
• Throws and rejections skip to the next catch; Error handling with promises is up next.

Up next: Error handling with promises.