Promises and async/await

Run this and predict what it logs before reading on.

function loadUser() {
  return fetch('/api/user')
    .then(res => {
      res.json();
    }) // no return here
    .then(data => console.log(data));
}

loadUser();

It logs undefined. res.json() really does parse the response — but the first .then() callback never returns it, so the second .then() receives whatever the first one returned instead: nothing.

A promise is an object that stands in for a value you don't have yet. It doesn't make anything faster and doesn't run on another thread — it's a receipt that lets the rest of the program carry on while the real value is still pending. async/await is a flatter syntax for exactly the same mechanism. This article covers the states a promise moves through, how chaining actually works, the sharpest edges of error handling, and running things in parallel instead of one at a time.

The tracking number analogy

You order something online. You don't get the package — you get a tracking number.

• The tracking number arrives instantly and is not the package.
• It sits in one of three states: still on the way (pending), delivered (fulfilled), or failed (rejected).
• Once it's settled, it never changes back. A delivered package doesn't become undelivered.
• You can register instructions in advance: when it arrives, leave it with the neighbour. That's .then().

                    ┌──────────────► fulfilled (value)
                    │                    │
   pending ─────────┤                    ├──► settled: never changes again
                    │                    │
                    └──────────────► rejected (reason)

The important consequence: a promise settles exactly once, no matter how many places are listening.

Where the analogy breaks: a real tracking number belongs to a shipment that's already moving — even a lost package eventually gets flagged and refunded. A promise has no such guarantee. If the code that creates it never calls resolve or reject on every path, the promise simply never settles — no error, no timeout, just a permanently pending placeholder. await on it hangs forever with no signal that anything went wrong.

Consuming a promise

Most of the time you're using promises other people created — fetch, a database driver, fs.promises.

fetch('/api/user')
  .then(res => res.json()) // runs on success
  .catch(err => console.error(err)) // runs on any failure above
  .finally(() => setLoading(false)); // runs either way

Two things make chaining work, and both explain the opening bug:

1. .then() returns a new promise. That's why you can keep chaining.
2. What you return inside .then() matters. Return a plain value and the next .then() receives it. Return a promise and the chain waits for it.

Walking through the opening example with that in mind:

1. loadUser() calls fetch(), which returns a promise for the response.
2. The first .then() callback runs once that settles, calls res.json() — which itself returns a promise — but never returns it.
3. Because nothing was returned, the first .then()'s own promise resolves with undefined.
4. The second .then() receives that undefined, not the parsed data.
5. The fix is return res.json(), so the chain waits for the real value.

async/await is the same thing

async/await is syntax over promises. Nothing new happens underneath.

async function loadUser() {
  const res = await fetch('/api/user');
  const data = await res.json();
  return data;
}

Two rules cover most of it:

• An async function always returns a promise, even if you return a plain value.
• await unwraps a promise: it pauses the function until the promise settles, then gives you the value — or throws if it rejected.

await does not block the thread. The function is suspended and the single thread carries on with everything else. Only that one function is paused.

Error handling

With await, a rejected promise becomes a thrown error, so ordinary try/catch works:

async function loadUser() {
  try {
    const res = await fetch('/api/user');
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    return await res.json();
  } catch (err) {
    console.error('Failed to load user', err);
    return null;
  }
}

⚠️ fetch does not reject on a 404 or 500. It only rejects on a network failure. An HTTP error status is a successful round trip as far as fetch is concerned, so you have to check res.ok yourself. This catches almost everyone once.

Note also return await res.json() rather than return res.json(). Without the await, the promise is returned before the try block ends, so a failure inside it escapes your catch.

Sequential vs parallel

This is the most common performance mistake in async code.

// ❌ 3 seconds — each await waits for the previous one
const user = await fetchUser();
const posts = await fetchPosts();
const tags = await fetchTags();

// ✅ 1 second — all three start immediately
const [user, posts, tags] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchTags(),
]);

Use sequential await only when a later call genuinely needs the earlier result. If the calls are independent, Promise.all is not an optimization — it's the correct code.

The same trap inside a loop:

// ❌ one at a time
for (const id of ids) {
  results.push(await fetchItem(id));
}

// ✅ all at once
const results = await Promise.all(ids.map(id => fetchItem(id)));

⚠️ array.forEach(async (x) => ...) does not wait. forEach ignores the returned promise, so the loop finishes instantly and the work continues in the background. Use for...of for sequential, or map + Promise.all for parallel.

The four combinators

Promise.all fails fast — one rejection discards every other result. When you want every outcome regardless, reach for allSettled.

const results = await Promise.allSettled(urls.map(fetchJson));
const ok = results.filter(r => r.status === 'fulfilled');

Side-by-side

The rule of thumb

Write async/await by default — it reads like normal code and gives you real try/catch. Then check two things before moving on: is anything waiting that didn't need to, and is there any promise here with nothing attached to catch a failure? Both questions target the same failure mode — a promise nobody is watching, whether that costs time nobody needed to lose or hides an error nobody will see.

Version and environment notes

• Promise.allSettled is ES2020, available from Node.js 12.9+.
• Promise.any is ES2021, available from Node.js 15+ — the same release that made an unhandled rejection terminate the Node process instead of just warning.
• AbortController, used to cancel the operation behind a promise, is broadly supported in current browsers and Node 15+.
• To verify support for a specific method, run node -v, or check its compatibility table on MDN.

Check yourself

1. What does this log?

Promise.resolve(1)
  .then(val => {
    throw new Error('bad');
  })
  .then(val => console.log('A', val))
  .catch(err => console.log('B', err.message));

2. fetchA() and fetchB() each take 1 second and don't depend on each other. Roughly how long does each version take?

// Version 1
const a = await fetchA();
const b = await fetchB();

// Version 2
const [a, b] = await Promise.all([fetchA(), fetchB()]);

Sources

• MDN Web Docs — Using promises
• MDN Web Docs — Promise.allSettled()
• MDN Web Docs — AbortController