How do promises work and what are their states?

A promise is a placeholder for a future value. The executor runs synchronously, but resolve and reject settle the promise asynchronously from the perspective of the code that consumes it.

const promise = new Promise((resolve, reject) => {
  setTimeout(() => resolve("done"), 100);
});

promise
  .then((value) => value.toUpperCase())
  .then((value) => console.log(value))
  .catch((error) => console.error(error))
  .finally(() => console.log("settled"));

The three states

• Pending: neither fulfilled nor rejected
• Fulfilled: settled with a value
• Rejected: settled with a reason, usually an Error
• Settled means fulfilled or rejected; it is not a fourth state

Once a promise settles, it cannot change. Calling resolve after reject has no effect. That immutability is what makes a promise safe to share.

Chaining

Each then returns a new promise. If the callback returns a value, the next promise fulfils with that value. If it returns a promise, the chain waits for it. If it throws, the next promise rejects and skips to the nearest catch.

Promise.resolve(2)
  .then((value) => value * 3)
  .then((value) => {
    throw new Error("stopped");
  })
  .then(() => console.log("not reached"))
  .catch((error) => console.log(error.message)); // "stopped"