9.2 Promises

Introduction

A Promise is an object representing the eventual completion or failure of an asynchronous operation. Promises provide a cleaner alternative to callbacks for handling async code.

┌─────────────────────────────────────────────────────────────┐
│                     PROMISE STATES                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│                      ┌──────────────┐                       │
│                      │   PENDING    │                       │
│                      │  (initial)   │                       │
│                      └──────┬───────┘                       │
│                             │                               │
│              ┌──────────────┴──────────────┐                │
│              │                             │                │
│              ▼                             ▼                │
│     ┌──────────────┐              ┌──────────────┐          │
│     │  FULFILLED   │              │   REJECTED   │          │
│     │  (resolved)  │              │   (error)    │          │
│     └──────────────┘              └──────────────┘          │
│                                                             │
│  • A promise is settled (fulfilled or rejected) only once   │
│  • Once settled, the state cannot change                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Creating Promises

The Promise Constructor

const promise = new Promise((resolve, reject) => {
  // Async operation
  const success = true;

  if (success) {
    resolve('Operation completed!'); // Fulfill the promise
  } else {
    reject(new Error('Operation failed!')); // Reject the promise
  }
});

Basic Example

function fetchData(url) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (url) {
        resolve({ data: 'Sample data', url });
      } else {
        reject(new Error('URL is required'));
      }
    }, 1000);
  });
}

// Using the promise
fetchData('/api/users')
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

---

Consuming Promises

.then() Method

promise
  .then((value) => {
    // Handle fulfilled state
    console.log('Success:', value);
    return value.toUpperCase(); // Can return new value
  })
  .then((upperValue) => {
    // Chained - receives previous return value
    console.log('Uppercase:', upperValue);
  });

.catch() Method

promise
  .then((value) => {
    console.log(value);
    throw new Error('Something went wrong!');
  })
  .catch((error) => {
    // Handles any error in the chain
    console.error('Error:', error.message);
  });

.finally() Method

promise
  .then((result) => console.log(result))
  .catch((error) => console.error(error))
  .finally(() => {
    // Always runs, regardless of outcome
    console.log('Cleanup complete');
  });

┌─────────────────────────────────────────────────────────────┐
│                    PROMISE METHODS                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  promise                                                    │
│      .then(onFulfilled)      // Handle success              │
│      .then(onFulfilled, onRejected)  // Both handlers       │
│      .catch(onRejected)      // Handle errors               │
│      .finally(onFinally)     // Always runs                 │
│                                                             │
│  Chain Flow:                                                │
│  ┌───────┐    ┌───────┐    ┌───────┐    ┌─────────┐        │
│  │ then  │───►│ then  │───►│ catch │───►│ finally │        │
│  └───────┘    └───────┘    └───────┘    └─────────┘        │
│       │            │            ▲                           │
│       │            └────────────┘                           │
│       │          (error propagates)                         │
│       └──────────────────────────►                          │
│              (value passes through)                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Promise Chaining

Sequential Operations

// ✅ Clean chaining - solves callback hell!
getUser(userId)
  .then((user) => {
    console.log('User:', user);
    return getOrders(user.id);
  })
  .then((orders) => {
    console.log('Orders:', orders);
    return getOrderDetails(orders[0].id);
  })
  .then((details) => {
    console.log('Details:', details);
  })
  .catch((error) => {
    // Single error handler for entire chain
    console.error('Error:', error);
  });

Returning Values

Promise.resolve(5)
  .then((x) => x * 2) // Returns 10
  .then((x) => x + 3) // Returns 13
  .then((x) => console.log(x)); // Logs: 13

Returning Promises

Promise.resolve('start')
  .then((value) => {
    return new Promise((resolve) => {
      setTimeout(() => resolve(value + ' → step1'), 100);
    });
  })
  .then((value) => {
    return new Promise((resolve) => {
      setTimeout(() => resolve(value + ' → step2'), 100);
    });
  })
  .then((value) => console.log(value));
// Logs: "start → step1 → step2"

---

Static Methods

Promise.resolve() and Promise.reject()

// Create resolved promise
const resolved = Promise.resolve('immediate value');
resolved.then((v) => console.log(v)); // "immediate value"

// Create rejected promise
const rejected = Promise.reject(new Error('immediate error'));
rejected.catch((e) => console.error(e.message)); // "immediate error"

Promise.all()

Waits for all promises to fulfill (or any to reject):

const promises = [
  fetch('/api/users'),
  fetch('/api/posts'),
  fetch('/api/comments'),
];

Promise.all(promises)
  .then(([users, posts, comments]) => {
    console.log('All data loaded!');
  })
  .catch((error) => {
    console.error('One or more requests failed:', error);
  });

┌─────────────────────────────────────────────────────────────┐
│                     Promise.all()                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Promise 1 ────────────► ✓                                  │
│  Promise 2 ────────────────────► ✓       ───► [R1, R2, R3]  │
│  Promise 3 ────────► ✓                        All results   │
│                                                             │
│  BUT if any fails:                                          │
│                                                             │
│  Promise 1 ────────────► ✓                                  │
│  Promise 2 ────────────────────► ✗       ───► Error         │
│  Promise 3 ────────► ✓                        Fast-fail     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Promise.allSettled()

Waits for all promises to settle (no short-circuit):

const promises = [
  Promise.resolve(1),
  Promise.reject(new Error('fail')),
  Promise.resolve(3),
];

Promise.allSettled(promises).then((results) => {
  console.log(results);
  // [
  //   { status: 'fulfilled', value: 1 },
  //   { status: 'rejected', reason: Error: fail },
  //   { status: 'fulfilled', value: 3 }
  // ]
});

Promise.race()

Returns first settled promise (fulfilled or rejected):

const promises = [
  new Promise((r) => setTimeout(() => r('slow'), 500)),
  new Promise((r) => setTimeout(() => r('fast'), 100)),
];

Promise.race(promises).then((result) => {
  console.log(result); // "fast"
});

Promise.any()

Returns first fulfilled promise (ignores rejections):

const promises = [
  Promise.reject(new Error('Error 1')),
  new Promise((r) => setTimeout(() => r('Success!'), 100)),
  Promise.reject(new Error('Error 2')),
];

Promise.any(promises)
  .then((result) => console.log(result)) // "Success!"
  .catch((error) => console.error(error)); // AggregateError if all reject

┌─────────────────────────────────────────────────────────────┐
│                 STATIC METHODS COMPARISON                   │
├─────────────────┬───────────────────────────────────────────┤
│ Method          │ Behavior                                  │
├─────────────────┼───────────────────────────────────────────┤
│ Promise.all     │ All fulfill → array of results           │
│                 │ Any reject → first rejection             │
├─────────────────┼───────────────────────────────────────────┤
│ Promise.allSettled │ Wait for all → array of outcomes      │
│                    │ Never short-circuits                  │
├─────────────────┼───────────────────────────────────────────┤
│ Promise.race    │ First to settle (fulfilled or rejected)  │
├─────────────────┼───────────────────────────────────────────┤
│ Promise.any     │ First to fulfill                         │
│                 │ All reject → AggregateError              │
└─────────────────┴───────────────────────────────────────────┘

---

Error Handling

Error Propagation

Promise.resolve()
  .then(() => {
    throw new Error('Error in step 1');
  })
  .then(() => {
    console.log("This won't run");
  })
  .then(() => {
    console.log("This won't run either");
  })
  .catch((error) => {
    console.error('Caught:', error.message);
    // Error handled, chain continues
    return 'recovered';
  })
  .then((value) => {
    console.log('Continued with:', value); // "recovered"
  });

Re-throwing Errors

promise
  .catch((error) => {
    if (error.code === 'RETRY') {
      return retryOperation(); // Handle specific error
    }
    throw error; // Re-throw others
  })
  .catch((error) => {
    console.error('Final error handler:', error);
  });

Multiple Catch Blocks

fetchUser(id)
  .then((user) => validateUser(user))
  .catch((error) => {
    // Handle validation errors
    console.log('Validation failed, using default');
    return defaultUser;
  })
  .then((user) => saveUser(user))
  .catch((error) => {
    // Handle save errors
    console.error('Failed to save:', error);
  });

---

Common Patterns

Converting Callbacks to Promises

// Callback-based function
function readFileCallback(path, callback) {
  // ... callback(error, data)
}

// Promise wrapper
function readFile(path) {
  return new Promise((resolve, reject) => {
    readFileCallback(path, (error, data) => {
      if (error) reject(error);
      else resolve(data);
    });
  });
}

// Node.js util.promisify
const { promisify } = require('util');
const readFilePromise = promisify(readFileCallback);

Timeout Pattern

function timeout(ms) {
  return new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Timeout')), ms);
  });
}

function fetchWithTimeout(url, ms) {
  return Promise.race([fetch(url), timeout(ms)]);
}

fetchWithTimeout('/api/data', 5000)
  .then((response) => response.json())
  .catch((error) => console.error(error.message));

Retry Pattern

function retry(fn, attempts = 3, delay = 1000) {
  return fn().catch((error) => {
    if (attempts <= 1) throw error;
    return new Promise((r) => setTimeout(r, delay)).then(() =>
      retry(fn, attempts - 1, delay)
    );
  });
}

retry(() => fetch('/api/flaky-endpoint'), 3, 1000)
  .then((response) => console.log('Success!'))
  .catch((error) => console.error('Failed after 3 attempts'));

Sequential Promise Execution

// Process array items sequentially
function sequential(items, asyncFn) {
  return items.reduce((promise, item) => {
    return promise.then((results) => {
      return asyncFn(item).then((result) => [...results, result]);
    });
  }, Promise.resolve([]));
}

// Usage
const urls = ['/api/1', '/api/2', '/api/3'];
sequential(urls, (url) => fetch(url).then((r) => r.json())).then((results) =>
  console.log(results)
);

---

Promise vs Callback Comparison

┌─────────────────────────────────────────────────────────────┐
│              CALLBACKS vs PROMISES                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  CALLBACKS                        PROMISES                  │
│  ─────────                        ────────                  │
│                                                             │
│  getUser(id, (err, user) => {    getUser(id)               │
│    if (err) handleError(err);       .then(user =>          │
│    getOrders(user.id, (err,           getOrders(user.id))  │
│                       orders) => {   .then(orders =>       │
│      if (err) handleError(err);        getDetails(         │
│      getDetails(orders[0].id,            orders[0].id))    │
│                (err, details) => {   .then(details =>      │
│        if (err) handleError(err);      console.log(        │
│        console.log(details);             details))         │
│      });                             .catch(handleError);  │
│    });                                                      │
│  });                                                        │
│                                                             │
│  ❌ Nested                         ✅ Flat                  │
│  ❌ Error handling repeated        ✅ Single catch          │
│  ❌ Hard to compose                ✅ Chainable             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

Common Mistakes

1. Forgetting to Return

// ❌ Wrong - promise not returned
promise
  .then((value) => {
    anotherPromise(value); // Not returned!
  })
  .then((result) => {
    console.log(result); // undefined!
  });

// ✅ Correct
promise
  .then((value) => {
    return anotherPromise(value);
  })
  .then((result) => {
    console.log(result); // Actual result
  });

2. Nested .then() (Promise Hell)

// ❌ Wrong - recreating callback hell
promise.then((a) => {
  return promiseB(a).then((b) => {
    return promiseC(b).then((c) => {
      return c;
    });
  });
});

// ✅ Correct - flat chain
promise
  .then((a) => promiseB(a))
  .then((b) => promiseC(b))
  .then((c) => c);

3. Not Handling Rejections

// ❌ Unhandled rejection
promise.then((result) => console.log(result));
// If promise rejects, error is swallowed!

// ✅ Always add .catch()
promise
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

---

Summary

---

What's Next?

In the next section, we'll learn about async/await - syntactic sugar that makes promises even easier to work with:

// Preview: async/await
async function loadData() {
  try {
    const user = await getUser(id);
    const orders = await getOrders(user.id);
    const details = await getDetails(orders[0].id);
    console.log(details);
  } catch (error) {
    console.error(error);
  }
}