Promise Internals and Chaining

The Chain That Broke

A developer writes this and expects sequential API calls:

getUser(id)
  .then(user => {
    getOrders(user.id)
      .then(orders => {
        getShipping(orders[0].id)
          .then(shipping => console.log(shipping));
      });
  })
  .catch(err => console.error(err));

When getOrders fails, the .catch doesn't fire. The error is silently swallowed. The developer is confused — "but I have a catch at the end!"

The problem: this isn't a chain. It's nested promises. The .catch is attached to the promise from getUser, not the inner promises. Understanding why requires understanding how promises actually work.

The Mental Model

The Promise State Machine

Every promise has:

1. State: pending, fulfilled, or rejected
2. Value: the fulfillment value or rejection reason (only set when settled)
3. Reaction queue: a list of callbacks waiting for this promise to settle

           resolve(value)
pending ──────────────────→ fulfilled
    │                           │
    │   reject(reason)          │  .then(onFulfilled)
    └──────────────────→ rejected
                                │  .then(_, onRejected)
                                │  .catch(onRejected)

When you call .then() on a pending promise, the callbacks are stored in the reaction queue. When the promise settles, all queued reactions fire as microtasks. When you call .then() on an already-settled promise, the callback is scheduled as a microtask immediately.

const p = new Promise((resolve) => {
  // Promise is pending right now
  setTimeout(() => resolve('done'), 1000);
});

// Reaction stored in queue — promise is still pending
p.then(val => console.log(val));

// Even after settling, .then works — schedules immediately as microtask
setTimeout(() => {
  p.then(val => console.log('late:', val));
}, 2000);

.then() Returns a NEW Promise

This is the single most important thing to understand about promise chaining. Every .then() call creates and returns a brand new promise. The value of that new promise depends on what the .then() callback returns:

const p1 = Promise.resolve(1);

const p2 = p1.then(val => val * 2);
// p2 is a NEW promise that will fulfill with 2

const p3 = p2.then(val => val * 3);
// p3 is a NEW promise that will fulfill with 6

console.log(p1 === p2); // false
console.log(p2 === p3); // false

The Resolution Rules

What happens to the promise returned by .then() depends on its callback's return value:

// Returns a value → next .then gets it
Promise.resolve(1)
  .then(x => x + 1)        // returns 2
  .then(x => console.log(x)); // logs 2

// Returns a promise → next .then waits for it
Promise.resolve(1)
  .then(x => fetch('/api'))  // returns a Promise<Response>
  .then(res => res.json())   // waits for fetch, gets Response
  .then(data => console.log(data));

// Throws → skips to .catch
Promise.resolve(1)
  .then(x => { throw new Error('fail'); })
  .then(x => console.log('skipped'))  // skipped!
  .catch(err => console.log(err.message)); // 'fail'

Chaining vs. Nesting: The Critical Difference

This is the part that causes the most real-world bugs. Let's compare the two patterns side by side.

Chaining (correct):

getUser(id)
  .then(user => getOrders(user.id))     // returns the promise
  .then(orders => getShipping(orders[0].id)) // returns the promise
  .then(shipping => console.log(shipping))
  .catch(err => console.error(err));    // catches ANY error above

Nesting (broken error handling):

getUser(id)
  .then(user => {
    getOrders(user.id)              // promise NOT returned
      .then(orders => {
        getShipping(orders[0].id)   // promise NOT returned
          .then(shipping => console.log(shipping));
      });
  })
  .catch(err => console.error(err)); // only catches getUser errors!

The nested version creates disconnected promise trees. Each inner .then() creates a new promise chain that has no connection to the outer .catch(). Errors in getOrders or getShipping are silently swallowed.

The chained version works because each .then() returns the inner promise, which the outer chain waits for. A rejection anywhere propagates down the single chain to the .catch().

Promise Resolution Procedure (The Algorithm)

Now let's go deeper. When a promise resolves with a value, the engine runs the Promise Resolution Procedure (Promises/A+ spec, section 2.3):

resolvePromise(promise, x):
  1. If x is the same object as promise → reject with TypeError (prevent cycles)
  2. If x is a Promise → adopt its state (follow it)
  3. If x is an object or function with a .then method ("thenable"):
     a. Call x.then(resolvePromise, rejectPromise)
     b. Only the first call to resolve/reject counts
  4. If x is any other value → fulfill with x

Step 3 is why you can return any "thenable" from .then(), not just native Promises. Libraries like Bluebird, jQuery Deferred, and even custom objects with a .then method all work with native promise chains.

// Custom thenable — works with native promises
const customThenable = {
  then(resolve, reject) {
    setTimeout(() => resolve(42), 100);
  }
};

Promise.resolve()
  .then(() => customThenable)
  .then(val => console.log(val)); // 42 (after 100ms)

Production Scenario: The Error Black Hole

This one's a classic. A production service processes webhook events. Each handler returns a promise:

// The bug: errors in handleEvent are swallowed
app.post('/webhook', (req, res) => {
  handleEvent(req.body); // returns a promise — but nobody awaits it!
  res.status(200).send('OK');
});

async function handleEvent(event) {
  const user = await getUser(event.userId); // might throw
  await updateRecord(user, event);          // might throw
  await sendNotification(user);             // might throw
}

handleEvent returns a promise, but the route handler doesn't await it or attach a .catch(). If any step throws, the rejection is unhandled. In Node.js, this triggers unhandledRejection and can crash the process (default behavior since Node.js 15).

The fix:

app.post('/webhook', async (req, res) => {
  try {
    await handleEvent(req.body);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook processing failed:', err);
    res.status(500).send('Error');
  }
});

Or if you intentionally fire-and-forget, handle the error explicitly:

app.post('/webhook', (req, res) => {
  handleEvent(req.body).catch(err => {
    console.error('Background processing failed:', err);
  });
  res.status(200).send('OK'); // respond immediately
});

Common Mistakes

Challenge: Promise Chain Resolution

Challenge: What Does the Chain Produce?

Predict the output, then step through to verify:

Key insight: .catch() is not the end of the chain. It returns a new promise. If the catch callback returns a value (doesn't throw), the chain recovers and subsequent .then() handlers run with the returned value.

Key Rules