Promises and async/await explained

JavaScript runs your code on a single thread. Slow work such as network requests, timers and file reads is handed off, and you get a promise back immediately. The promise is later fulfilled with a value or rejected with an error.

async and await

An async function always returns a promise. Inside it, await pauses that function (not the whole program) until a promise settles, then gives you its value or throws its error.

async function loadUser(id) {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  return response.json();
}

try {
  const user = await loadUser(1);
  console.log(user.name);
} catch (err) {
  console.error("Could not load user:", err.message);
}

Errors from awaited promises are caught by ordinary try/catch. Top-level await, as in the last lines above, works in ES modules (.mjs files, type="module" scripts) but not in CommonJS.

Creating a promise yourself

You rarely need new Promise, except to wrap a callback-based API. A small wait helper is the usual example:

const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
await wait(500);

Node already ships promise versions of most APIs, such as node:fs/promises and setTimeout from node:timers/promises, so check before wrapping.

Sequential versus parallel

The most common performance mistake is awaiting independent tasks one after another. Each await in a loop waits for the previous one to finish:

// Sequential: total time is the sum of all requests
for (const id of ids) {
  results.push(await loadUser(id));
}

// Parallel: start everything, then wait once
const results = await Promise.all(ids.map(loadUser));

Use the sequential form only when each step depends on the previous result, or when you must not overload a server. For a bounded middle ground, run tasks with a concurrency limit.

Combining promises

• Promise.all(list): waits for all; rejects as soon as any one rejects.
• Promise.allSettled(list): waits for all and reports each as { status: "fulfilled", value } or { status: "rejected", reason }. Good for batch jobs where partial success is fine.
• Promise.race(list): settles like whichever promise settles first, success or failure.
• Promise.any(list): the first one to succeed; rejects with an AggregateError only if all fail.
• Promise.withResolvers(): returns { promise, resolve, reject } for cases where resolving happens outside the constructor callback.

Common pitfalls

• Forgetting await. const data = loadUser(1) stores a pending promise, not the user. A linter rule such as @typescript-eslint/no-floating-promises catches this.
• Unhandled rejections. A rejected promise that nobody catches makes Node print the error and exit with a non-zero code. Always await or attach .catch().
• async callbacks in forEach. forEach ignores returned promises, so the code after it does not wait. Use for...of or Promise.all with map.
• return versus return await inside try. If you write return promise in a try block, a rejection skips your catch. Use return await promise there.

How it fits the event loop

Code after an await runs as a microtask once the awaited promise settles. Microtasks run after the current synchronous code finishes and before the next timer or I/O callback. That is why await never blocks other work, and why a long synchronous loop still freezes everything, async function or not.