JavaScript Async and Await

Adding async to a function changes its return contract to always be a promise.

async function fetchData() {
  return "data";
}
fetchData().then(result => console.log(result));

An async function that returns a plain value wraps it in a resolved promise.

You can use await only inside a function declared with async.

async function getData() {
  const response = await fetch("/api/data");
  return response.json();
}

Async functions are just a cleaner way to work with promises, nothing more.

Every async function returns a promise, even one that never uses await.

Await pauses the function and hands back the resolved value, nothing more.

async function getUser(id) {
  const response = await fetch(`/api/users/${id}`);
  const user = await response.json();
  return user;
}

Await unwraps the resolved value from a promise automatically.

Await only works inside async functions or at a module's top level.

async function getMultiple() {
  const [a, b] = await Promise.all([
    fetch("/a").then(r => r.json()),
    fetch("/b").then(r => r.json())
  ]);
  return [a, b];
}

Do not await independent operations one at a time — use Promise.all instead.

A rejected await throws synchronously, so try/catch works like it does with normal exceptions.

async function fetchData() {
  try {
    const res = await fetch("/data");
    return await res.json();
  } catch (error) {
    console.error("Failed to fetch:", error);
    return null;
  }
}

The catch block runs when any awaited call inside the try block rejects.

Use finally to run cleanup code regardless of success or failure.

async function withCleanup() {
  try {
    return await operation();
  } finally {
    cleanup();
  }
}

Throw errors from async functions to propagate them as promise rejections.

Attach .catch() to an async call when you prefer promise chaining instead.

fetchData().then(data => process(data)).catch(error => console.error("Failed:", error.message));

Runs every promise concurrently and resolves once all of them succeed.

async function getUsers() {
  const [user1, user2] = await Promise.all([
    fetch("/users/1").then(r => r.json()),
    fetch("/users/2").then(r => r.json())
  ]);
  return [user1, user2];
}

Running promises together is much faster than awaiting each one in turn.

Resolves or rejects as soon as the first promise settles, whichever it is.

const fastest = await Promise.race([api1(), api2()]);

Waits for every promise to finish and reports each result, even failures.

Resolves as soon as the first promise succeeds, ignoring earlier rejections.

const result = await Promise.any([
  fetch("/endpoint-1").then(r => r.json()),
  fetch("/endpoint-2").then(r => r.json())
]);
// Resolves with whichever responds first without rejecting

ES modules can await at the top level without a wrapping async function.

// In a module
const config = await loadConfig();

Chain multiple async operations together, each awaiting the previous result.

async function workflow() {
  const data = await fetch1();
  const result = await process(data);
  return await fetch2(result);
}

Use an async IIFE for immediate async execution without a named function.

(async () => {
  const data = await fetchData();
  console.log(data);
})();

Loop over async iterables item by item using for-await-of.

for await (const item of asyncIterator()) {
  console.log(item);
}