What States Can a Promise Have?

A promise starts in the pending state. It then settles, and settling means moving to exactly one of two final states: fulfilled if it was resolved with a value, or rejected if it was rejected with a reason. Once it has settled it stays in that state forever.

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

promise.then((value) => console.log("fulfilled:", value));
promise.catch((err) => console.log("rejected:", err.message));

// A rejected promise.
const failing = new Promise((resolve, reject) => {
  reject(new Error("boom"));
});

failing.catch((err) => console.log("caught:", err.message));

The executor function runs immediately and synchronously when the promise is created. That means anything before the first await or before the runtime gets control is not asynchronous, and a long synchronous computation inside the executor blocks the thread just like any other code.

You observe the states with the then method, which takes a success handler and an optional failure handler, and with the catch method, which is just then with the success handler omitted. There is also a finally method, which runs its callback whatever happened, and which is the right place for cleanup such as hiding a loading spinner.

Two details about the handlers. The success handler receives the resolved value, but if that value is itself a promise, the promise machinery waits for it and hands you the inner value instead, which is called unwrapping. And handlers registered with then never run immediately; they are queued as microtasks, so even an already settled promise calls its handler a little later.

Nothing happens. A promise settles exactly once, and every later call to resolve or reject is ignored. The first settlement wins and the promise is locked in that state.

const p = new Promise((resolve, reject) => {
  resolve("first");
  resolve("second");
  reject(new Error("too late"));
});

p.then((value) => console.log("value:", value));   // "first"
p.catch((err) => console.log("never printed", err.message));

// The same with async and await.
async function demo() {
  const settled = await p;
  console.log("awaited:", settled);   // "first"
}

demo();

This is a safety feature rather than an accident. The executor is often given to code you do not control, and if a buggy implementation called the callback twice, the second call would have no way to change what consumers already saw. Locking the promise means the value every observer sees is the value the first settlement produced.

It also means the reverse case is safe. If a function throws after it has already resolved, the rejection is swallowed rather than surfacing as an unhandled error. That is convenient, but it can hide a real bug, so it is worth knowing that a throw inside an executor after a resolve will not be reported.

One related subtlety worth raising. If you resolve a promise with another promise, the outer promise waits for the inner one and adopts its state, including its rejection. That means a promise that resolves with a rejected promise ends up rejected, which is the mechanism that makes returning a promise from an async function work correctly.

You can create one promise in each state and observe them with the same handler shape. The allSettled helper is a neat way to look at several promises at once and see the status of each.

const states = [];

const pending = new Promise(() => {
  // The executor never resolves or rejects, so it stays pending.
});

const fulfilled = Promise.resolve("value");
const rejected = Promise.reject(new Error("nope"));

pending.then((v) => states.push("pending resolved: " + v));
fulfilled.then((v) => states.push("fulfilled: " + v));
rejected.catch((e) => states.push("rejected: " + e.message));

Promise.allSettled([fulfilled, rejected]).then((results) => {
  console.log(results.map((r) => r.status));   // ["fulfilled", "rejected"]
  console.log(states);
});

Notice that the pending promise in the example never settles, because the executor does not call resolve or reject. That is the normal state of a promise that is waiting for something, and it is also the state a promise is in for the whole of its synchronous setup.

The states array shows the order the handlers ran in. All three handlers were attached at the same time, but the pending one never fires, and the other two both run as microtasks after the current script finishes. The allSettled call also reports the status of each promise without waiting for the pending one, because only the two settled promises were passed to it.

A useful piece of vocabulary for an interview: a promise that has settled is called settled, and the word pending covers everything before that. There is no separate state for a promise that has been cancelled, because JavaScript has no built-in cancellation. To cancel work, you use an abort signal, which the underlying API decides how to honour.