Chapter 3 — Promises in Real Code

The state machine, floating promises, lost errors, and choosing a combinator

Prerequisites: Chapter 1 (microtasks), Chapter 2 (what promises replaced), FE-10 Part 8 (what a promise object is). Practice: the gym, exercises 06-cache-layer and 10-polyfill-kata.

How to Read This Chapter

A promise fixes the callback bugs from Chapter 2 by design: it settles once, and its handlers never run synchronously. What it adds are bugs of disconnection. A promise that nobody returns, nobody awaits, or nobody catches still runs, still fails, and in Node 15+ still kills the process. Most promise bugs in review come down to one question: is this promise connected to the chain that the caller is waiting on?

The chapter ends with a full Promises/A+ implementation. Writing one is a common interview round, and it is also the fastest way to make the rules in Parts 1–7 feel obvious.

Part 1: The State Machine

The "following" state is what the spec calls resolved but pending. It explains three behaviours you will be asked about:

• new Promise((resolve) => resolve(Promise.reject(err))) rejects. resolve does not mean "fulfil". It means "lock in to this", and it locked in to a rejection.
• After resolve(p) is called, later calls to resolve or reject are ignored, even though the promise is still pending.
• Resolving with a thenable costs extra microtask hops, because the promise has to call thenable.then in a job of its own (Chapter 1, Part 2).

Each .then(onFulfilled, onRejected) returns a new promise. That new promise is decided by what the handler does:

That last row is how one .catch at the end of a chain catches a rejection from any step above it: each .then without a rejection handler passes the rejection down.

Part 2: The .then That Forgets to return

function chargeForStory(userId, cost) {
  return db.getWallet(userId)
    .then((wallet) => {
      db.charge(wallet, cost);       // starts the charge, returns nothing
    })
    .then(() => res.json({ status: 'charged' }));
}

The braces turn the arrow function into a block body, so it returns undefined. The second .then fulfils at once, and the charge runs detached from the chain. Run in Node with a fake 20 ms charge:

cost 30:
  route: sending 200 "charged"
  db: charged 30
cost 500:
  route: sending 200 "charged"
  unhandledRejection: insufficient

The fix is one word, and the reason is the table in Part 1: return the inner promise so the next step follows it.

.then((wallet) => db.charge(wallet, cost))     // concise body returns the promise

The same bug inside async code is a missing await (Chapter 4). The lint rule that catches both is @typescript-eslint/no-floating-promises; in plain JS projects, look for .then( with a { body and no return.

Part 3: The Explicit-Construction Antipattern

function getUser(id) {
  return new Promise((resolve, reject) => {
    fetchUser(id).then((user) => resolve(normalize(user)));
  });
}

This wraps a promise in a new promise for no reason, and it breaks error handling twice:

1. If fetchUser rejects, nothing calls reject. The outer promise stays pending forever, and the inner rejection is unhandled.
2. If normalize throws, it throws inside a .then handler, which rejects the inner chain, not the outer promise. Same result: pending forever plus an unhandled rejection. (Verified: with normalize throwing on a null name, getUser(1) was still pending 100 ms later and Node reported the TypeError as unhandled.)

The executor's built-in try/catch does not help, because both failures happen after the executor returned. The fix is to return the chain you already have:

function getUser(id) {
  return fetchUser(id).then(normalize);
}
// or
async function getUser(id) {
  return normalize(await fetchUser(id));
}

new Promise is for wrapping things that are not promises: callback APIs, events, timers. If the executor's body calls a function that already returns a promise, that is the antipattern.

Part 4: Swallowed Errors and Where .catch Goes

Two placements look equivalent and are not:

op().then(onOk, onFail);          // onFail handles op() failing only
op().then(onOk).catch(onFail);    // onFail handles op() failing OR onOk throwing

With op resolving { items: null } and onOk reading r.items.length: in the first form the TypeError from onOk escapes onFail and goes to whatever is next. In the second, onFail sees it.

The more common bug is a .catch that logs and carries on:

op()
  .then((r) => r.items.length)
  .catch((err) => { log.error(err); })     // returns undefined → fulfilled
  .then((count) => billing.record(count)); // runs with count = undefined

A .catch handler is an ordinary handler: if it returns normally, the chain recovers. Code after it runs as if nothing failed, with undefined. Decide which of three things you mean, and write that:

Where to put the final .catch: at the boundary that can do something about the failure. That is the route handler that turns it into a 500, the job runner that marks the job failed, the UI that shows an error. Catching in the middle of a chain is right only when that step has a real fallback.

Part 5: Unhandled Rejections

When a promise rejects and has no handler, the host notices. What it does differs:

The timing matters. Node checks after the microtask queue drains. A handler attached later in the same drain is fine; a handler attached in a later task is too late:

const p = Promise.reject(new Error('provider 503'));
await null;
await null;
p.catch((e) => console.log('caught:', e.message));   // fine: same drain

const q = Promise.reject(new Error('provider 503'));
setTimeout(() => q.catch(() => {}), 0);               // too late: the process has already exited

The pattern that hits this in real code is starting two operations and awaiting them one by one:

async function buildDashboard(userId) {
  const profileP = getProfile(userId);   // 50 ms
  const usageP = getUsage(userId);       // fails after 10 ms
  try {
    const profile = await profileP;
    const usage = await usageP;
    return { profile, usage };
  } catch (err) {
    return { error: 'dashboard unavailable' };
  }
}

Fix with await Promise.all([profileP, usageP]), or allSettled if a partial dashboard is acceptable.

What a process-level handler should do: log and exit, not swallow. process.on('unhandledRejection', (err) => { log.fatal(err); process.exit(1); }) adds logging; a handler that only logs turns crashes into silent corruption. Chapter 8 covers shutdown.

Part 6: finally Semantics

p.finally(fn) is for cleanup. It is not p.then(fn, fn):

The waiting row is a feature: .finally(() => client.release()) holds the chain until the connection is back in the pool. The throwing row is a trap: if release() throws, it replaces the original error, and the log shows "release failed" instead of the query error that caused it.

try/finally inside an async function follows ordinary JS rules, which differ: a return inside finally overrides the try's return value or thrown error. async () => { try { return 'try'; } finally { return 'finally'; } } resolves with 'finally'. Never return from a finally block.

Part 7: Thenables and Assimilation

Any object with a then method is treated as a promise by Promise.resolve, await, return from an async function, and every combinator.

const t = { then(resolve) { console.log('then() called'); resolve(42); } };
Promise.resolve(t).then((v) => console.log('assimilated', v));
console.log('sync end');
// sync end, then() called, assimilated 42

The then method is called in a later microtask, never synchronously. The rules for a thenable are defensive, because it may be badly written:

• Only the first call to resolve or reject counts.
• A throw from then after it called resolve is ignored.
• The then property is read once, because it may be a getter with side effects.
• Promise.resolve(p) === p when p is already a native promise; no new wrapper.

The review bug is accidental thenables. Query builders such as Knex and Mongoose queries are thenables on purpose: awaiting the builder runs the query. Returning a builder from an async function therefore runs it:

async function queuedJobsQuery() {
  return knex('jobs').where({ status: 'queued' });   // caller wanted a builder to add .limit()
}
const q = await queuedJobsQuery();   // q is the rows; the query already ran without a limit

The same happens with any class that grows a then method, or a module that exports a function named then, which changes what await import() returns. To hand back a thenable unexecuted, wrap it: return { query: knex('jobs') }.

Part 8: Choosing a Combinator

Edge cases interviewers check: all([]) fulfils with []; allSettled([]) fulfils with []; any([]) rejects with an AggregateError whose errors is empty; race([]) stays pending forever. Non-promise items are treated as already fulfilled, so race([slowPromise, 'plain']) returns 'plain'.

AggregateError has an errors array in input order, not in the order they failed. For a provider failover with any, log every entry: "All promises were rejected" alone tells you nothing.

No combinator cancels anything. When Promise.all rejects, the other operations keep running and their results are thrown away. When race picks a winner, the loser keeps running. (Verified: after all rejected at 10 ms, the 50 ms operation still finished.) For LLM calls, that means you still pay for the losing request. Pass an AbortSignal and abort the losers (Chapter 6).

Promise.withResolvers() (Node 22, all current browsers) returns { promise, resolve, reject }, for when the code that settles a promise is not inside its executor: resolve a waiting request from a webhook handler, or build a queue whose consumers wait on a promise that producers resolve.

const waiting = new Map();   // jobId -> resolve

export function waitForRender(jobId) {
  const { promise, resolve } = Promise.withResolvers();
  waiting.set(jobId, resolve);
  return promise;            // add a timeout in real code; see Spot the Bug, Drill 2
}

app.post('/webhooks/render', (req, res) => {
  waiting.get(req.body.jobId)?.(req.body);
  waiting.delete(req.body.jobId);
  res.sendStatus(204);
});

Spot the Bug

Drill 1: the embedding cache

const embeddings = new Map();   // text -> Promise<number[]>

export function getEmbedding(text) {
  if (!embeddings.has(text)) {
    embeddings.set(text, provider.embed(text));
  }
  return embeddings.get(text);
}

Caching the promise, not the value, is deliberate: two concurrent callers share one provider call. What's wrong?

export function getEmbedding(text) {
  let p = embeddings.get(text);
  if (!p) {
    p = provider.embed(text);
    embeddings.set(text, p);
    p.catch(() => {
      if (embeddings.get(text) === p) embeddings.delete(text);
    });
  }
  return p;
}

Drill 2: the timeout helper

export function withTimeout(promise, ms) {
  return Promise.race([
    promise,
    new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), ms)),
  ]);
}

// used as
const reply = await withTimeout(llm.complete(prompt), 30_000);

What's wrong? There are two problems.

export function withTimeout(promise, ms) {
  let timer;
  const timeout = new Promise((_, reject) => {
    timer = setTimeout(() => reject(new Error(`timed out after ${ms} ms`)), ms);
  });
  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
}

// better: let the operation itself stop
const reply = await llm.complete(prompt, { signal: AbortSignal.timeout(30_000) });

Drill 3: the provider wrapper

function callProvider(prompt) {
  return openai.complete(prompt)
    .catch((err) => {
      log.warn('openai failed, will fall back', err);
    })
    .then((res) => res.text);
}

export async function answer(prompt) {
  try {
    return await callProvider(prompt);
  } catch (err) {
    return anthropicFallback(prompt, err);
  }
}

The failover "works", but the on-call engineer sees TypeError: Cannot read properties of undefined (reading 'text') in every incident and never the real provider error. What's wrong?

function callProvider(prompt) {
  return openai.complete(prompt).then((res) => res.text);
}

Drill 4: what happens?

const results = [];
const p = new Promise((resolve, reject) => {
  resolve(Promise.reject(new Error('A')));
  resolve('B');
  reject(new Error('C'));
});
p.then((v) => results.push(v), (e) => results.push(e.message))
  .finally(() => results.push('done'))
  .then(() => console.log(results));

Build It: MyPromise, Promises/A+ Style

Spec.

• new MyPromise(executor) calls executor(resolve, reject) synchronously. A throw from the executor rejects, unless resolve or reject was already called.
• Only the first call to resolve or reject counts.
• resolve(x) runs the resolution procedure: x === this rejects with a TypeError; an object or function with a callable then is adopted (read then once; the first of its callbacks wins; a throw after a callback is ignored); anything else fulfils.
• then(onFulfilled, onRejected) returns a new promise. Handlers run in a later microtask (queueMicrotask), in registration order. A missing handler passes the outcome through. A handler's return value goes through the resolution procedure; a throw rejects.
• catch, finally (with the semantics in Part 6), MyPromise.resolve, MyPromise.reject.
• all, allSettled, race, any accept any iterable, keep input order, and treat non-promises as fulfilled values.

const PENDING = 'pending';
const FULFILLED = 'fulfilled';
const REJECTED = 'rejected';

export class MyPromise {
  #state = PENDING;
  #value = undefined;
  #reactions = []; // handlers registered while pending

  constructor(executor) {
    if (typeof executor !== 'function') {
      throw new TypeError('MyPromise executor must be a function');
    }
    const { resolve, reject } = this.#createResolvingFunctions();
    try {
      executor(resolve, reject);
    } catch (err) {
      reject(err); // ignored if resolve/reject already ran
    }
  }

  // A resolve/reject pair that shares one "already resolved" flag.
  // Only the first call of either function counts.
  #createResolvingFunctions() {
    let alreadyResolved = false;
    return {
      resolve: (x) => {
        if (alreadyResolved) return;
        alreadyResolved = true;
        this.#resolveWith(x);
      },
      reject: (reason) => {
        if (alreadyResolved) return;
        alreadyResolved = true;
        this.#settle(REJECTED, reason);
      },
    };
  }

  // The Promise Resolution Procedure: [[Resolve]](promise, x)
  #resolveWith(x) {
    if (x === this) {
      this.#settle(REJECTED, new TypeError('Chaining cycle detected for promise'));
      return;
    }
    if (x !== null && (typeof x === 'object' || typeof x === 'function')) {
      let then;
      try {
        then = x.then; // read exactly once: it may be a getter
      } catch (err) {
        this.#settle(REJECTED, err);
        return;
      }
      if (typeof then === 'function') {
        // Adopt the thenable's eventual state. A fresh pair: the thenable
        // may call them several times or throw after calling one.
        const { resolve, reject } = this.#createResolvingFunctions();
        try {
          then.call(x, resolve, reject);
        } catch (err) {
          reject(err);
        }
        return;
      }
    }
    this.#settle(FULFILLED, x);
  }

  #settle(state, value) {
    if (this.#state !== PENDING) return;
    this.#state = state;
    this.#value = value;
    const reactions = this.#reactions;
    this.#reactions = [];
    for (const reaction of reactions) this.#runLater(reaction);
  }

  // Handlers always run in a later microtask, never synchronously.
  #runLater({ onFulfilled, onRejected, resolve, reject }) {
    queueMicrotask(() => {
      const fulfilled = this.#state === FULFILLED;
      const handler = fulfilled ? onFulfilled : onRejected;
      if (typeof handler !== 'function') {
        // No handler for this outcome: pass it down the chain unchanged.
        if (fulfilled) resolve(this.#value);
        else reject(this.#value);
        return;
      }
      let result;
      try {
        result = handler(this.#value);
      } catch (err) {
        reject(err);
        return;
      }
      resolve(result); // runs the resolution procedure on the next promise
    });
  }

  then(onFulfilled, onRejected) {
    return new MyPromise((resolve, reject) => {
      const reaction = { onFulfilled, onRejected, resolve, reject };
      if (this.#state === PENDING) this.#reactions.push(reaction);
      else this.#runLater(reaction);
    });
  }

  catch(onRejected) {
    return this.then(undefined, onRejected);
  }

  finally(onFinally) {
    if (typeof onFinally !== 'function') return this.then(onFinally, onFinally);
    return this.then(
      (value) => MyPromise.resolve(onFinally()).then(() => value),
      (reason) => MyPromise.resolve(onFinally()).then(() => { throw reason; }),
    );
  }

  static resolve(x) {
    if (x instanceof MyPromise) return x;
    return new MyPromise((resolve) => resolve(x));
  }

  static reject(reason) {
    return new MyPromise((_, reject) => reject(reason));
  }

  static all(iterable) {
    return new MyPromise((resolve, reject) => {
      const results = [];
      let remaining = 0;
      let index = 0;
      for (const item of iterable) {
        const i = index++;
        remaining++;
        MyPromise.resolve(item).then((value) => {
          results[i] = value;
          if (--remaining === 0) resolve(results);
        }, reject);
      }
      if (remaining === 0) resolve(results); // empty input
    });
  }

  static allSettled(iterable) {
    return new MyPromise((resolve) => {
      const results = [];
      let remaining = 0;
      let index = 0;
      for (const item of iterable) {
        const i = index++;
        remaining++;
        MyPromise.resolve(item).then(
          (value) => {
            results[i] = { status: 'fulfilled', value };
            if (--remaining === 0) resolve(results);
          },
          (reason) => {
            results[i] = { status: 'rejected', reason };
            if (--remaining === 0) resolve(results);
          },
        );
      }
      if (remaining === 0) resolve(results);
    });
  }

  static race(iterable) {
    return new MyPromise((resolve, reject) => {
      for (const item of iterable) {
        MyPromise.resolve(item).then(resolve, reject);
      }
      // Empty input: stays pending forever, like the native one.
    });
  }

  static any(iterable) {
    return new MyPromise((resolve, reject) => {
      const errors = [];
      let remaining = 0;
      let index = 0;
      for (const item of iterable) {
        const i = index++;
        remaining++;
        MyPromise.resolve(item).then(resolve, (reason) => {
          errors[i] = reason;
          if (--remaining === 0) reject(new AggregateError(errors, 'All promises were rejected'));
        });
      }
      if (remaining === 0) reject(new AggregateError(errors, 'All promises were rejected'));
    });
  }
}

Edge cases interviewers check.

Known differences from native promises, worth saying out loud: this version calls a thenable's then synchronously inside resolve (Promises/A+ allows it; native promises defer it by one job, so ordering around thenables differs by a tick); it has no unhandled-rejection tracking; and it ignores subclassing (Symbol.species).

The Causal Chains

Review Checklist

1. .then((x) => { … }) with a block body and no return. The classic floating promise.
2. new Promise whose executor calls a promise-returning function. Replace with the chain.
3. .catch handlers that don't rethrow or return a real fallback. What does the next step receive?
4. .then(ok, fail) where fail is expected to cover errors from ok.
5. Promises started early and awaited later, one at a time. Each is an unhandled-rejection window.
6. process.on('unhandledRejection') handlers that log and continue.
7. finally handlers that can throw, and return inside a finally block.
8. Promise caches with no eviction on rejection.
9. Promise.race timeouts that never clear the timer or abort the loser.
10. Promise.all over work where partial success is acceptable (should be allSettled), or over unbounded arrays (should be a pool, Chapter 7).

What's Next

async/await is promises with nicer syntax, and it keeps every rule in this chapter while hiding most of them. Chapter 4 — async/await Traps covers the missing await, forEach with async, sequential awaits that should be parallel, and return vs return await.