Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท Promises and Async

async and await

Reference for JavaScript async and await: how async functions return promises, what await does, error handling, sequential versus parallel work, with examples.

async and await are syntax for working with promises in a top-to-bottom style. Marking a function async makes it always return a promise. Inside it, await pauses that function until a promise settles and gives you the fulfillment value, or throws the rejection reason.

They add no new capabilities to promises: everything you can do with async and await can be done with .then() and .catch(). The benefit is readability, because loops, try...catch and ordinary variables work across asynchronous steps.

This page explains the model behind the syntax. For the individual forms, see async function and the await operator.

Try it

JS What runs when

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Sequential versus parallel

Press Run (or Ctrl + Enter) to see the console output here.

No output.

How an async function runs

An async function starts running synchronously, exactly like a normal function, until it reaches its first await. At that point the function is suspended, and control returns to the caller, which receives the function's promise. When the awaited promise settles, the rest of the function is scheduled as a microtask and resumes where it left off.

In the first example the order is therefore 1, 2, 3, 4: the part before await runs immediately, the caller continues, and only later does the function resume.

The returned promise is fulfilled with whatever the function returns, and rejected if the function throws. Returning a promise from an async function does not nest it: the outer promise adopts the inner one's result.

What await accepts

await value works with any value. A promise is waited for; a thenable (an object with a then method) is treated like a promise; any other value is wrapped in an already-fulfilled promise. Even await 5 yields to the event loop for one microtask before continuing, which matters for ordering.

Handling errors

A rejected promise becomes a thrown exception at the await, so try...catch...finally works as it does for synchronous code:

JavaScript
async function load() {
  try {
    const data = await fetchData();
    return data;
  } catch (error) {
    console.error("failed:", error);
    throw error; // let the caller decide too
  } finally {
    hideSpinner();
  }
}

If nobody handles the rejection of the promise an async function returns, the runtime reports an unhandled rejection.

Sequential or parallel

Each await finishes before the next line runs, so two independent operations written one after another run one after another. The second example shows the difference: sequential() prints A then B, while parallel() starts both timers at once, so the shorter one (D) finishes first and the whole thing takes as long as the slowest task.

Start independent work first, then wait for the results together with Promise.all(), Promise.allSettled() or another combinator.

Usage notes

  • Forgetting await leaves you holding a promise instead of its value. Conditions such as if (isAllowed()) are then always truthy.
  • forEach does not wait. items.forEach(async (item) => { await save(item); }) starts every call and returns immediately. Use a for...of loop to go one at a time, or Promise.all(items.map(save)) to run them together.
  • return await matters inside try...catch: return await task() lets the catch block see a rejection, while return task() does not.
  • Top-level await is allowed in ES modules, not in classic scripts.
  • Async arrow functions and methods (async () => {}, { async run() {} }) behave the same way.
  • A long synchronous section still blocks. async does not move work to another thread; only the waiting is asynchronous.
  • Cancellation is not built in. Pass an AbortSignal to APIs that support it.

Browser support

async and await work in every current browser and in Node.js. Top-level await requires a module.