Skip to content

Promises in Depth

Promise states, chaining, error propagation, and combinators like Promise.all and Promise.race.

What you'll learn

  • The three promise states: pending, fulfilled, rejected
  • Chaining with then and transforming values
  • Error propagation and catch across a chain
  • Combinators: Promise.all, Promise.race, Promise.allSettled, Promise.any
  • Creating promises from scratch with the executor function

Concept

Promise States

A promise is an object representing a future result. It is always in one of three states: pending (the operation has not finished), fulfilled (it succeeded with a value), or rejected (it failed with a reason). Once a promise settles (fulfills or rejects), it is immutable — it will never change state again. This is what makes promises safer than callbacks, which can be called multiple times by mistake.

Chaining with then

.then(onFulfilled, onRejected) returns a new promise that resolves with whatever the handler returns. This lets you chain transformations: each then takes the previous value and produces the next. If a handler returns a promise, the chain waits for it to settle before continuing — this is how you sequence async steps without nesting.

Error Propagation

A rejected promise skips forward to the next catch (or the onRejected handler). Errors propagate down the chain like exceptions in a try/catch. A single catch at the end can handle errors from any step above. finally() runs regardless of outcome and is useful for cleanup, but it does not receive the value or reason.

Combinators

Promise.all waits for all promises and rejects if any one rejects — use it for parallel work where all must succeed. Promise.allSettled waits for all and never rejects; it gives you an array of {status, value/reason} results — ideal when you want partial success. Promise.race settles with the first promise to settle (fulfill or reject). Promise.any (ES2021) fulfills with the first to fulfill, ignoring rejections unless all reject.

The Executor

You create a promise with new Promise((resolve, reject) => { ... }). The executor runs synchronously and calls resolve(value) or reject(reason) when the work is done. Call resolve/reject exactly once — subsequent calls are ignored. Throw inside the executor to reject automatically.

Example

              // Creating a promise from scratch
function delay(ms, value) {
  return new Promise((resolve) => setTimeout(() => resolve(value), ms));
}

// Chaining: each then transforms the value
delay(100, 10)
  .then((n) => n * 2)        // 20
  .then((n) => n + 5)        // 25
  .then((n) => console.log("chained:", n));

// Error propagation across a chain
function risky(x) {
  return new Promise((resolve, reject) => {
    if (x < 0) reject(new Error("negative input"));
    else resolve(Math.sqrt(x));
  });
}
risky(-1)
  .then((r) => console.log("root:", r))
  .catch((e) => console.log("caught:", e.message)) // "negative input"
  .finally(() => console.log("done"));

// Promise.all — parallel, all must succeed
async function loadAll() {
  const [a, b, c] = await Promise.all([
    delay(100, "A"),
    delay(150, "B"),
    delay(50, "C"),
  ]);
  console.log("all:", a, b, c); // waits ~150ms
}
loadAll();

// Promise.allSettled — partial success, never rejects
async function loadBestEffort() {
  const results = await Promise.allSettled([
    delay(100, "ok"),
    Promise.reject(new Error("fail")),
  ]);
  results.forEach((r) =>
    console.log(r.status, r.value ?? r.reason?.message)
  );
}
loadBestEffort();
            

Shows creating a promise with an executor, chaining transformations, error propagation with catch and finally, Promise.all for parallel success, and Promise.allSettled for partial-success handling.

Try it

Common mistakes

The mistake

Creating a promise chain that swallows errors because catch is missing

The fix

Unhandled rejections can crash Node.js or log warnings in browsers. Always end a chain with .catch() or use async/await with try/catch. In Node, listen for process.on('unhandledRejection').

The mistake

Using Promise.all when some requests may legitimately fail

The fix

Promise.all rejects if any single promise rejects, losing the successful results. Use Promise.allSettled to get every result with a status field, then filter or handle failures individually.

Related Cheatsheets

Look up unfamiliar terms

A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.

View glossary

Build real projects

Apply what you learned by building guided projects with starter code and solutions.

View projects

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors