🤝 Promises

Why Promises?

In the previous lesson you saw callbacks buckle under nesting — the "pyramid of doom" where each async step burrowed one level deeper and the error check was copy-pasted at every layer. A Promise fixes the structure by turning "here's a function to call me back with the result" into "here's an object that represents the result, which you can pass around, chain, and hand error handling to in one place."

Think of the coffee-shop ticket again. The ticket (the Promise) is handed to you immediately. You don't know yet whether it will become a latte or a "sorry, we're out of milk" — but you can already plan what to do in either case, and the shop will honor exactly one of those outcomes. That's the whole idea.

Promises are also the foundation for async/await (next lesson) and the return type of the modern fetch API, so this lesson is load-bearing for everything that follows.

The Three States

A Promise is always in exactly one of three states, and once it leaves pending it can never change again — it is settled for good.

• Pending — the operation is still in progress; no result yet.
• Fulfilled — it succeeded, carrying a value.
• Rejected — it failed, carrying a reason (usually an Error).

Here is the same lifecycle as a state diagram — note there is no path out of the settled states:

Creating a Promise

You build a Promise by passing an executor function to new Promise. The executor receives two functions from the engine — resolve and reject — and you call one of them when your async work finishes.

const myPromise = new Promise((resolve, reject) => {
    // The executor runs immediately and starts the async work
    setTimeout(() => {
        const success = true;                 // pretend this came from a server
        if (success) {
            resolve('Operation successful!');  // -> fulfilled with this value
        } else {
            reject(new Error('Operation failed!')); // -> rejected with this reason
        }
    }, 1000);
});

// Consume it: .then for success, .catch for failure
myPromise
    .then(result => console.log(result))        // "Operation successful!"
    .catch(error => console.error(error.message));

Most of the time you won't write new Promise yourself — APIs like fetch hand you one already. You reach for the constructor mainly to wrap something that isn't Promise-based yet (like a timer or an old callback API), which we do below.

then, catch & finally

Three methods let you react to a Promise. Each returns a new Promise, which is exactly why they chain.

const promise = new Promise((resolve, reject) => {
    setTimeout(() => {
        const n = Math.random();
        n > 0.5 ? resolve(n) : reject(new Error('Number too small'));
    }, 1000);
});

promise
    .then(value => {
        console.log('Success:', value.toFixed(2));
    })
    .catch(error => {
        console.error('Error:', error.message);
    })
    .finally(() => {
        console.log('Done — hide the loading spinner');  // always runs
    });

.finally is perfect for cleanup that must happen regardless of outcome: hiding a loading indicator, closing a connection, re-enabling a button.

Callbacks → Promises

The main reason to hand-write new Promise is to modernize an old callback-based function. Compare the two styles side by side.

Before — error-first callback

function fetchUserDataCallback(userId, callback) {
    setTimeout(() => {
        if (!userId) return callback(new Error('Invalid user ID'), null);
        callback(null, { id: userId, name: 'John Doe' });
    }, 1000);
}

After — returns a Promise

function fetchUserData(userId) {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            if (!userId) return reject(new Error('Invalid user ID'));
            resolve({ id: userId, name: 'John Doe' });
        }, 1000);
    });
}

// The caller is dramatically cleaner:
fetchUserData(123)
    .then(user => console.log('User:', user))
    .catch(error => console.error('Error:', error.message));

function promisify(fn) {
    return (...args) => new Promise((resolve, reject) => {
        fn(...args, (error, result) => {
            error ? reject(error) : resolve(result);
        });
    });
}

// const readFileAsync = promisify(fs.readFile);
// readFileAsync('file.txt', 'utf8').then(console.log).catch(console.error);

Promise Chaining

Here's the payoff. Because every .then returns a new Promise, and because returning a Promise from inside a .then makes the chain wait for it, dependent async steps line up vertically instead of nesting. The same four-step flow that was a pyramid with callbacks becomes a flat, readable ladder.

function fetchUser(id) {
    return new Promise(resolve =>
        setTimeout(() => resolve({ id, name: 'Alice' }), 1000));
}
function fetchPosts(userId) {
    return new Promise(resolve =>
        setTimeout(() => resolve([{ id: 1, userId, title: 'Post 1' }]), 1000));
}
function fetchComments(postId) {
    return new Promise(resolve =>
        setTimeout(() => resolve([{ id: 1, postId, text: 'Great post!' }]), 1000));
}

fetchUser(1)
    .then(user => {
        console.log('User:', user.name);
        return fetchPosts(user.id);          // return a Promise -> chain waits
    })
    .then(posts => {
        console.log('Posts:', posts.length);
        return fetchComments(posts[0].id);
    })
    .then(comments => {
        console.log('Comments:', comments.length);
    })
    .catch(error => {
        console.error('Error somewhere in the chain:', error.message);
    });

Notice the single .catch at the bottom. A rejection anywhere in the chain skips straight to it — one error handler for the whole sequence, instead of one per level.

Combinators: all, race & friends

Chaining runs steps in sequence. When steps are independent, you want them in parallel. The static Promise combinators take an array of Promises and combine them into one.

Promise.all — everything, together

// Fire three independent requests at once, wait for all of them
Promise.all([fetchUser(1), fetchPosts(1), fetchComments(1)])
    .then(([user, posts, comments]) => {
        console.log('All data loaded:', { user, posts, comments });
    })
    .catch(error => {
        // Rejects as soon as ANY input rejects ("fail fast")
        console.error('At least one request failed:', error.message);
    });

Promise.allSettled — everything, report each

// Use when one failure shouldn't sink the others
const jobs = [
    Promise.resolve('Success'),
    Promise.reject(new Error('Failure')),
    Promise.resolve('Another success'),
];

Promise.allSettled(jobs).then(results => {
    results.forEach(r => {
        if (r.status === 'fulfilled') console.log('OK:', r.value);
        else console.log('Failed:', r.reason.message);
    });
});

Promise.race — first to finish wins

// Classic use: a timeout guard around a slow request
function withTimeout(promise, ms) {
    const timeout = new Promise((_, reject) =>
        setTimeout(() => reject(new Error('Timed out')), ms));
    return Promise.race([promise, timeout]);   // whichever settles first
}

withTimeout(fetchUser(1), 3000)
    .then(user => console.log('Got user:', user.name))
    .catch(err => console.error(err.message));   // "Timed out" if too slow

Promise.any is the optimistic cousin of race: it ignores rejections and resolves with the first success, handy for "try several mirrors, take whichever responds first."

Error Handling

A single trailing .catch handles a rejection from anywhere earlier in the chain. Inside it you can branch on the error type to respond appropriately.

class NetworkError extends Error {
    constructor(message) { super(message); this.name = 'NetworkError'; }
}
class ValidationError extends Error {
    constructor(errors) { super('Validation failed'); this.name = 'ValidationError'; this.errors = errors; }
}

fetchUser(1)
    .then(user => fetchPosts(user.id))
    .then(posts => fetchComments(posts[0].id))
    .then(comments => console.log('Loaded', comments.length, 'comments'))
    .catch(error => {
        if (error instanceof NetworkError)      showOfflineMessage();
        else if (error instanceof ValidationError) showValidationErrors(error.errors);
        else                                     showGenericError(error);
    });

Practice & Quiz

function delay(ms) {
    // TODO: return a Promise that resolves after ms
}

delay(2000).then(() => console.log('2 seconds have passed'));

function delay(ms) {
    return new Promise(resolve => setTimeout(resolve, ms));
}
// Bonus: pass a value through
// const delayValue = (ms, v) => new Promise(r => setTimeout(() => r(v), ms));

calculate(5).add(3).multiply(2).subtract(4).divide(2)
    .getResult()
    .then(result => console.log(result));   // 6

function calculate(start) {
    let value = start;
    const api = {
        add(n)      { value += n; return api; },
        subtract(n) { value -= n; return api; },
        multiply(n) { value *= n; return api; },
        divide(n) {
            if (n === 0) throw new Error('Cannot divide by zero');
            value /= n; return api;
        },
        getResult() { return Promise.resolve(value); },
    };
    return api;
}
// calculate(5).add(3).multiply(2).subtract(4).divide(2).getResult()
//   -> resolves to 6

Best Practices & Pitfalls

✅ Do

• Always end a chain with .catch (or handle errors with try/catch under async/await)
• return the Promise or value you want to pass to the next .then
• Reject with an Error object, not a string — you get a stack trace
• Use Promise.all to run independent work in parallel instead of awaiting one by one

❌ Don't

• Nest .then inside .then — that recreates the pyramid you escaped
• Forget return, leaving the next step with undefined
• Wrap something that's already a Promise in new Promise (the "explicit construction antipattern")
• Assume order in Promise.all equals completion order — the results array matches input order regardless of who finishes first

// ❌ Nested — the pyramid sneaks back in
fetchUser(1).then(user => {
    fetchPosts(user.id).then(posts => { /* ... */ });
});

// ✅ Flat — return and continue the chain
fetchUser(1)
    .then(user => fetchPosts(user.id))
    .then(posts => { /* ... */ });

Summary

📚 Additional Resources

• MDN — Promise reference
• MDN — Using promises (guide)
• MDN — fetch(), which returns a Promise

🚀 What's Next?

Promises are clean, but chains of .then still read a little sideways. The next lesson introduces async/await — syntactic sugar over Promises that lets you write asynchronous code that reads top-to-bottom like ordinary synchronous code, complete with familiar try/catch error handling.