Promises

Promises are order tokens

Some work finishes later, like a timer or loading data. In the Callbacks lesson, you handled this by passing a function to the work and waiting for it to be called. A promise is another way. The work gives you an object right away. Later, that object gets the result. You add your instructions to the object.

const coffee = Promise.resolve("tea");
coffee.then((drink) => console.log("Ready: " + drink));

Line 1 makes a promise that is already fulfilled with the value "tea". Line 2 uses then to add a handler: a function that runs when the promise has its value. The handler gets "tea" as drink and prints "Ready: tea".

This lesson uses one promise at a time, with its handlers. The next lesson, Promise chaining, shows how to join several steps one after another.

A promise is always in one of three states:

• Pending: there is no result yet. Every promise starts here.
• Fulfilled: the work succeeded. The promise holds a value.
• Rejected: the work failed. The promise holds a reason, often an Error.

Fulfilled and rejected share one name: settled. A settled promise has its final result.

const order = Promise.reject("sold out");

order.catch((reason) => {
  console.log("Could not serve: " + reason);
});

Line 1 makes a promise that is already rejected, with the reason "sold out". Line 3 adds a catch handler. catch runs when a promise is rejected, and it gets the reason. Line 4 puts the reason in a message, so the output is "Could not serve: sold out".

A rejected promise does not stop your script with an error on line 1. Rejected is just one of the promise's states. catch is the usual place to deal with the reason.

The table below has one row per state. Read each row as: "in this state, this is true, and this can happen next."

The most important rule: a promise settles only once. After it is fulfilled or rejected, more calls to resolve or reject do nothing. (You'll meet these two functions in the next section.) Because the result never changes, every handler sees the same result, even a handler added late.

To make your own promise, write new Promise(...) and pass it a function. This function is called the executor. JavaScript calls the executor right away and gives it two functions:

• resolve(value): call it when the work succeeds. The promise becomes fulfilled with value.
• reject(reason): call it when the work fails. The promise becomes rejected with reason.

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 a real promise in your browser. Pick "Resolve, then try reject" and press Order. The log shows that the first call wins. The later reject call is ignored, because the promise is already settled.

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

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

Promise.resolve(value) makes a promise that is already fulfilled with value. Promise.reject(reason) makes a promise that is already rejected with reason. These are shortcuts. They are handy in tests and small examples, and in functions that must return a promise even when the answer is known right away. This code prints already ready, then already failed.

const kitchen = new Promise((resolve) => {
  setTimeout(() => resolve("pizza ready"), 5);
});

const order = new Promise((resolve) => resolve(kitchen));
order.then((value) => console.log(value));

Lines 1 to 3 make a promise called kitchen. A timer fulfills it with "pizza ready" 5 milliseconds later. Line 5 makes a second promise, order, and calls resolve(kitchen). When you pass a promise to resolve, the outer promise waits for that inner promise and copies its result. So order does not get the kitchen object as its value. It gets "pizza ready", and line 6 prints pizza ready.

const order = new Promise(() => {
  throw new Error("oven is off");
});

order.catch((error) => console.log(error.message));

Line 2 throws an error inside the executor. JavaScript catches it and rejects the promise, with the error as the reason. On line 5, catch gets that error. It reads error.message and prints oven is off. So when your executor can fail, add a catch handler.

You add handlers to a promise with three methods:

• then runs when the promise is fulfilled. It gets the value.
• catch runs when the promise is rejected. It gets the reason.
• finally runs in both cases. It gets nothing. Use it to clean up, like hiding a loading spinner.

The table below compares the handlers. Read each row as: "this handler runs when this happens, and it gets this."

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

Step through the code above. The finally function does not get "noodles". It only prints its cleanup message. Then the value "noodles" passes on to the next then, which prints it. If a finally function throws an error, that error replaces the value. The lesson Error handling with promises covers that case.

Many people think then starts the promise's work. It does not. The executor runs during new Promise, right away. We say promises are eager: the work starts as soon as the promise is made.

A then function runs later. It waits until the current script has finished. Then it runs as a microtask: a small job that JavaScript runs as soon as the script is done. The Event loop and Microtasks in depth lessons explain this fully. Here, you only need the rule: normal lines first, promise handlers after.

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});

So adding a then handler does not start any work. The work started in the executor. The handler only says what to do with the result when it is ready.

The next example uses a promise that is already fulfilled. Its then handler still waits for the script to finish first.

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 different from an event like a click. If a click happens before you add a click listener, you miss that click. If a promise is fulfilled before you add then, the promise keeps the value. Your handler still runs and gets it.

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

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

Line 1 makes a promise that is already fulfilled with "receipt #42". Lines 3 to 7 wait 10 milliseconds, then add a then handler. The promise still has its value, so the handler prints late handler saw receipt #42.

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),
);

Line 2 calls resolve("ready") first, so the promise is fulfilled with "ready". Line 3 tries to resolve again, and line 4 tries to reject. Both are ignored. Line 8 prints fulfilled: ready, and the function on line 9 never runs.

Because a promise keeps its one result, you can pass the promise to other code. That code can add a handler at any time, and the result will still be there.

Where you’ll use promises

Promises show up whenever JavaScript must wait without freezing the page. For example:

• waiting for a timer
• loading data from a server
• asking the user for permission, like using the camera
• reading files, in some environments such as Node.js

Later you'll learn async and await. They let promise code read from top to bottom like normal code, but they still use promises.

let loading = true;

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

This is a common pattern in real pages. Line 1 sets loading to true. Then:

• If loadMenu() succeeds, then shows the menu (lines 4 to 6).
• If it fails, catch shows an error (lines 7 to 9).
• Either way, finally sets loading to false and hides the spinner (lines 10 to 13).

function fakeFetch() {
  return Promise.resolve({
    ok: true,
    json: () => Promise.resolve({ name: "Asha" }),
  });
}

let loading = true;
fakeFetch()
  .then((response) => response.json())
  .then((user) => console.log("Hello " + user.name))
  .catch(() => console.log("Could not load profile"))
  .finally(() => {
    loading = false;
    console.log("loading: " + loading);
  });

The real fetch function loads data from a server and returns a promise. This example uses a pretend version, fakeFetch, so it runs without a network. It works like this:

1. fakeFetch() returns a promise for a response object.
2. The first then calls response.json(), which returns another promise, for the data { name: "Asha" }.
3. The second then gets that data and prints Hello Asha.
4. If anything fails, catch prints Could not load profile.
5. Either way, finally prints loading: false.

Common misconceptions

• “then starts the promise.” No. The executor already ran during new Promise.
• “If the promise is already fulfilled, the handler runs right now.” No. Promise handlers always wait until the current script finishes.
• “resolve gives back the promise's value.” No. resolve settles the promise. Handlers get the value later.
• “A promise can be fulfilled and then rejected.” No. The first call to resolve or reject decides the result forever.
• “finally is where I read the value.” No. finally gets nothing. Use then or catch.
• “A rejected promise is always handled.” No. If you add no catch, the browser or Node.js shows an "unhandled rejection" error.
• “fetch rejects for every server error.” No. A 404 or 500 page still fulfills. Check response.ok.

Key takeaways

• A promise is an object for one result that comes later.
• It starts pending and settles once: fulfilled with a value, or rejected with a reason.
• new Promise runs its executor right away. Handlers run later, after the script finishes.
• then is for success, catch is for failure, and finally is for cleanup.
• A settled promise keeps its result, so a handler added late still gets it.

A promise is an object for work that finishes later: pending now, fulfilled or rejected later, and you can add handlers to it at any time.

Up next: Promise chaining.