JavaScript Promises

A Promise is an object representing the eventual result of an asynchronous operation — something that hasn't finished yet, like a network request, a file read, or a timer. Before Promises, asynchronous code relied on nested callbacks, which became difficult to read and error-prone as operations chained together ("callback hell").

A Promise gives asynchronous code a predictable shape: it starts in one state and settles into exactly one of two final states, and you attach handlers that run once that settlement happens.

Why it matters

Anything that takes time in JavaScript, such as a network request, a timer or reading a file, gives back a promise: an object standing for a result that is not ready yet. Promises replaced deeply nested callbacks, and async and await are built directly on top of them, so they cannot be skipped.

The Three States

Every Promise is in exactly one of three states at any moment.

• Pending — the initial state; the operation hasn't completed yet.
• Fulfilled — the operation completed successfully, producing a value.
• Rejected — the operation failed, producing a reason (usually an Error).

.then, .catch, and .finally

.then(onFulfilled, onRejected) registers callbacks for success and (optionally) failure. .catch(onRejected) is shorthand for .then(undefined, onRejected) and is the conventional way to handle errors at the end of a chain. .finally(callback) runs regardless of whether the Promise fulfilled or rejected, useful for cleanup like hiding a loading spinner. Because .then() always returns a new Promise, these calls chain together, and each .then() receives the value returned by the previous one.

Combining Promises with Promise.all

Promise.all(iterable) takes an array of Promises and returns a single Promise that fulfills with an array of all their results, but only once every input Promise has fulfilled — and it rejects immediately if any single one rejects. This is the standard tool for running independent async operations in parallel rather than awaiting them one at a time. Related methods include Promise.allSettled() (waits for all, never rejects, reports each outcome) and Promise.race() (settles as soon as the first input settles).

Examples

function fetchUserAge(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id === 1) {
        resolve(28);
      } else {
        reject(new Error('User not found'));
      }
    }, 100);
  });
}

fetchUserAge(1)
  .then((age) => {
    console.log('Age is', age);
    return age * 2;
  })
  .then((doubled) => console.log('Doubled:', doubled))
  .catch((err) => console.error('Failed:', err.message))
  .finally(() => console.log('Request finished'));

Age is 28
Doubled: 56
Request finished

const delay = (value, ms) =>
  new Promise((resolve) => setTimeout(() => resolve(value), ms));

Promise.all([delay('users', 50), delay('posts', 30), delay('comments', 10)])
  .then((results) => console.log(results))
  .catch((err) => console.error(err));

[ 'users', 'posts', 'comments' ]

Exercise

Write delay, which returns a promise that resolves with the given value after the given number of milliseconds. The code below then handles a rejected promise with catch and finally, and waits for two delays together with Promise.all.

Expected output: boom, done, ab (one per line)

function delay(ms, value) {
  // TODO: return a promise that resolves with value after ms milliseconds
}

Promise.reject(new Error("boom"))
  .catch((error) => console.log(error.message))
  .finally(() => console.log("done"));

Promise.all([delay(20, "a"), delay(10, "b")])
  .then((values) => console.log(values.join("")));

function delay(ms, value) {
  return new Promise((resolve) => {
    setTimeout(() => resolve(value), ms);
  });
}

Promise.reject(new Error("boom"))
  .catch((error) => console.log(error.message))
  .finally(() => console.log("done"));

Promise.all([delay(20, "a"), delay(10, "b")])
  .then((values) => console.log(values.join("")));

Quick quiz

Interview questions