How Promises and async/await Actually Work

A promise is a placeholder for a result that isn’t ready yet. It settles once, to a value or an error, and anyone who calls then on it gets notified, always asynchronously, as a microtask. async/await doesn’t replace promises; it is syntax that writes promise chains for you. This post builds the model from the ground up: states, chaining, how values and errors flow, exactly when callbacks run, and what an async function really does. Every ordering shown was run to confirm the result.

Why It Matters

Most async bugs come from a wrong mental model, not wrong syntax:

• a forgotten await that lets an error escape
• a forEach with async callbacks that nobody waits for
• requests that run one by one when they could run together
• a try/catch that doesn’t catch

All of them follow from a handful of rules.

How We Got Here: From Callbacks to async/await

Before promises, asynchronous JavaScript meant callbacks: you passed a function, and the API called it when the work finished. Node.js standardized “error-first” callbacks, where the first argument is an error or null. Loading a user, then their orders, then an invoice looked like this:

getUser(id, (error, user) => {
  if (error) return handle(error);
  getOrders(user.id, (error, orders) => {
    if (error) return handle(error);
    getInvoice(orders[0].id, (error, invoice) => {
      if (error) return handle(error);
      render(user, orders, invoice);
    });
  });
});

This shape got a name, callback hell (or the “pyramid of doom”), and the indentation was the smallest problem:

• Error handling is repeated at every level, and one forgotten if (error) silently swallows a failure. A throw inside a callback can’t be caught by a try around the outer call.
• Inversion of control. You hand your continuation to someone else’s code and trust it to call it exactly once, with the right arguments. Buggy libraries called callbacks twice, never, or sometimes synchronously and sometimes not.
• No composition. “Run these three in parallel and continue when all finish”, “give up after 5 seconds” or “retry twice” each needed hand-written counters and flags.

Promises fixed this by turning “a result that will exist later” into a value you can return, pass around and combine. The same flow as a promise chain:

getUser(id)
  .then((user) => getOrders(user.id).then((orders) => ({ user, orders })))
  .then(({ user, orders }) =>
    getInvoice(orders[0].id).then((invoice) => render(user, orders, invoice)),
  )
  .catch(handle); // one place for every error in the chain

The pyramid is gone and errors flow to one catch, but passing earlier results along is still awkward. async/await (ES2017) lets you write the same chain as straight-line code:

try {
  const user = await getUser(id);
  const orders = await getOrders(user.id);
  const invoice = await getInvoice(orders[0].id);
  render(user, orders, invoice);
} catch (error) {
  handle(error);
}

Each step is built on the one before: await is promise chaining with nicer syntax, and promises still call callbacks under the hood. Old callback APIs can join in:

• Node.js’s util.promisify wraps an error-first function so it returns a promise.
• Most Node.js core modules now have promise versions (fs/promises, timers/promises).

A Quick Event Loop Refresher

Promises don’t add threads. Everything below happens on the same single thread, scheduled by the event loop:

• Your synchronous code runs first, to completion.
• Promise callbacks and the code after each await are microtasks. They run as soon as the current code finishes, all of them, before anything else.
• Timers, clicks and network events are tasks. One runs per turn of the loop, after the microtasks are drained, and the browser may paint in between.

That is why a resolved promise’s then always runs before a setTimeout(…, 0) queued earlier. The event loop post covers the full model, with diagrams and ordering exercises.

States and Settling

A promise is in one of three states, and it can only move out of pending once:

const p = new Promise((resolve, reject) => {
  resolve('first');
  resolve('second'); // ignored
  reject(new Error('too late')); // ignored
});

The executor function runs synchronously inside new Promise. Only the reactions (then, catch, finally callbacks) run later.

then Returns a New Promise

Every then creates a new promise, settled by what its callback does:

That last row is how errors skip ahead to the next catch:

Promise.resolve(1)
  .then((v) => {
    throw new Error('x' + v);
  })
  .then(() => 'skipped') // no rejection handler here, so the error passes through
  .catch((e) => e.message) // 'x1': catch returns a value, so the chain recovers
  .then((v) => v + '!'); // 'x1!'

When Callbacks Run

Reactions always run as microtasks, after the current synchronous code, even if the promise is already settled. There is one subtle cost: when a callback or an async function returns a promise, adopting it takes extra microtask turns:

async function returnsPromise() {
  return Promise.resolve('f');
}
async function returnsValue() {
  return 'g';
}
returnsPromise().then(log);
returnsValue().then(log);
Promise.resolve()
  .then(() => log('p1'))
  .then(() => log('p2'))
  .then(() => log('p3'));
// g, p1, p2, f, p3

• 'g' arrives first because returning a plain value fulfills immediately.
• 'f' waits for the inner promise’s then to be called and to fire, which costs two extra turns.
• Why it matters: you will rarely depend on this, but it explains why “equivalent” code can log in a different order, and why tests that assume a fixed number of ticks are fragile.

async/await Is Syntax Over Promises

An async function always returns a promise. Its body runs synchronously until the first await; the rest runs later, as a microtask, once the awaited value settles:

async function load() {
  console.log(1);
  const data = await fetchData(); // pause here; the caller continues
  console.log(3, data);
  return data.id; // fulfills the returned promise
}
 
load();
console.log(2);
// 1, 2, then 3 once fetchData settles

The Mistakes This Model Explains

Sequential When It Could Be Parallel

// About 90 ms: each request waits for the previous one
for (const id of ids) results.push(await fetchUser(id));
 
// About 30 ms: all start at once
const results = await Promise.all(ids.map(fetchUser));

• Promise.all for independent work
• Promise.allSettled when you need every outcome, even if some fail
• Promise.any for the first success
• Promise.race for the first to settle

For hundreds of items, limit concurrency so you don’t overload a server (see Limiting Concurrency).

return Without await Inside try

async function noAwait() {
  try {
    return Promise.reject(new Error('lost'));
  } catch {
    return 'caught'; // never runs: the promise is returned before it rejects
  }
}
async function withAwait() {
  try {
    return await Promise.reject(new Error('lost'));
  } catch {
    return 'caught'; // runs
  }
}

Async Callbacks in forEach

array.forEach(async (item) => { await save(item); }) starts every save and returns immediately. forEach ignores the promises, so nobody waits for them and their errors go unhandled. Instead:

• for…of with await to run them one after another
• Promise.all(array.map(…)) to run them in parallel

Floating Promises

A promise that is never awaited or given a catch doesn’t throw where it failed. The runtime reports it later instead:

• Browsers fire an unhandledrejection event and log it to the console.
• Node.js terminates the process by default, since version 15.

Common sources are a missing await, an async function passed as a callback (forEach, event emitters) and fire-and-forget calls. Two defenses:

• a lint rule such as typescript-eslint’s no-floating-promises, to catch them in review
• a global handler in production that reports to your error tracker

Going Deeper: Combinators, Limits and Thenables

Four Ways to Wait for Many Promises

All four combinators take the same input and differ only in when they settle and with what. Given three operations, A succeeding after 30 ms, B failing after 10 ms and C succeeding after 20 ms:

None of them cancels the losers: A and C keep running after Promise.all has rejected (see the cancellation tip above).

Limiting Concurrency

Promise.all(items.map(fetchItem)) starts every request at once. With 5,000 items that can exhaust connections, hit rate limits or overload the server. A small worker pool keeps a fixed number in flight:

async function mapLimit(items, limit, fn) {
  const results = new Array(items.length);
  let next = 0;
  async function worker() {
    while (next < items.length) {
      const i = next++; // claimed synchronously, so no two workers take the same item
      results[i] = await fn(items[i], i);
    }
  }
  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
  return results;
}
 
const users = await mapLimit(ids, 5, fetchUser); // at most 5 requests at a time

• Results stay in input order.
• The first failure rejects the whole call, like Promise.all.
• Libraries such as p-limit offer the same with more options.

Thenables and Promise.withResolvers

• await and Promise.resolve accept any thenable, an object with a then method, not just real promises. await { then(resolve) { resolve(42) } } gives 42. That is how promise libraries interoperate, and also why an object that accidentally has a then property behaves strangely when awaited.
• Promise.withResolvers() (ES2024) returns { promise, resolve, reject }, which is handy when the code that settles a promise is not the code that creates it, for example wrapping an event-based API.

Test Yourself

Predict the output first, then open the answer. Every answer was checked by running the code.

console.log('A');
setTimeout(() => console.log('B'), 0);
Promise.resolve().then(() => console.log('C'));
new Promise((resolve) => {
  console.log('D');
  resolve();
}).then(() => console.log('E'));
console.log('F');

async function load() {
  console.log('load 1');
  await null;
  console.log('load 2');
}
console.log('start');
load();
console.log('end');

Promise.reject(new Error('boom'))
  .then(() => console.log('then 1'))
  .catch((error) => console.log('catch', error.message))
  .then(() => console.log('then 2'))
  .finally(() => console.log('finally'));

async function saveAll(items) {
  items.forEach(async (item) => {
    await save(item);
    console.log('saved', item);
  });
  console.log('done');
}
await saveAll([1, 2]);

Promise.resolve(1)
  .then(2)
  .then((value) => console.log('a', value));
 
Promise.resolve(1)
  .finally(() => 2)
  .then((value) => console.log('b', value));

const slow = new Promise((resolve) =>
  setTimeout(() => {
    console.log('slow finished');
    resolve();
  }, 100),
);
try {
  await Promise.all([slow, Promise.reject(new Error('fast fail'))]);
} catch (error) {
  console.log('caught', error.message);
}

Key Takeaways

Sources

• MDN: Promise concurrency
• MDN: unhandledrejection event
• Node.js docs: --unhandled-rejections
• MDN: Promise.withResolvers()
• ECMAScript specification: Promise objects and Await
• MDN: Using promises and async function
• Promises/A+: The Promises/A+ specification
• Node.js docs: util.promisify
• V8 blog: Faster async functions and promises
• typescript-eslint: no-floating-promises
• MDN: AbortController