JavaScript Promises: A Complete Guide

const promise = new Promise((resolve, reject) => {
    // Pending → Fulfilled (resolve called)
    // Pending → Rejected (reject called or error thrown)
---);

promise.then(
    (value) => console.log('Fulfilled:', value),
    (error) => console.log('Rejected:', error)
);

// Wrapping a callback-based API
function readFileAsync(path) {
    return new Promise((resolve, reject) => {
        fs.readFile(path, 'utf8', (err, data) => {
            if (err) reject(err);
            else resolve(data);
        });
    });
---

// Already settled promises
const fulfilled = Promise.resolve('immediate value');
const rejected = Promise.reject(new Error('immediate error'));
// Use Promise.reject sparingly — it creates an unhandled rejection if not caught

// Timers
const delay = Promise.resolve().then(() => {
    return new Promise(resolve => setTimeout(resolve, 1000));
---);

// Three styles of the same pattern
// 1. Thenable chain
fetchUser(id)
    .then(fetchProfile)
    .then(fetchPosts)
    .then(renderProfile)
    .catch(handleError);

// 2. Returning arrays
Promise.all([fetchUser(id), fetchConfig()])
    .then(([user, config]) => ({ user, config }))
    .then(data => render(data));

// 3. Flat chain with error recovery
fetchUser(id)
    .catch(() => ({ id, name: 'Guest' })) // recover from error
    .then(user => fetchPosts(user.id))
    .catch(() => []) // recover: return empty array
    .then(posts => render({ user, posts }));

fetchUser(id)
    .then(user => fetchPosts(user.id))
    .catch(error => {
        console.warn('Failed to fetch posts, using empty array:', error);
        return []; // recover — chain continues as fulfilled
    })
    .then(posts => render({ posts }));

async function loadDashboard(userId) {
    const [user, posts, notifications] = await Promise.all([
        fetchUser(userId),
        fetchPosts(userId),
        fetchNotifications(userId),
    ]);

    return { user, posts, notifications };
---

const results = await Promise.allSettled([
    fetchUser(1),
    fetchPosts(999), // will reject
    fetchConfig(),
]);

for (const result of results) {
    if (result.status === 'fulfilled') {
        console.log('Success:', result.value);
    } else {
        console.warn('Failure:', result.reason);
        // Continue processing — no overall rejection
    }
---

function withTimeout(promise, ms) {
    const timeout = new Promise((_, reject) =>
        setTimeout(() => reject(new Error('Timeout')), ms)
    );
    return Promise.race([promise, timeout]);
---

const data = await withTimeout(fetch(url), 5000);

const fastestSource = await Promise.any([
    fetchFromCDN(),
    fetchFromOrigin(),
    fetchFromMirror(),
]).catch(() => {
    throw new Error('All sources failed');
---);

// Centralized error handling
class AppError extends Error {
    constructor(message, code, context) {
        super(message);
        this.code = code;
        this.context = context;
    }
---

// Error boundary wrapper
async function withErrorHandling(fn, context) {
    try {
        return await fn();
    } catch (error) {
        if (error instanceof AppError) throw error;
        throw new AppError('Operation failed', 500, {
            original: error,
            context,
        });
    }
---

async function safeOperation() {
    try {
        const data = await riskyOperation();
        return data;
    } catch (error) {
        if (error instanceof NetworkError) {
            return await fallbackOperation();
        }
        throw error; // re-throw unknown errors
    }
---

// ❌ Explicit Promise construction when not needed
new Promise((resolve) => {
    fs.readFile(path, (err, data) => {
        if (err) reject(err);
        else resolve(data);
    });
---);

// ✅ Just use the promise-returning API
fs.promises.readFile(path);

// ❌ The explicit promise construction antipattern
function fetchData() {
    return new Promise((resolve) => {
        fetch(url).then(resolve);
    });
---

// ✅ Just return the promise
function fetchData() {
    return fetch(url).then(r => r.json());
---

// ❌ Nesting promises (promise pyramid)
fetchUser().then(user => {
    fetchPosts(user.id).then(posts => {
        console.log(posts);
    });
---);

// ✅ Flat chain
fetchUser()
    .then(user => fetchPosts(user.id))
    .then(posts => console.log(posts));

// There's no standard way to check a promise's state synchronously.
// But you can track state yourself:
function trackable(promise) {
    let state = 'pending';
    const tracked = promise
        .then(value => { state = 'fulfilled'; return value; })
        .catch(error => { state = 'rejected'; throw error; });
    tracked.state = () => state;
    return tracked;
---

async function processInSequence(items) {
    const results = [];
    for (const item of items) {
        // Each iteration waits for the previous to complete
        const result = await processItem(item);
        results.push(result);
    }
    return results;
---

// Using reduce for promise chaining
function sequentialReduce(items) {
    return items.reduce((promise, item) => {
        return promise.then(results => {
            return processItem(item).then(result => {
                return [...results, result];
            });
        });
    }, Promise.resolve([]));
---

async function batchProcess(items, batchSize = 5) {
    const results = [];
    for (let i = 0; i < items.length; i += batchSize) {
        const batch = items.slice(i, i + batchSize);
        const batchResults = await Promise.all(
            batch.map(item => processItem(item))
        );
        results.push(...batchResults);
    }
    return results;
---

function cancellablePromise(fn) {
    let cancel = null;

    const promise = new Promise((resolve, reject) => {
        cancel = () => reject(new Error('Cancelled'));
        fn(resolve, reject);
    });

    return { promise, cancel };
---

// Usage
const { promise, cancel } = cancellablePromise((resolve) => {
    setTimeout(() => resolve('Done'), 5000);
---);

// Cancel after 2 seconds
setTimeout(() => cancel(), 2000);

promise.catch(err => console.log(err.message)); // 'Cancelled'