Async, the Event Loop & Iteration

JavaScript runs your code on one thread: one call stack, one thing at a time. If waiting for a network response blocked that thread, the whole page would freeze — no clicks, no scrolling, no painting — until the response came back. So slow work (network, timers, disk) is handed to the environment (the browser, or libuv in Node), which does the waiting in the background, and your code is told when the result is ready.

How you're told has gone through three generations, each built on the one before. Promises replaced "pass me a function to call later" with an object you get back immediately and can pass around. async/await is syntax on top of promises — under the hood it's still promises.

A useful mental model: a callback is "call me when it's done". A promise is the buzzer you get at a food counter — you get it straight away, before the food exists, and you can hand it to someone else or check it later. await is "stand here until the buzzer goes off" — except only this function stands still; the rest of the program keeps working.

// 1. Callbacks — nesting gets ugly fast ("callback hell")
getUser(id, (err, user) => {
  if (err) return handle(err);
  getOrders(user, (err, orders) => {
    if (err) return handle(err);
    render(orders);
  });
});

// 2. Promises — flat chains, one error handler
getUser(id)
  .then((user) => getOrders(user))
  .then(render)
  .catch(handle);

// 3. async/await — promises that read like synchronous code
try {
  const user = await getUser(id);
  render(await getOrders(user));
} catch (err) {
  handle(err);
}

A Promise is an object standing in for a value that will be available later. It's always in one of three states: pending, fulfilled (with a value) or rejected (with a reason). It starts pending and settles at most once — after that, its state and value never change, and further attempts to resolve or reject it are ignored.

Three properties make promises useful:

• You get the promise immediately, before the result exists, so you can return it, store it, or pass it to other code.
• Handlers attached with .then run once it settles — even if you attach them after it settled. Unlike an event, you can't "miss" a promise.
• Every .then, .catch and .finally returns a new promise. That's what makes chaining work. The new promise settles based on what the handler does: return a value → fulfilled with that value; return a promise → follows that promise; throw → rejected with the thrown error.

function returnAfter(ms, value) {
  return new Promise((resolve, reject) => {
    if (ms < 0) return reject(new RangeError("ms must be ≥ 0"));
    setTimeout(() => resolve(value), ms);
  });
}

returnAfter(1000, 42)
  .then((v) => v * 2)          // return a value → next then gets it
  .then((v) => returnAfter(500, v + 1)) // return a promise → chain waits for it
  .then(console.log)           // 85
  .catch(console.error)        // catches a rejection from ANY step above
  .finally(() => console.log("done")); // runs either way, receives nothing

The function you pass to new Promise(...) is called the executor, and it runs immediately, right there in the current call stack. Only the .then callbacks are asynchronous.

That makes sense once you see what the executor is for: it starts the async work — sets the timer, sends the request — and that should happen now, not later. The constructor's contract is "start the job now and give me the buzzer"; .then is "when the buzzer goes off, do this — but never before the code that's currently running has finished".

console.log("1");
const p = new Promise((resolve) => {
  console.log("2 — executor runs now");
  resolve();
  console.log("3 — still runs after resolve()");
});
p.then(() => console.log("5 — then is a microtask"));
console.log("4");

// 1, 2, 3, 4, 5

const once = new Promise((resolve, reject) => {
  resolve("first");
  reject(new Error("ignored")); // already settled — no effect
  resolve("also ignored");
});
once.then(console.log); // "first"

const boom = new Promise(() => {
  throw new Error("boom"); // a throw inside the executor = reject(error)
});
boom.catch((e) => console.log(e.message)); // "boom"

An async function is a function that always returns a promise and is allowed to use await inside. await somePromise pauses this function until the promise settles: if it fulfils, await evaluates to the value; if it rejects, await throws the reason, so you can use ordinary try/catch.

The mental model is a bookmark. At an await, the engine saves the function's position and its local variables, takes the function off the call stack, and returns to whoever called it. The thread is free to do other work. When the awaited promise settles, a microtask puts the function back on the stack exactly where the bookmark was. Nothing blocks — await is not sleep.

function returnAfter25secs() {
  return new Promise((resolve) => setTimeout(() => resolve(1), 25_000));
}

async function callThis() {
  const result = await returnAfter25secs(); // pauses THIS function only
  console.log(result); // 1, after 25 seconds
}

callThis();
console.log("this logs first — the rest of the program keeps running");

async function fetchData() {
  try {
    const res = await fetch("/api/user");
    if (!res.ok) throw new Error(`HTTP ${res.status}`); // fetch doesn't reject on 404/500!
    return await res.json();
  } catch (error) {
    console.error(error);
    return null;
  }
}

Whatever you return from an async function is wrapped in a promise; whatever you throw becomes a rejection. That's true even for errors thrown on the very first line, before any await: an async function never throws synchronously to its caller. And if you return a promise, the function's promise simply follows it — you never get a promise of a promise.

async function one() {
  return 1;
}
one();                 // Promise {<fulfilled>: 1}, not 1
one().then(console.log); // 1

async function fail() {
  throw new Error("nope");
}
fail().catch((e) => console.log(e.message)); // "nope" — no synchronous throw

When an async function hits await, it pauses and returns to its caller. The rest of the function (the continuation) is scheduled as a microtask once the awaited promise settles — even if the value was already available.

Think of the engine cutting the function into pieces at every await. The first piece runs synchronously as part of the call. Each later piece is queued as a microtask when the value it waits for is ready. If you await something that isn't a promise (like null or 5), it's wrapped in an already-fulfilled promise, so the next piece is queued immediately — but it still has to wait its turn in the queue. await always gives up the thread at least once.

async function demo() {
  console.log("B");
  await null;           // even awaiting a non-promise yields
  console.log("D");
}

console.log("A");
demo();
console.log("C");
// A, B, C, D

async function first() {
  console.log("first: 1");
  await null;
  console.log("first: 2");
  await null;
  console.log("first: 3");
}

async function second() {
  console.log("second: 1");
  await null;
  console.log("second: 2");
}

first();
second();
console.log("sync code done");
// first: 1, second: 1, sync code done, first: 2, second: 2, first: 3

The event loop is how a single-threaded runtime handles asynchronous work. JavaScript has run-to-completion semantics: once a piece of code starts (a script, a callback, a microtask), nothing interrupts it until it returns. Asynchronous callbacks never pre-empt running code; they wait in queues until the call stack is empty.

A mental model: one chef (the thread) works at one station (the call stack). Helpers (Web APIs / libuv) do all the waiting — for the oven timer, for deliveries. When something is ready, a ticket goes into one of two trays. The chef only checks the trays after finishing the current dish. They always empty the priority tray (microtasks) completely — including tickets added while emptying it — and only then take one ticket from the normal tray (macrotasks). In a browser, the dining room can be repainted between normal tickets.

1. The engine runs synchronous code on the call stack. The initial script is itself the first macrotask.
2. Async operations (setTimeout, fetch, DOM events, file I/O) are handed to the Web APIs (browser) or libuv (Node), which do the work in the background — on other threads or in the operating system, not on the JavaScript thread.
3. When the work finishes, a callback is queued. Timers, I/O and UI events queue a macrotask (task). When a promise settles, its .then/.catch/.finally reactions and await continuations are queued as microtasks.
4. Whenever the call stack is empty, the event loop drains the entire microtask queue (including microtasks added while draining).
5. Then it takes one macrotask, runs it, and goes back to step 4. In browsers, rendering can happen between macrotasks.

Here are steps 4 and 5 in action — note where the microtask queued by a timer runs:

setTimeout(() => console.log("timeout 1"), 0);
setTimeout(() => {
  console.log("timeout 2");
  Promise.resolve().then(() => console.log("microtask from timeout 2"));
}, 0);
setTimeout(() => console.log("timeout 3"), 0);

Promise.resolve().then(() => {
  console.log("microtask 1");
  queueMicrotask(() => console.log("microtask 2 (queued while draining)"));
});
console.log("script done");

// script done, microtask 1, microtask 2 (queued while draining),
// timeout 1, timeout 2, microtask from timeout 2, timeout 3

Why two queues? Microtasks are for "finish this piece of work before anything else happens". When a promise settles, the code reacting to it should run as soon as the current code finishes, while the world is still in the state it left it — before a timer, a click handler or a repaint can see a half-finished update. Macrotasks are separate, independent units of work arriving from outside: a timer firing, a user click, a network message.

Microtasks always run before the next macrotask. A setTimeout(fn, 0) is "as soon as possible after the current task and all microtasks" — not immediately.

One subtlety in the table: with fetch(url).then(cb), the network response arrives as a task, and that task fulfils the promise — but cb itself runs as a microtask straight after it. An XHR onload handler, by contrast, is the task.

The process.nextTick row also needs a caveat, because the order depends on the module system:

Promise.resolve().then(() => console.log("promise"));
process.nextTick(() => console.log("nextTick"));
// CommonJS (.js / .cjs): nextTick, promise
// ES module (.mjs):      promise, nextTick

console.log("1");
setTimeout(() => console.log("2"), 0);
Promise.resolve().then(() => console.log("3"));
console.log("4");

console.log("A");

setTimeout(() => console.log("B"), 0);

new Promise((resolve) => {
  console.log("C");
  resolve();
}).then(() => console.log("D"));

(async () => {
  console.log("E");
  await null;
  console.log("F");
})();

queueMicrotask(() => console.log("G"));

console.log("H");

These static methods take an iterable of promises and return one promise that settles based on them. They don't start anything: the work starts the moment you call the functions that create the promises (fetch(...)). The combinator only decides how to combine the results. And none of them cancels the losers — a promise that's no longer needed keeps running; its result is just ignored.

// Parallel — total time ≈ the slowest request
const [user, posts] = await Promise.all([
  fetch("/api/user").then((r) => r.json()),
  fetch("/api/posts").then((r) => r.json()),
]);

// Keep going even if some fail
const results = await Promise.allSettled(urls.map((u) => fetch(u)));
const ok = results.filter((r) => r.status === "fulfilled").map((r) => r.value);

// Timeout with race
const timeout = (ms) =>
  new Promise((_, reject) => setTimeout(() => reject(new Error("Timed out")), ms));
const data = await Promise.race([fetch("/slow"), timeout(5000)]);

// First successful mirror
const fastest = await Promise.any([fetch(mirrorA), fetch(mirrorB)]);

Promise.all(items.map(fetchItem)) fires every request at once — 1,000 items means 1,000 simultaneous requests. That's a problem: servers rate-limit you, browsers only open a handful of connections per host anyway (about 6 over HTTP/1.1), and every in-flight request holds memory.

A small worker pool caps it: start limit workers that share one list of items, and let each worker take the next unclaimed item as soon as it finishes its current one — like a few cashiers serving a single queue of customers.

async function mapWithLimit(items, limit, fn) {
  const results = new Array(items.length);
  let next = 0;

  async function worker() {
    while (next < items.length) {
      const i = next++;            // safe: JS is single-threaded between awaits
      results[i] = await fn(items[i], i);
    }
  }

  const workers = Array.from({ length: Math.min(limit, items.length) }, worker);
  await Promise.all(workers);
  return results; // same order as items
}

const pages = await mapWithLimit(urls, 5, (url) => fetch(url).then((r) => r.text()));

const delays = [300, 100, 200, 100, 100];
const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const out = await mapWithLimit(["a", "b", "c", "d", "e"], 2, async (x, i) => {
  console.log("start", x);
  await wait(delays[i]);
  return x.toUpperCase();
});
console.log(out); // ["A", "B", "C", "D", "E"], after ~400 ms

A promise has no "cancel" button — it's a read-only receipt for work that's already happening. AbortController adds cancellation by splitting it into two objects: the controller, which has the power to cancel (abort()), and its signal, which you hand to the operations that should listen. Many APIs accept a signal: fetch, addEventListener (to remove listeners), and many Node APIs (fs.readFile, timers/promises, streams). One abort() call can cancel all of them at once.

const controller = new AbortController();

fetch("/api/search?q=js", { signal: controller.signal })
  .then((r) => r.json())
  .catch((err) => {
    if (err.name === "AbortError") return; // we cancelled it — not a real error
    throw err;
  });

controller.abort(); // e.g. the user typed again, or the component unmounted

// Built-in timeout
await fetch("/api/slow", { signal: AbortSignal.timeout(5000) });

let controller;

async function search(q) {
  controller?.abort(); // cancel the previous request, if any
  controller = new AbortController();
  try {
    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal: controller.signal });
    renderResults(await res.json());
  } catch (err) {
    if (err.name !== "AbortError") throw err;
  }
}

ES2022 lets you wrap a low-level error in a more meaningful one without losing the original.

Before this, you had two bad options when catching and re-throwing: throw a new error and lose the original message and stack, or glue messages together into one long string. With new Error(message, { cause }), the new error describes what you were trying to do, and its .cause property holds the original error that explains why it failed. Think of it as a chain of "because": "Failed to load user 7" because "Unexpected token '<'". It works with every built-in error type and with subclasses that pass the options object to super.

async function loadUser(id) {
  try {
    const res = await fetch(`/api/users/${id}`);
    return await res.json();
  } catch (err) {
    throw new Error(`Failed to load user ${id}`, { cause: err });
  }
}

try {
  await loadUser(7);
} catch (err) {
  console.log(err.message);      // "Failed to load user 7"
  console.log(err.cause);        // the original TypeError / SyntaxError
}

Two small contracts power for...of, spread, destructuring, Array.from, Promise.all and more:

• An iterator is an object with a next() method that returns { value, done }.
• An iterable is an object with a [Symbol.iterator]() method that returns an iterator.

Why bother with a protocol? Because it gives arrays, strings, Maps, Sets, DOM collections and your own classes one uniform way to say "here is the next item". for...of and spread don't need to know what kind of collection they're looping over — they just follow the protocol. Iteration is pull-based: the consumer calls next() when it wants another value, so the producer can compute values lazily. Picture a ticket dispenser: the iterable is the machine you can ask for a fresh roll; the iterator is the roll, handing out one ticket at a time.

const arr = ["a", "b"];
const it = arr[Symbol.iterator]();
it.next(); // { value: "a", done: false }
it.next(); // { value: "b", done: false }
it.next(); // { value: undefined, done: true }

class Range {
  constructor(start, end, step = 1) {
    Object.assign(this, { start, end, step });
  }

  [Symbol.iterator]() {
    let current = this.start;
    const { end, step } = this;
    return {
      next() {
        if (current > end) return { value: undefined, done: true };
        const value = current;
        current += step;
        return { value, done: false };
      },
    };
  }
}

const r = new Range(1, 10, 3);
[...r];                    // [1, 4, 7, 10]
for (const n of r) console.log(n);
const [first, second] = r; // 1, 4

A generator function (function*) can pause at each yield and resume later. Calling it returns a generator object, which is both an iterator and an iterable — so generators are the easiest way to write custom iterables.

The key difference from a normal function: calling a generator function doesn't run its body. It returns a paused generator object. Each call to next() runs the body until the next yield, hands out that value, and freezes again with all its local variables intact — like pausing a video, not stopping it. Generators exist because hand-written iterators (like Range above) are really little state machines; a generator lets you write the same logic as straight-line code with loops, and the language keeps track of where you were.

function* idGenerator() {
  let id = 1;
  while (true) {
    yield id++; // pause here, hand out a value
  }
}

const ids = idGenerator();
ids.next().value; // 1
ids.next().value; // 2 — infinite, but lazy: values are made only on demand

// The Range class again, much shorter
class Range {
  constructor(start, end) {
    this.start = start;
    this.end = end;
  }
  *[Symbol.iterator]() {
    for (let n = this.start; n <= this.end; n++) yield n;
  }
}
[...new Range(1, 5)]; // [1, 2, 3, 4, 5]

function* conversation() {
  const name = yield "What's your name?";
  yield `Hello, ${name}!`;
}
const chat = conversation();
chat.next().value;          // "What's your name?"
chat.next("Rohit").value;   // "Hello, Rohit!"

idGenerator()
  .filter((n) => n % 2 === 0)
  .map((n) => n * 10)
  .take(3)
  .toArray(); // [20, 40, 60] — only 6 values were ever generated

Why for await exists: a regular iterator's next() must return { value, done } synchronously. Data that arrives over time — paginated APIs, streams, sockets — can't do that. An async iterator's next() returns a promise of { value, done }, and for await...of awaits each one in turn.

The protocol mirrors the sync one: an async iterable has a [Symbol.asyncIterator]() method that returns an async iterator. The easiest way to write one is an async generator (async function*), which can both await (to wait for data) and yield (to hand a value to the consumer). Each yield fulfils the promise that the consumer's next() returned.

// Async generator: yield + await in the same function
async function* fetchAllPages(url) {
  while (url) {
    const res = await fetch(url);
    const { items, nextUrl } = await res.json();
    yield items;
    url = nextUrl;
  }
}

for await (const page of fetchAllPages("/api/products?page=1")) {
  render(page); // each page as soon as it arrives; stops when url is null
}

import { createReadStream } from "node:fs";
import { createInterface } from "node:readline";

const lines = createInterface({ input: createReadStream("huge.log") });
for await (const line of lines) {
  if (line.includes("ERROR")) console.log(line);
}

requestAnimationFrame(callback) asks the browser to run callback right before the next repaint — once per frame, matched to the display's refresh rate (usually 60 Hz, 120 Hz on newer screens).

Where it sits in the event loop: after a task and its microtasks, when the browser decides to render, it runs all queued rAF callbacks → recalculates styles and layout → paints.

Why that matters: the browser draws a new frame roughly every 16.7 ms at 60 Hz. Anything you change in the DOM is only seen when the next frame is painted. Code that runs at the start of a rendering step gets to make its changes just in time for that frame — not too early (the change is overwritten or wasted) and not too late (it misses the frame).

const box = document.querySelector(".box");
let start;

function step(timestamp) {           // timestamp: ms since page load, high precision
  start ??= timestamp;
  const elapsed = timestamp - start;
  const x = Math.min(elapsed / 5, 300); // move 300px over 1.5s
  box.style.transform = `translateX(${x}px)`;
  if (x < 300) requestAnimationFrame(step); // schedule the next frame
}

requestAnimationFrame(step);

A Web Worker runs JavaScript on a separate thread, so heavy computation doesn't freeze the UI. Workers can't touch the DOM; they communicate with the page by passing messages.

The main thread runs your JavaScript and handles input, layout and painting, so a two-second calculation there means two seconds of frozen page. A worker is a real OS thread with its own event loop and its own global scope (self instead of window). It shares no variables with the page. Picture a colleague in another room: you can only slide notes under the door, and each note is photocopied on the way through.

const worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });

worker.postMessage({ numbers: Array.from({ length: 1e7 }, (_, i) => i) });

worker.onmessage = (event) => {
  console.log("Sum from worker:", event.data);
};
worker.onerror = (e) => console.error(e.message);

self.onmessage = (event) => {
  const { numbers } = event.data;
  let sum = 0;
  for (const n of numbers) sum += n; // the page stays responsive meanwhile
  self.postMessage(sum);
};