async & await

Readable promise code

Promises gave JavaScript a standard way to represent work that will finish later. async and await give you a friendlier way to write that promise code. Instead of nesting every next step inside .then(...), you can write a sequence that reads from top to bottom.

The pause is the magic worth understanding. It does not freeze the browser tab, block clicks, or stop timers. It pauses one async function, lets the rest of JavaScript keep moving, and comes back to the exact line when the awaited promise settles. If you have already studied Promises, the Event loop, and Microtasks, this lesson connects those pieces into the syntax you will use every day.

We will cover the pieces in the order you need them: async functions return promises, await pauses and resumes, errors travel through try/catch, top-level await belongs to modules, and under the hood the whole feature is promise continuation machinery—not a second thread.

Put async before a function declaration, function expression, arrow function, or method, and calling it always returns a new native promise. The body begins running synchronously, right away, until it either returns, throws, or reaches its first await.

Try the branches below. The code is fixed, but you choose which branch runs in the real browser. Notice two details: return; fulfills with undefined, and returning a promise does not return the same promise object—it creates a new async-function promise that adopts the 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);

An unawaited async call still starts. If it later throws and nobody catches the returned promise, the host reports an unhandled rejection. In real code, either await it, return it to someone who will await it, or attach .catch(...) deliberately.

The most important output pattern is A, C, B. The async function prints A before the await. The caller continues and prints C. Later, the async function resumes 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 settings. A resolved promise, a timer promise, and a plain value all pause the rest of the async function. The timer changes how long you wait, not the shape of the order. Even await 0 means “wrap this with Promise.resolve and resume later.” Do not count exact ticks; modern engines have optimized await over time. The stable rule is: code after await runs later, after the current caller can continue.

A rejected promise awaited inside a try behaves like a throw at that line. That means ordinary catch and finally become useful again for asynchronous work.

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}

Two traps are classics. First, return fetchData() inside a try returns the promise without awaiting it. If that promise rejects later, the catch has already been skipped. Use return await fetchData() when you need that catch (or the timing of finally) to observe the failure.

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}

Outside a try/catch, return await is usually unnecessary: returning the promise is enough. Inside a try, it can be the difference between “caught here” and “rejected somewhere else.”

Second, forgetting await can make checks silently wrong. A promise object is truthy, so if (checkPermission()) runs the branch before the permission boolean arrives.

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

You should not imagine engine internals too literally. Different engines implement optimizations differently. But as a mental model, await value is roughly:

• convert value with Promise.resolve(value),
• save the async function’s current state, and
• run the rest of the function as a continuation when the promise settles.

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}

That saved continuation is why async functions feel like suspended state machines, similar in spirit to generators: the function can stop in the middle, keep its locals, and later continue. The promise chain version is not a perfect source-to-source translation, but it explains why await does not block the thread and why errors after await become promise rejections.

Since ES2022, ES modules can use await at the top level, outside any function. This pauses evaluation of that module and of modules that import it. Classic scripts cannot do this. DevTools consoles and the Node REPL often allow top-level await as a learning convenience, but that is not the same as putting it 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 is helpful for module setup, such as loading a configuration before exporting values. Use it carefully: an importer waits for the awaited module, so a slow top-level await can delay a whole module graph.

Where you’ll use this

You will use async/await any time a program asks for something that is not ready yet: data from a server, a file from disk, an animation finishing, a permission prompt, or a timer. The common shape is “show loading, await the work, render success, 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}

That example waits sequentially: projects need the user’s id first. When two requests do not depend on each other, you often start them together and await them together. The next lesson, “Sequential vs parallel,” focuses on those patterns, including loops. Later, the course returns to for await...of for streams of async values.

Common misconceptions

• “async makes the function run on another thread.” No: the function starts on the same JavaScript thread and yields at awaits.
• “await blocks the whole page.” It pauses one async function; other ready code can run.
• “awaiting a non-promise is synchronous.” It still pauses and resumes later.
• “try/catch catches every promise returned inside it.” Only awaited rejections throw at that line. Returning a promise is not the same as awaiting it.
• “await inside forEach makes forEach wait.” An async callback is allowed, but forEach does not wait for its promises. Preview: the next lesson fixes this with explicit loop and parallel patterns.
• “Top-level await works in any script.” Standard top-level await is for modules, not classic scripts.

Key takeaways

• Calling an async function returns a new promise immediately.
• Returns fulfill that promise, throws reject it, and promises or thenables are adopted.
• await pauses the current async function; it does not block the whole JavaScript thread.
• Even await on a plain value resumes later.
• Use try/catch around awaited expressions, and use return await when that local catch or finally timing matters.
• Top-level await is for ES modules; classic scripts get a syntax error.

Final definition: async/await is promise syntax that lets one function pause at promise boundaries while the rest of JavaScript keeps running.

Up next: Sequential vs parallel.