Stop 02 · Node.js FundamentalsTopics · 10/18

Promises

In short

A Promise is an object that stands for a result that isn't ready yet. Most modern Node APIs return one, and its helpers like Promise.allSettled save you from messy error handling.

An object representing the eventual result of an async operation, with `.then()`/`.catch()` for handling success and failure — the modern foundation of async Node.js code.

The mascot reads a courier receipt next to one parcel on a scooter, one delivered and one being returned.

Think of it like this

The courier tracking receipt

Book a parcel and you get a receipt with a tracking number. It isn't the parcel, it's a promise of one. Right now it's 'in transit', pending. Later it's either 'delivered' (fulfilled) or 'returned to sender' (rejected), and it never changes after that.

Watch it happen

Promise.allSettled on three notifications

sms: pending

email: pending

push: pending

1/5Three notifications start together. Each call returns a promise, and all three are pending.

The big ideas

What you need to know

Three states, settled once

A promise is pending, then fulfilled with a value or rejected with an error. Once settled, it never changes.

Chain with then and catch

.then runs on success, .catch on failure, .finally either way. Each returns a new promise.

Combine many

Promise.all fails fast, allSettled reports everything, race takes the first to settle, any takes the first success.

Node has promise versions

node:fs/promises, node:timers/promises and node:dns/promises give promise-based versions of classic APIs.

See it in code

Walk through the code

1import { setTimeout as sleep } from "node:timers/promises";2 3const send = async (channel, ms, ok = true) => {4  await sleep(ms);5  if (!ok) throw new Error(`${channel} failed`);6  return `${channel} sent`;7};8 9const results = await Promise.allSettled([10  send("sms", 300, false), send("email", 100), send("push", 200),11]);12 13for (const r of results) {14  console.log(r.status, r.status === "fulfilled" ? r.value : r.reason.message);15}

1/4A promise-based sleep, built into Node.

Save as notify.mjs. Results come back in the same order as the input array, no matter which promise finished first.

Save yourself the pain

Common mistakes

Oops

Forgetting to return inside a .then chain, so the next .then gets undefined.

Do this instead

Return the value or promise from each .then, or switch to async/await where this can't happen.

Oops

Using Promise.all when one failure shouldn't cancel the rest.

Do this instead

Promise.all rejects on the first failure. Use Promise.allSettled when you want every outcome.

Your mission

A notification sender

~20 min

Quick check

Promise.all([a, b, c]): b rejects after 50 ms, while a and c succeed after 200 ms. What happens?

Go deeper

1Wrap a callback-based Node API (like `fs.readFile`) in a Promise.
2Practice `Promise.all()` to run multiple async DB/API calls in parallel.
3Learn `Promise.allSettled()` for handling a mix of successes and failures.