async / await

1What async/await Actually Is

async/await is syntax sugar over Promises — it doesn't replace them, it makes code that uses them read like synchronous code, while still being fully asynchronous underneath.

// Promise chain
function loadUser(id) {
  return fetch(`/users/${id}`).then(res => res.json());
}

// Equivalent async/await
async function loadUser(id) {
  const res = await fetch(`/users/${id}`);
  return res.json();
}

2async Functions Always Return a Promise

async function example() {
  return 42;
}
example(); // Promise { 42 } — NOT the number 42 directly
example().then(value => console.log(value)); // 42

If the function body throws, the returned Promise rejects instead:

async function fails() {
  throw new Error("boom");
}
fails().catch(e => console.log(e.message)); // "boom"

3await Pauses the Function, Not the Program

async function example() {
  console.log("1: before await");
  const result = await delay(100, "done"); // pauses HERE, but only this function
  console.log("3: after await:", result);
}
example();
console.log("2: runs immediately — the rest of the program is NOT blocked");
// order: 1, 2, 3

await can only be used inside an async function (or at the top level of an ES module). Everything after await is scheduled as a microtask, exactly like a .then() callback (see the Microtasks vs Macrotasks topic).

4await Unwraps a Promise's Value (or Throws Its Rejection)

async function example() {
  const value = await Promise.resolve(42);   // value = 42, unwrapped automatically
  try {
    await Promise.reject(new Error("failed"));
  } catch (e) {
    console.log(e.message); // "failed" — a rejected awaited Promise throws, catchable with try/catch
  }
}

await on a rejected Promise behaves exactly like a throw — this is what makes try/catch work naturally with async code (full detail in the Async Error Handling topic).

5Sequential vs Concurrent await (Preview)

// SEQUENTIAL — each await waits for the previous one to finish first
async function sequential() {
  const a = await delay(100, "a"); // waits 100ms
  const b = await delay(100, "b"); // THEN waits another 100ms — total ~200ms
  return [a, b];
}

// CONCURRENT — both start immediately, only wait once
async function concurrent() {
  const [a, b] = await Promise.all([delay(100, "a"), delay(100, "b")]); // total ~100ms
  return [a, b];
}

Full depth on this distinction (and when to use each) is covered in the Parallel vs Sequential Async Operations topic — but it's the single most impactful performance decision when writing async/await code.

6Top-Level await

In ES modules, await can be used directly at the top level, outside any async function:

// inside an ES module (.mjs, or "type": "module")
const data = await fetch("/config.json").then(r => r.json());
console.log(data);

// Roughly what async function example() { const x = await foo(); return x + 1; }
// used to desugar to, conceptually:
function example() {
  return driveWithPromises(function* () {
    const x = yield foo();
    return x + 1;
  });
}

⚠️ Common Pitfalls

1. Forgetting an async function always returns a Promise — trying to use its return value directly (without await or .then()) gives you a Promise object, not the resolved value.
2. Using await inside a non-async function — a SyntaxError at parse time; the enclosing function must be declared async.
3. Sequential awaits that could run concurrently — awaiting one independent operation, then another, needlessly serializes work that Promise.all could run in parallel.
4. Forgetting to try/catch an await — an unhandled rejection from an awaited Promise crashes the async function (and, if nothing catches it further up, triggers an unhandledRejection).
5. Mixing .then() and await inconsistently in the same function — not wrong, but usually a readability smell; pick one style per function.

📋 Quick Reference

async function f() { ... }        → always returns a Promise
await promise                       → unwraps value, or throws on rejection
await only inside async functions    → (or top-level in ES modules)
try { await x } catch (e) {}         → standard error handling pattern

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

Source: js_async_await_theory.md · generated by tools/build_lessons.py