Promises & async/await Deep Dive

Reviewed & published by Brayan K

A Promise is an object representing a value that will be available later, and async/await is the syntax that lets you work with those future values as if the code ran top to bottom.

Part of the free Node.js course at LearnCodingFast — hands-on lessons with worked examples and the output they print, plus practice exercises and a quick quiz.

By the end of this lesson you'll create promises, chain them with then/catch/finally, write clean async/await with try/catch, combine many promises with all, allSettled, race, and any, choose sequential versus parallel, and modernize callback APIs with util.promisify.

What You'll Learn in This Lesson

• How to create a promise and resolve or reject it
• How then, catch, and finally chain together
• How async/await with try/catch reads cleaner than chains
• Promise.all, allSettled, race, and any — and when to use each
• Why parallel beats sequential for independent work
• How util.promisify modernizes old callback APIs

1️⃣ Creating & Consuming Promises

You create a promise with new Promise((resolve, reject) => {...}). Call resolve(value) on success or reject(error) on failure. Consumers attach .then for the result, .catch for errors, and .finally for cleanup that always runs.

// A Promise represents a value that will exist later (or an error).
function delay(ms, value) {
  return new Promise((resolve) => setTimeout(() => resolve(value), ms));
}

delay(50, 'done!')
  .then((result) => console.log('then:', result))       // success path
  .catch((err) => console.log('catch:', err.message))   // error path
  .finally(() => console.log('finally: always runs'));  // cleanup, always

The same logic reads far more naturally with async/await. Inside an async function, await pauses until the promise settles, and a rejection throws — so ordinary try/catch handles errors.

function fetchUser(id) {
  return new Promise((resolve, reject) => {
    if (id > 0) resolve({ id, name: 'Ada' });
    else reject(new Error('invalid id'));
  });
}

// async/await reads top-to-bottom; try/catch handles rejections.
async function main() {
  try {
    const user = await fetchUser(1);
    console.log('got user:', user.name);
    await fetchUser(-1);            // this rejects -> jumps to catch
  } catch (err) {
    console.log('caught:', err.message);
  }
}

main();

2️⃣ Combining Many Promises

Real apps juggle several async operations at once, and four static helpers cover the common cases. Promise.all waits for all and fails fast if any rejects. Promise.allSettled waits for all and never rejects, reporting each outcome. Promise.race settles with the first to finish either way. Promise.any resolves with the first success.

const ok = (v, ms = 10) => new Promise((res) => setTimeout(() => res(v), ms));
const fail = (msg, ms = 10) => new Promise((_, rej) => setTimeout(() => rej(new Error(msg)), ms));

// Promise.all: waits for ALL; rejects if ANY rejects.
console.log('all:', await Promise.all([ok(1), ok(2), ok(3)]));

// Promise.allSettled: waits for all, never rejects — reports each outcome.
const settled = await Promise.allSettled([ok('A'), fail('B failed')]);
console.log('allSettled:', settled.map((s) => s.status));

// Promise.race: settles with the FIRST to finish (resolve OR reject).
console.log('race:', await Promise.race([ok('fast', 5), ok('slow', 50)]));

// Promise.any: first to RESOLVE; ignores rejections unless all reject.
console.log('any:', await Promise.any([fail('x'), ok('winner', 20)]));

3️⃣ Sequential vs Parallel (and promisify)

One of the most common performance bugs is awaiting independent operations one at a time. If three calls each take 100ms and don't depend on each other, doing them sequentially costs ~300ms; starting them together with Promise.all costs only ~100ms. Await sequentially only when a later step truly needs an earlier result.

const task = (label, ms) => new Promise((res) => setTimeout(() => res(label), ms));

// SEQUENTIAL: each await waits for the previous one. ~300ms total.
async function sequential() {
  const start = Date.now();
  await task('a', 100);
  await task('b', 100);
  await task('c', 100);
  console.log('sequential took ~', Math.round((Date.now() - start) / 100) * 100, 'ms');
}

// PARALLEL: start all three, then await together. ~100ms total.
async function parallel() {
  const start = Date.now();
  await Promise.all([task('a', 100), task('b', 100), task('c', 100)]);
  console.log('parallel took ~', Math.round((Date.now() - start) / 100) * 100, 'ms');
}

await sequential();
await parallel();

Finally, plenty of older APIs still use error-first callbacks. util.promisify wraps one into a promise-returning function so you can await it.

import { promisify } from 'node:util';

// A classic Node-style callback function: (err, result) => ...
function getValueCb(n, callback) {
  setTimeout(() => {
    if (n < 0) callback(new Error('no negatives'));
    else callback(null, n * 2);
  }, 10);
}

// promisify turns it into a promise-returning function you can await.
const getValue = promisify(getValueCb);

console.log('doubled:', await getValue(21));

Your turn. The program below works once you fill in the two blanks marked ___. Follow the 👉 hints, then run it and compare with the expected output.

const fetchPrice = (item) =>
  new Promise((res) => setTimeout(() => res(item === 'apple' ? 3 : 5), 10));

async function main() {
  // 🎯 YOUR TURN — fill each ___ then run it.
  // Fetch BOTH prices in PARALLEL and add them.

  const [apple, banana] = await Promise.___([   // 👉 all
    fetchPrice('apple'),
    fetchPrice('banana'),
  ]);

  console.log('total:', apple ___ banana);       // 👉 + (the plus operator)
}

main();

// ✅ Expected output:
//    total: 8

Mini-Challenge: A Health-Check Report

No blanks this time — just a brief and an outline. Write it yourself, run it, and check your output against the example in the comments. This ties together Promise.allSettled and reading each result's status.

// 🎯 MINI-CHALLENGE: a health-check report
//
// Given check(name, willPass) that resolves with the name when willPass
// is true and rejects with an Error(name) when false:
//   - Run THREE checks together so one failure doesn't stop the others.
//   - Print "OK   <name>" for each that passed and "FAIL <name>" for each
//     that failed.
//   (Hint: Promise.allSettled gives you { status, value/reason } per item.)
//
// const check = (name, willPass) =>
//   new Promise((res, rej) =>
//     setTimeout(() => (willPass ? res(name) : rej(new Error(name))), 10));
//
// Run with: check('db', true), check('cache', false), check('api', true)
//
// ✅ Example output:
//    OK   db
//    FAIL cache
//    OK   api

// your code here

Common Errors (and the fix)

• ❌ Logged "Promise { <pending> }" — You forgot to await (or to use .then). ✅ Await the promise inside an async function.
• ❌ Awaiting in a loop, one at a time — Turns parallel work serial. ✅ Build an array of promises and await Promise.all(...).
• ❌ UnhandledPromiseRejection — A rejection had no handler. ✅ Wrap awaits in try/catch or attach .catch().
• ❌ await outside an async function — SyntaxError in scripts. ✅ Use a .mjs module (top-level await) or wrap in async.
• ❌ Mixing callbacks and promises — Double-resolves and lost errors. ✅ Pick one style; promisify the callbacks first.

Pro Tips

• 💡 Kick off first, await later: call the async functions to start them, store the promises, then await Promise.all([...]) — that's how you parallelize.
• 💡 Always return your promises from a function so callers can await and errors propagate correctly.
• 💡 Build a timeout by racing a task against new Promise((_, r) => setTimeout(() => r(new Error('timeout')), ms)).

📋 Quick Reference — Combinators

🎉 Lesson Complete!

• ✅ A promise resolves with a value or rejects with an error; consume with then/catch/finally
• ✅ async/await + try/catch reads cleaner than long chains
• ✅ all/allSettled/race/any combine many promises by intent
• ✅ Run independent work in parallel with Promise.all — don't await one at a time
• ✅ util.promisify turns error-first callbacks into awaitable functions

Practice quiz

Continue this course

• Previous: The crypto Module
• Next: Checkpoint: Node Core — Combine process, crypto and promises in a CLI build — then a quiz
• Quick reference: Node.js cheat sheet › Async

Frequently asked questions

What is the difference between Promise.all and Promise.allSettled?

Promise.all is all-or-nothing: it resolves with an array of every result once they all succeed, but if any single promise rejects, the whole thing rejects immediately with that error and you lose the other results. Promise.allSettled never rejects — it waits for every promise to finish and gives you an array describing each outcome as { status: 'fulfilled', value } or { status: 'rejected', reason }. Use all when you need every operation to succeed (and want to fail fast); use allSettled when you want a full report even if some fail, like running independent health checks.

When should I run promises sequentially versus in parallel?

Run them in parallel when the operations are independent — fetching three unrelated URLs, for example. Starting them together and awaiting with Promise.all means the total time is roughly the slowest one, not the sum. Run them sequentially (await one, then the next) only when each step depends on the previous step's result, or when you must limit load on a resource. A very common performance bug is awaiting independent calls one at a time in a loop, turning what could be 100ms of parallel work into 300ms or more.

How does error handling work with async/await?

A rejected promise that you await throws at the await point, so you catch it with a normal try/catch around the awaited call. If you don't catch it, the rejection propagates up and becomes an unhandled rejection. With plain promises you handle errors with .catch(). The two styles mix: you can await inside try/catch, or attach .catch() to a promise chain. Just make sure every promise has somewhere its rejection is handled — either a surrounding try/catch on the await, or a .catch() on the chain.

What is util.promisify for?

Many older Node APIs use the error-first callback style: doThing(args, (err, result) => ...). util.promisify wraps such a function so it returns a promise instead, letting you use await and try/catch rather than nesting callbacks. It works for any function whose last parameter is a Node-style (err, value) callback. Most core modules now ship promise versions directly (for example node:fs/promises), so reach for those first; use promisify for third-party or legacy callback APIs that don't offer one.