Promise Chaining

1The Mechanism: Each .then() Returns a New Promise

Promise.resolve(1)
  .then(n => n + 1)   // returns a new Promise resolved with 2
  .then(n => n * 10)   // returns a new Promise resolved with 20
  .then(n => console.log(n)); // 20

Because every .then() returns a new Promise (see the Promises topic), chains can be built to any length, with each step transforming the previous result.

2Returning a Promise from .then() — Automatic Flattening

If a .then() callback returns another Promise, the chain automatically waits for it and unwraps its value — it does not nest Promises inside Promises.

function fetchUser(id) { return Promise.resolve({ id, name: "Ana" }); }
function fetchOrders(userId) { return Promise.resolve([{ total: 20 }]); }

fetchUser(1)
  .then(user => fetchOrders(user.id))  // returns a Promise — the chain WAITS for it
  .then(orders => console.log(orders)); // orders is the ARRAY, not a Promise wrapping an array

This flattening behavior is what makes sequential async steps composable — without it, chains would produce nested Promise<Promise<Promise<value>>> structures.

3Returning a Plain Value — Automatically Wrapped

Promise.resolve(1)
  .then(n => n + 1)       // returning a plain number — automatically becomes Promise.resolve(2)
  .then(n => console.log(n)); // 2

Every .then() callback's return value — Promise or plain value — is normalized the same way: the next .then() in the chain always receives the unwrapped, resolved value either way.

4Error Propagation Skips Directly to the Next .catch()

Promise.resolve()
  .then(() => { throw new Error("step 1 failed"); })
  .then(() => console.log("step 2 — SKIPPED"))   // skipped — error propagates past it
  .then(() => console.log("step 3 — SKIPPED"))   // skipped too
  .catch(e => console.log("caught:", e.message))  // "caught: step 1 failed"
  .then(() => console.log("step 4 — runs, chain has recovered")); // runs — .catch() "handles" the error

Once an error occurs, every subsequent .then() is skipped until a .catch() (or a .then(onFulfilled, onRejected) with a rejection handler) is reached. After that handler runs (without re-throwing), the chain is considered "recovered" and continues normally.

5Placing .catch() Strategically

// ONE catch at the end — handles errors from ANY step above it
step1().then(step2).then(step3).catch(handleAnyError);

// Per-step catch — recovers locally, chain continues with a fallback value
step1()
  .then(step2)
  .catch(err => {
    console.log("step2 failed, using fallback");
    return fallbackValue; // chain continues as if step2 had succeeded with this value
  })
  .then(step3);

6Chaining vs Nesting — the Anti-Pattern to Avoid

// BAD — nested .then() inside .then(), reintroducing "callback hell" with Promises
fetchUser(1).then(user => {
  fetchOrders(user.id).then(orders => {
    fetchOrderDetails(orders[0].id).then(details => {
      console.log(details);
    });
  });
});

// GOOD — flat chain, each step returns a Promise for the next .then() to pick up
fetchUser(1)
  .then(user => fetchOrders(user.id))
  .then(orders => fetchOrderDetails(orders[0].id))
  .then(details => console.log(details));

If you find yourself nesting .then() calls, you almost always meant to return the inner Promise and chain it flatly instead.

const fakePromiseLike = {
  then(onFulfilled, onRejected) {
    setTimeout(() => onFulfilled("resolved from a thenable"), 100);
  },
};

Promise.resolve(1)
  .then(() => fakePromiseLike) // NOT a real Promise instance — just an object with .then()
  .then(value => console.log(value)); // "resolved from a thenable" — flattening still works

⚠️ Common Pitfalls

1. Forgetting to return inside a .then() — if a callback doesn't return the inner Promise (or value), the next .then() receives undefined instead of waiting for it.
2. Nesting instead of chaining — reproduces callback hell inside Promise syntax; always flatten by returning the inner Promise.
3. Missing a final .catch() — an unhandled rejection anywhere in the chain will silently vanish (or trigger an unhandledRejection warning) if nothing downstream catches it.
4. Assuming a .catch() mid-chain stops everything — it only stops error propagation; execution continues normally with whatever the .catch() handler returns.

📋 Quick Reference

.then(fn) returns a new Promise
returning a Promise from .then() → chain waits and flattens automatically
returning a plain value → wrapped automatically
throw inside .then() → skips to nearest .catch()
.catch() that doesn't re-throw → chain "recovers," continues normally

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

Source: js_promise_chaining_theory.md · generated by tools/build_lessons.py