Promises

Promises are order tokens

The Callbacks lesson introduced a problem: when work finishes later, we often pass a function and hope someone calls it correctly. A promise gives that future result a stable object. Instead of handing away all control, your code receives a value now and attaches instructions to it.

This lesson stays focused on a single promise and a single set of handlers. The next lesson, Promise chaining, shows how returned values and returned promises connect multiple steps.

A promise is always in exactly one state. It begins pending. From pending, it may fulfill with a value, or reject with a reason. The shared word for fulfilled and rejected is settled.

The most important state rule is one-way movement. Once a promise is fulfilled or rejected, extra calls to resolve or reject do nothing. That one-time behavior is what makes late handlers safe: they all observe the same remembered result.

You create a custom promise with new Promise. The constructor receives an executor function. JavaScript calls that executor with two functions: resolve for success and reject for failure.

1const order = new Promise((resolve, reject) => {2  setTimeout(() => {3    if (outcome === "fulfill") resolve("order ready");4    else reject("sold out");5  }, delay);6});7 8order9  .then((value) => log("then: " + value))10  .catch((reason) => log("catch: " + reason))11  .finally(() => log("finally: throw away the receipt"));

The playground runs real promises in the browser. Choose “Resolve, then try reject” and notice the log: the first result wins. The later attempt is ignored because the promise has already settled.

Promise.resolve("already ready")
  .then((value) => console.log(value));

Promise.reject("already failed")
  .catch((reason) => console.log(reason));

Promise.resolve(value) and Promise.reject(reason) are shortcuts for promises that are already settled. They are useful in tests, examples, and code that wants to return a promise-shaped result even when the answer is known immediately.

Handlers are instructions attached to the order promise. then handles fulfillment, catch handles rejection, and finally handles cleanup either way.

1Promise.resolve("noodles")Run2  .finally(() => {3    console.log("finally: wipe counter");4  })5  .then((value) => {6    console.log("then: " + value);7  });

The finally callback above does not receive "noodles". It simply logs cleanup and lets the original value continue to the next then. If a finally callback throws, that new error takes over; the Error handling with promises lesson focuses on those paths.

A common misconception is that then starts a promise. It does not. The executor starts during new Promise. The callback passed to then runs later, as a microtask, after the current script finishes. The Event loop and Microtasks in depth lessons build the full scheduling model; this lesson uses the rule.

1console.log("before new Promise");Run2const order = new Promise((resolve) => {3  console.log("executor: kitchen starts");4  resolve("tacos");5});6console.log("after new Promise");7order.then((value) => {8  console.log("then: " + value);9});

The token analogy is exact here: the kitchen starts cooking when you order, not when you look at your token. Attaching handlers is like deciding what to do when your number shows on the screen.

1const ready = Promise.resolve("tea");Run2console.log("A: cup ordered");3ready.then((value) => {4  console.log("B: then gets " + value);5});6console.log("C: keep walking");

Settled promises remember

A promise is not an event. If a click happens before you add a click listener, that old click is gone. If a promise fulfills before you add then, the promise remembers the value and still calls your handler later.

const remembered = Promise.resolve("receipt #42");

setTimeout(() => {
  remembered.then((value) => {
    console.log("late handler saw " + value);
  });
}, 10);

const order = new Promise((resolve, reject) => {
  resolve("ready");
  resolve("extra ready");
  reject("out of buns");
});

order.then(
  (value) => console.log("fulfilled: " + value),
  (reason) => console.log("rejected: " + reason),
);

That memory is one reason promises are easier to compose than plain callbacks. You can pass the promise object around without worrying that the result will disappear before a caller attaches a handler.

Where you’ll use promises

Promises appear whenever JavaScript needs to wait without freezing the page: timers, loading data, asking a user for permission, reading files in some environments, and many browser APIs. Later, async and await make promise code read more like normal top-to-bottom code, but promises are still underneath.

let loading = true;

loadMenu()
  .then((menu) => {
    renderMenu(menu);
  })
  .catch((error) => {
    showError(error);
  })
  .finally(() => {
    loading = false;
    hideSpinner();
  });

In real interfaces, finally is often where a loading flag turns off. The success path renders data. The failure path shows an error. Cleanup runs for both.

Common misconceptions

• “then starts the promise.” No. The executor already ran during new Promise.
• “Already fulfilled means the callback runs right now.” No. Promise handlers run later as microtasks.
• “resolve returns the value from the promise.” No. resolve settles the promise; handlers receive the value later.
• “A promise can be both fulfilled and rejected.” No. The first settle call wins forever.
• “finally is where I read the value.” No. finally receives no value; use then or catch.

Key takeaways

• A promise is an object for one future result.
• It starts pending and settles once: fulfilled with a value or rejected with a reason.
• new Promise runs its executor immediately; handlers run later as microtasks.
• then, catch, and finally describe success, failure, and cleanup.
• Settled promises remember their result, so handlers attached late still work.

A promise is JavaScript’s one-time order token for async work: pending now, fulfilled or rejected later, and safe to attach handlers to at any time.

Up next: Promise chaining.