• Previous
• Overview: Asynchronous JavaScript
• Next

Promises are the foundation of asynchronous programming in modern JavaScript. A promise is an object returned by an asynchronous function, which represents the current state of the operation. At the time the promise is returned to the caller, the operation often isn't finished, but the promise object provides methods to handle the eventual success or failure of the operation.

In theprevious article, we talked about the use of callbacks to implement asynchronous functions. With that design, you call the asynchronous function, passing in your callback function. The function returns immediately and calls your callback when the operation is finished.

With a promise-based API, the asynchronous function starts the operation and returns aPromise object. You can then attach handlers to this promise object, and these handlers will be executed when the operation has succeeded or failed.

Using the fetch() API

In this example, we'll download the JSON file fromhttps://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json, and log some information about it.

To do this, we'll make anHTTP request to the server. In an HTTP request, we send a request message to a remote server, and it sends us back a response. In this case, we'll send a request to get a JSON file from the server. Remember in the last article, where we made HTTP requests using theXMLHttpRequest API? Well, in this article, we'll use thefetch() API, which is the modern, promise-based replacement forXMLHttpRequest.

Copy this into your browser's JavaScript console:

const fetchPromise = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);console.log(fetchPromise);fetchPromise.then((response) => {  console.log(`Received response: ${response.status}`);});console.log("Started request…");

Here we are:

1. calling thefetch() API, and assigning the return value to thefetchPromise variable
2. immediately after, logging thefetchPromise variable. This should output something like:Promise { <state>: "pending" }, telling us that we have aPromise object, and it has astate whose value is"pending". The"pending" state means that the fetch operation is still going on.
3. passing a handler function into the Promise'sthen() method. When (and if) the fetch operation succeeds, the promise will call our handler, passing in aResponse object, which contains the server's response.
4. logging a message that we have started the request.

The complete output should be something like:

Promise { <state>: "pending" }Started request…Received response: 200

Note thatStarted request… is logged before we receive the response. Unlike a synchronous function,fetch() returns while the request is still going on, enabling our program to stay responsive. The response shows the200 (OK)status code, meaning that our request succeeded.

This probably seems a lot like the example in the last article, where we added event handlers to theXMLHttpRequest object. Instead of that, we're passing a handler into thethen() method of the returned promise.

Chaining promises

With thefetch() API, once you get aResponse object, you need to call another function to get the response data. In this case, we want to get the response data as JSON, so we would call thejson() method of theResponse object. It turns out thatjson() is also asynchronous. So this is a case where we have to call two successive asynchronous functions.

Try this:

const fetchPromise = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);fetchPromise.then((response) => {  const jsonPromise = response.json();  jsonPromise.then((data) => {    console.log(data[0].name);  });});

In this example, as before, we add athen() handler to the promise returned byfetch(). But this time, our handler callsresponse.json(), and then passes a newthen() handler into the promise returned byresponse.json().

This should log "baked beans" (the name of the first product listed in "products.json").

But wait! Remember the last article, where we said that by calling a callback inside another callback, we got successively more nested levels of code? And we said that this "callback hell" made our code hard to understand? Isn't this just the same, only withthen() calls?

It is, of course. But the elegant feature of promises is thatthen() itself returns a new promise that is fulfilled with the return value of the callback function (provided the function runs successfully). This means that we can (and certainly should) rewrite the above code like this:

const fetchPromise = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);fetchPromise  .then((response) => response.json())  .then((data) => {    console.log(data[0].name);  });

Instead of calling the secondthen() inside the handler for the firstthen(), we canreturn the promise returned byjson(), and call the secondthen() on that return value. This is calledpromise chaining and means we can avoid ever-increasing levels of indentation when we need to make consecutive asynchronous function calls.

Before we move on to the next step, there's one more piece to add. We need to check that the server accepted and was able to handle the request, before we try to read it. We'll do this by checking the status code in the response and throwing an error if it wasn't "OK":

const fetchPromise = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);fetchPromise  .then((response) => {    if (!response.ok) {      throw new Error(`HTTP error: ${response.status}`);    }    return response.json();  })  .then((data) => {    console.log(data[0].name);  });

Catching errors

This brings us to the last piece: how do we handle errors? Thefetch() API can throw an error for many reasons (for example, because there was no network connectivity or the URL was malformed in some way) and we are throwing an error ourselves if the server returned an error.

In the last article, we saw that error handling can get very difficult with nested callbacks, making us handle errors at every nesting level.

To support error handling,Promise objects provide acatch() method. This is a lot likethen(): you call it and pass in a handler function. However, while the handler passed tothen() is called when the asynchronous operationsucceeds, the handler passed tocatch() is called when the asynchronous operationfails.

If you addcatch() to the end of a promise chain, then it will be called when any of the asynchronous function calls fail. So you can implement an operation as several consecutive asynchronous function calls, and have a single place to handle all errors.

Try this version of ourfetch() code. We've added an error handler usingcatch(), and also modified the URL so the request will fail.

const fetchPromise = fetch(  "bad-scheme://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);fetchPromise  .then((response) => {    if (!response.ok) {      throw new Error(`HTTP error: ${response.status}`);    }    return response.json();  })  .then((data) => {    console.log(data[0].name);  })  .catch((error) => {    console.error(`Could not get products: ${error}`);  });

Try running this version: you should see the error logged by ourcatch() handler.

Promise terminology

Promises come with some quite specific terminology that it's worth getting clear about.

First, a promise can be in one of three states:

• pending: The initial state. The operation has not yet completed (succeeded or failed).
• fulfilled: The operation succeeded. This is when the promise's.then() handler is called.
• rejected: The operation failed. This is when the promise's.catch() handler is called.

Note that what "succeeded" or "failed" means here is up to the API in question. For example,fetch() rejects the returned promise if (among other reasons) a network error prevented the request being sent, but fulfills the promise if the server sent a response, even if the response was an error like404 Not Found.

We also use a few other terms to describe a promise's state:

• completed: The promise is no longer pending; it has either been fulfilled or rejected.
• resolved: The promise is completed, or it has been "locked in" to follow the state of another promise. This is a more advanced concept, relevant when one promise depends on another.

The articleLet's talk about how to talk about promises gives a great explanation of the details of this terminology.

Combining multiple promises

The promise chain is what you need when your operation consists of several asynchronous functions, and you need each one to complete before starting the next one. But there are other ways you might need to combine asynchronous function calls, and thePromise API provides some helpers for them.

Sometimes, you need all the promises to be fulfilled, but they don't depend on each other. In a case like that, it's much more efficient to start them all off together, then be notified when they have all fulfilled. ThePromise.all() method is what you need here. It takes an array of promises and returns a single promise.

The promise returned byPromise.all() is:

• fulfilled when and ifall the promises in the array are fulfilled. In this case, thethen() handler is called with an array of all the responses, in the same order that the promises were passed intoall().
• rejected when and ifany of the promises in the array are rejected. In this case, thecatch() handler is called with the error thrown by the promise that rejected.

For example:

const fetchPromise1 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);const fetchPromise2 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/not-found",);const fetchPromise3 = fetch(  "https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json",);Promise.all([fetchPromise1, fetchPromise2, fetchPromise3])  .then((responses) => {    for (const response of responses) {      console.log(`${response.url}: ${response.status}`);    }  })  .catch((error) => {    console.error(`Failed to fetch: ${error}`);  });

Here, we're making threefetch() requests to three different URLs. If they all succeed, we will log the response status of each one. If any of them fail, then we're logging the failure.

With the URLs we've provided, all the requests should be fulfilled, although for the second, the server will return404 (Not Found) instead of200 (OK) because the requested file does not exist. So the output should be:

https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json: 200https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/not-found: 404https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json: 200

If we try the same code with a badly formed URL, like this:

const fetchPromise1 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);const fetchPromise2 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/not-found",);const fetchPromise3 = fetch(  "bad-scheme://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json",);Promise.all([fetchPromise1, fetchPromise2, fetchPromise3])  .then((responses) => {    for (const response of responses) {      console.log(`${response.url}: ${response.status}`);    }  })  .catch((error) => {    console.error(`Failed to fetch: ${error}`);  });

Then we can expect thecatch() handler to run, and we should see something like:

Failed to fetch: TypeError: Failed to fetch

Sometimes, you might need any one of a set of promises to be fulfilled, and don't care which one. In that case, you wantPromise.any(). This is likePromise.all(), except that it is fulfilled as soon as any of the array of promises is fulfilled, or rejected if all of them are rejected:

const fetchPromise1 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",);const fetchPromise2 = fetch(  "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/not-found",);const fetchPromise3 = fetch(  "https://mdn.github.io/learning-area/javascript/oojs/json/superheroes.json",);Promise.any([fetchPromise1, fetchPromise2, fetchPromise3])  .then((response) => {    console.log(`${response.url}: ${response.status}`);  })  .catch((error) => {    console.error(`Failed to fetch: ${error}`);  });

Note that in this case we can't predict which fetch request will complete first.

These are just two of the extraPromise functions for combining multiple promises. To learn about the rest, see thePromise reference documentation.

async and await

Theasync keyword gives you a simpler way to work with asynchronous promise-based code. Addingasync at the start of a function makes it an async function:

async function myFunction() {  // This is an async function}

Inside an async function, you can use theawait keyword before a call to a function that returns a promise. This makes the code wait at that point until the promise is settled, at which point the fulfilled value of the promise is treated as a return value, or the rejected value is thrown.

This enables you to write code that uses asynchronous functions but looks like synchronous code. For example, we could use it to rewrite our fetch example:

async function fetchProducts() {  try {    // after this line, our function will wait for the `fetch()` call to be settled    // the `fetch()` call will either return a Response or throw an error    const response = await fetch(      "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",    );    if (!response.ok) {      throw new Error(`HTTP error: ${response.status}`);    }    // after this line, our function will wait for the `response.json()` call to be settled    // the `response.json()` call will either return the parsed JSON object or throw an error    const data = await response.json();    console.log(data[0].name);  } catch (error) {    console.error(`Could not get products: ${error}`);  }}fetchProducts();

Here, we are callingawait fetch(), and instead of getting aPromise, our caller gets back a fully completeResponse object, just as iffetch() were a synchronous function!

We can even use atry...catch block for error handling, exactly as we would if the code were synchronous.

Note though that async functions always return a promise, so you can't do something like:

async function fetchProducts() {  try {    const response = await fetch(      "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",    );    if (!response.ok) {      throw new Error(`HTTP error: ${response.status}`);    }    const data = await response.json();    return data;  } catch (error) {    console.error(`Could not get products: ${error}`);  }}const promise = fetchProducts();console.log(promise[0].name); // "promise" is a Promise object, so this will not work

Instead, you'd need to do something like:

async function fetchProducts() {  const response = await fetch(    "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",  );  if (!response.ok) {    throw new Error(`HTTP error: ${response.status}`);  }  const data = await response.json();  return data;}const promise = fetchProducts();promise  .then((data) => {    console.log(data[0].name);  })  .catch((error) => {    console.error(`Could not get products: ${error}`);  });

Here, we moved thetry...catch back to thecatch handler on the returned promise. This means ourthen handler doesn't have to deal with the case where an error got caught inside thefetchProducts function, causingdata to beundefined. Handle errors as the last step of your promise chain.

Also, note that you can only useawait inside anasync function, unless your code is in aJavaScript module. That means you can't do this in a normal script:

try {  // using await outside an async function is only allowed in a module  const response = await fetch(    "https://mdn.github.io/learning-area/javascript/apis/fetching-data/can-store/products.json",  );  if (!response.ok) {    throw new Error(`HTTP error: ${response.status}`);  }  const data = await response.json();  console.log(data[0].name);} catch (error) {  console.error(`Could not get products: ${error}`);  throw error;}

You'll probably useasync functions a lot where you might otherwise use promise chains, and they make working with promises much more intuitive.

Keep in mind that just like a promise chain,await forces asynchronous operations to be completed in series. This is necessary if the result of the next operation depends on the result of the last one, but if that's not the case then something likePromise.all() will be more performant.

Summary

Promises are the foundation of asynchronous programming in modern JavaScript. They make it easier to express and reason about sequences of asynchronous operations without deeply nested callbacks, and they support a style of error handling that is similar to the synchronoustry...catch statement.

Theasync andawait keywords make it easier to build an operation from a series of consecutive asynchronous function calls, avoiding the need to create explicit promise chains, and allowing you to write code that looks just like synchronous code.

Promises work in the latest versions of all modern browsers; the only place where promise support will be a problem is in Opera Mini and IE11 and earlier versions.

We didn't touch on all features of promises in this article, just the most interesting and useful ones. As you start to learn more about promises, you'll come across more features and techniques.

Many modern Web APIs are promise-based, includingWebRTC,Web Audio API,Media Capture and Streams API, and many more.

See also

• Promise()
• Using promises
• We have a problem with promises by Nolan Lawson
• Let's talk about how to talk about promises

• Previous
• Overview: Asynchronous JavaScript
• Next