async & await

Promise code you can read from top to bottom

A promise is an object that stands for a value that arrives later, such as data from a server. You already know how to wait for a promise with .then(...): you pass it a function, and that function runs when the value is ready.

async and await are two keywords that do the same job with less nesting. You write the steps one under the other, and they read from top to bottom, like normal code.

The pause is the part to understand well. It does not freeze the browser tab. Clicks still work, and timers still run. Only one async function waits. The rest of your JavaScript keeps going. When the promise is ready, the paused function goes back to the exact line where it stopped.

This lesson builds on Promises, the Event loop, and Microtasks. If those feel new, have a quick look at them first.

The lesson goes in this order:

1. An async function always gives back a promise.
2. await pauses one function and carries on later.
3. Errors can be caught with try and catch.
4. What await does, written with .then.
5. await outside any function, in modules.

There is no second thread in any of this. A thread is one line of work the computer runs. All of this lesson's code runs on JavaScript's one thread.

You can put async in front of any kind of function: a normal function, an arrow function, or a method. Calling it always gives back a new promise.

The function's code starts running straight away. It runs until one of three things happens: it returns, it throws an error, or it reaches its first await.

async function greet() {
  return "Asha";
}

const result = greet();
console.log(result instanceof Promise);
result.then((name) => console.log(name));

Line 1 makes greet an async function. Line 2 returns the name "Asha".

Line 5 calls greet(). But result holds a promise, not the name. Line 6 checks this with instanceof Promise, which asks "is this a promise?". It prints true.

Line 7 waits with .then. When the promise is ready, the function inside .then gets the name, so it prints Asha.

A few words you will see in this lesson:

• Fulfilled: the promise worked and has a value.
• Rejected: the promise failed and has an error. The error is called the reason.
• Settled: the promise is either fulfilled or rejected. It is no longer waiting.
• Thenable: any object with a then method. JavaScript treats it like a promise.
• Adopt: when an async function returns a promise, its own promise waits for that one and takes the same result.

Try each choice below. The code stays the same; you pick which line runs, and it runs in your browser. Look for two things:

• nothing returns no value, so the promise is fulfilled with undefined.
• promise returns a promise. You don't get that same promise back. You get a new promise that adopts its result.

1async function gift(kind) {2  if (kind === "value") return 42;3  if (kind === "promise") return Promise.resolve("ready");4  if (kind === "thenable") return { then(resolve) { resolve("thenable value"); } };5  if (kind === "throw") throw new Error("broken ribbon");6}7 8gift(kind);

The table sums up the playground. Each row is one way to leave an async function.

An async call starts running even if you never await it. If it throws later and no code handles the promise, the browser or Node shows an "unhandled rejection" error. To avoid that, do one of these:

• await the call.
• Return the promise to code that will await it.
• Add .catch(...) to the call on purpose.

The most important pattern in this lesson is the print order A, C, B:

1. The async function prints A before its await.
2. The function pauses. The code that called it, the caller, carries on and prints C.
3. Later, the async function carries on and prints B.

1async function demo() {2  console.log("A: before await");3  const value = await Promise.resolve("B");4  console.log(value + ": after await");5}6 7demo();Run8console.log("C: caller continues");

Try all three choices. Each one puts something different after await:

• a promise that is already fulfilled,
• a promise that a timer fulfills after 300 milliseconds,
• a plain value, "B", that is not a promise at all.

All three pause the rest of the function. The timer changes how long the function waits. It doesn't change the order.

Even await 0 pauses. JavaScript first turns the value into a promise with Promise.resolve(0), then carries on later. Don't try to count exactly how many steps the pause takes; browsers have changed that over the years. The rule to remember: code after await runs later, after the caller has carried on.

async function readOrder() {
  const order = "tea";
  await Promise.resolve();
  console.log(order);
}

readOrder();
console.log("counter stays open");

Line 2 stores "tea" in order before the pause. Line 3 pauses readOrder.

While it is paused, line 8 runs and prints counter stays open first. Then line 4 runs. order still holds its value, so it prints tea.

Code inside a try block can fail. When it fails, JavaScript jumps to the catch block. A finally block runs at the end either way.

An awaited promise that is rejected inside a try acts like a throw on that line. So catch and finally work for waiting code, the same as for normal code.

1async function loadProfile(failStep) {Run2  try {3    const user = await step("user", failStep);4    const posts = await step("posts", failStep);5    return user + " + " + posts;6  } catch (error) {7    return "caught " + error.message;8  } finally {9    cleanup();10  }11}

There are two common mistakes. The first one: return fetchData() inside a try returns the promise without waiting for it.

If that promise is rejected later, the function has already left the try. So the catch never runs. Write return await fetchData() when you want that catch to handle the failure, or when you need finally to wait until the promise is settled.

1async function notCaught() {2  try {3    return fetchData();4  } catch (error) {5    return "caught";6  }7}8 9async function caught() {10  try {11    return await fetchData();12  } catch (error) {13    return "caught";14  }15}

function fetchData() {
  return Promise.reject(new Error("nope"));
}

async function returned() {
  try {
    return fetchData();
  } catch {
    return "inner";
  }
}

async function awaited() {
  try {
    return await fetchData();
  } catch {
    return "inner";
  }
}

returned().catch((error) => console.log("return", error.message));
awaited().then((value) => console.log("await", value));

returned() returns the rejected promise on line 7. Its own catch doesn't see the error. The .catch on line 21 gets it instead and prints return nope.

awaited() waits on line 15, inside try. The rejection becomes a throw there. Its own catch returns "inner", so line 22 prints await inner.

Outside a try block, you usually don't need return await. Returning the promise is enough. Inside a try block, it decides where the error goes: to this function's catch, or out to the caller.

The second mistake: forgetting await can make a check wrong without any error.

An if treats every object as true; the word for that is truthy. A promise is an object. So if (checkPermission()) always runs its block, before the real true or false arrives.

1if (checkPermission()) {2  showAdminButton(); // runs: a Promise object is truthy3}4 5if (await checkPermission()) {6  showAdminButton(); // waits for the boolean7}

function checkPermission() {
  return Promise.resolve(false);
}

async function showResult() {
  const permission = checkPermission();
  console.log(permission instanceof Promise);
  console.log(await permission);
}

showResult();

Line 6 stores the promise itself in permission, so line 7 prints true: it is a promise. Line 8 adds await, gets the real answer, and prints false.

The JavaScript engine is the program that runs your code, such as the one in your browser. Each engine has its own tricks to make await fast, so don't take this too literally. But as a rough picture, await value does three things:

1. It turns value into a promise with Promise.resolve(value).
2. It saves where the function is and what its variables hold.
3. When the promise is settled, it runs the rest of the function.

"The rest of the function" has a name: the continuation. It is the code still waiting to run after the await.

1async function label() {2  const user = await getUser();3  return "Hi, " + user.name;4}5 6function labelRoughly() {7  return Promise.resolve(getUser()).then((user) => {8    return "Hi, " + user.name;9  });10}

In label, line 2 waits for the user, and line 3 is the continuation. In labelRoughly, line 7 does the same with .then: the continuation, line 8, is inside the function passed to .then.

The two versions are not exactly the same in every detail. But the .then version explains two facts:

• await doesn't stop the thread. It only hands the rest of the function to a promise.
• An error after await rejects the function's promise, just like an error inside .then.

Async functions can stop in the middle, keep their variables, and carry on later. Generator functions, which you may meet later, can do this too.

The table compares the two ways. Read each row as a question, then the answer for each way.

Since 2022, JavaScript lets you use await outside any function, at the top of the file. This is called top-level await. It only works in an ES module: a file loaded with <script type="module"> or with import.

A normal <script> without type="module" is called a classic script. In a classic script, top-level await is a syntax error.

The browser console and the Node prompt often let you use top-level await anyway, to make trying things easier. That doesn't mean it works in a classic script file.

1<script type="module">2  const data = await Promise.resolve("module data");3  parent.postMessage({ kind: "module", value: data }, "*");4</script>5 6<script>7  await Promise.resolve("classic data"); // SyntaxError8</script>

Top-level await pauses the module. Any file that imports that module waits too. This helps when a module must load something first, such as its settings.

Use it with care. If the awaited work is slow, every file that imports the module has to wait for it.

Where you’ll use this

You use async and await whenever code must wait for something that isn't ready yet:

• data from a server,
• a file from the disk,
• an animation finishing,
• a permission question the user must answer,
• a timer.

The usual steps are: show "Loading...", await the work, show the result, and handle failure.

1async function showDashboard() {2  setStatus("Loading...");3  try {4    const user = await getUser();5    const projects = await getProjects(user.id);6    renderDashboard(user, projects);7  } catch (error) {8    showError("Could not load the dashboard.");9  } finally {10    hideSpinner();11  }12}

Line 2 shows a loading message. Line 4 waits for the user. Line 6 shows the dashboard. If anything inside try fails, line 8 shows an error. Line 10 hides the spinner in both cases.

The two await lines run one after the other on purpose: getProjects needs user.id, so it must wait for the user first.

function getUser() {
  return Promise.resolve({ name: "Asha" });
}

async function showProfile() {
  const user = await getUser();
  console.log("Hello, " + user.name);
}

showProfile();

Here getUser is a pretend version, so the example works without the internet. But it has the same steps as real code: line 6 waits for the data, then line 7 shows the greeting. It prints Hello, Asha.

Sometimes two requests don't need each other. Then you can start them together and wait for both at once.

const items = ["tea", "toast"];

async function save(item) {
  return item + " saved";
}

async function run() {
  for (const item of items) {
    console.log(await save(item));
  }
  const saved = await Promise.all(items.map(save));
  console.log(saved.join(", "));
}

run();

The for...of loop waits for each item before it starts the next one. It prints tea saved, then toast saved.

Promise.all takes a list of promises and gives back one promise. That promise is fulfilled when all of them are fulfilled. Here, both save calls start first, then line 11 waits for both. Line 12 prints tea saved, toast saved.

The next lesson, Sequential vs parallel, covers timing and the forEach(async ...) mistake. Later, the course shows for await...of, a loop for values that arrive one at a time.

Common misconceptions

• "async makes the function run on another thread." No. The function runs on JavaScript's one thread. At each await, it steps aside so other code can run.
• "await stops the whole page." No. It pauses one async function. Other code that is ready still runs.
• "Awaiting a value that isn't a promise happens straight away." No. The function still pauses and carries on later.
• "try/catch catches every promise returned inside it." No. It only catches a rejection you await inside the try. Returning a promise is not the same as waiting for it.
• "await inside forEach makes forEach wait." No. You may pass an async function to forEach, but forEach doesn't wait for its promises. The next lesson shows loops that do wait.
• "Top-level await works in any script." No. It works in modules, not in classic scripts.

Key takeaways

• Calling an async function gives back a new promise straight away.
• A return fulfills that promise. A throw rejects it. A returned promise is adopted: the outer promise takes its result.
• await pauses the one async function it is in. The rest of JavaScript keeps running.
• Even await on a plain value carries on later, not straight away.
• Put try/catch around await lines. Inside try, write return await so that catch can see the error.
• Top-level await works in modules. In a classic script, it is a syntax error.

In one line: async and await let one function pause until a promise is ready, while the rest of JavaScript keeps running.

Up next: Sequential vs parallel.