Promises

Learning objectives#

• Create promises and consume them with then/catch/finally
• Chain dependent steps
• Use promise-based core modules
• Handle unhandled rejections

Explanation#

A promise is pending, then either fulfilled (with a value) or rejected (with an error) — once.

Create one with new Promise((resolve, reject) => ...). Usually you get promises from APIs instead: fs/promises, fetch, database drivers.

then(fn) receives the value and returns a new promise, so you can chain steps; catch(fn) handles errors from any earlier step; finally(fn) runs either way (close connections, hide spinners).

Combinators: Promise.all (all succeed), allSettled (all finish), race (first to settle), any (first to succeed).

An unhandled rejection crashes Node by default. Always end chains with catch (or use try/catch with await), and log process "unhandledRejection" events as a safety net.

Syntax#

1getUser(7)
2  .then(user => getOrders(user.id))
3  .then(orders => console.log(orders.length))
4  .catch(err => console.error(err.message))
5  .finally(() => db.close());

Code example: Creating, chaining and combining promises#

1import { setTimeout as delay } from 'node:timers/promises';
2

3function checkStock(product, qty) {
4  return new Promise((resolve, reject) => {
5    setTimeout(() => {
6      if (qty <= product.stock) resolve({ ...product, reserved: qty });
7      else reject(new Error(`Only ${product.stock} ${product.name} left`));
8    }, 30);
9  });
10}
11

12const pen = { name: 'Pen', price: 20, stock: 10 };
13

14// Chain: each then receives the previous result
15checkStock(pen, 3)
16  .then(item => item.price * item.reserved)
17  .then(total => console.log('Total:', total))
18  .catch(err => console.log('Failed:', err.message))
19  .finally(() => console.log('Stock check 1 finished'));
20

21await delay(50);
22

23checkStock(pen, 30)
24  .then(item => console.log('Reserved', item.reserved))
25  .catch(err => console.log('Failed:', err.message))
26  .finally(() => console.log('Stock check 2 finished'));
27

28await delay(50);
29

30// Combinators
31const fast = delay(10, 'fast mirror');
32const slow = delay(100, 'slow mirror');
33console.log('race →', await Promise.race([fast, slow]));
34console.log('any  →', await Promise.any([Promise.reject(new Error('down')), delay(20, 'backup')]));

Total: 60
Stock check 1 finished
Failed: Only 10 Pen left
Stock check 2 finished
race → fast mirror
any  → backup

This example is illustrative. Copy or download it and run it in your own environment; the expected output is shown above.

Step-by-step explanation#

1. checkStock wraps a timer in new Promise, resolving or rejecting once.
2. The first chain computes the total in a then and prints it; finally runs at the end.
3. The second check rejects, so the then is skipped and catch handles the error.
4. timers/promises provides a promise-based setTimeout (delay).
5. race returns the first to settle; any returns the first to succeed, ignoring rejections.

Real-world use case#

Common mistakes#

Best practices#

• Return promises from then callbacks
• End every chain with catch
• Use finally for cleanup
• Prefer promise-based core modules

Remember this#

Practice exercise#

1const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
2

3console.log('A');
4await sleep(100);
5console.log('B');

Mini quiz#

Want more? Practise all Node.js MCQs · Node.js interview questions

Related topics#

My notes#

Saved in this browser.