JavaScript Promises: A Complete Guide

What are Promises?

A Promise is an object representing the eventual completion or failure of an asynchronous operation. It allows you to write asynchronous code that looks synchronous, making it easier to read and maintain.

// Creating a simple promise
const myPromise = new Promise((resolve, reject) => {
  // Asynchronous operation
  setTimeout(() => {
    const success = true;
    
    if (success) {
      resolve('Operation completed successfully!');
    } else {
      reject('Operation failed!');
...

Promise States

A promise can be in one of three states:

• Pending: Initial state, neither fulfilled nor rejected
• Fulfilled: Operation completed successfully
• Rejected: Operation failed

const promise = new Promise((resolve, reject) => {
  console.log('Promise created - State: Pending');
  
  setTimeout(() => {
    const random = Math.random();
    if (random > 0.5) {
      resolve('Success!'); // State: Fulfilled
    } else {
      reject('Error!'); // State: Rejected
    }
...

Promise Methods: then(), catch(), finally()

const fetchData = () => {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      const data = { id: 1, name: 'John Doe' };
      resolve(data);
      // reject(new Error('Network error'));
    }, 1000);
  });
};

...

Promise Chaining

Promises can be chained to perform sequential asynchronous operations. Each then() returns a new promise, allowing for clean sequential code.

const getUser = (id) => {
  return new Promise((resolve) => {
    setTimeout(() => resolve({ id, name: 'User ' + id }), 500);
  });
};

const getPosts = (userId) => {
  return new Promise((resolve) => {
    setTimeout(() => resolve(['Post 1', 'Post 2', 'Post 3']), 500);
  });
...

Promise.all() - Running Promises in Parallel

Promise.all() takes an array of promises and returns a single promise that resolves when all promises in the array have resolved, or rejects if any promise rejects.

const promise1 = new Promise(resolve => setTimeout(() => resolve('First'), 1000));
const promise2 = new Promise(resolve => setTimeout(() => resolve('Second'), 2000));
const promise3 = new Promise(resolve => setTimeout(() => resolve('Third'), 500));

Promise.all([promise1, promise2, promise3])
  .then(results => {
    console.log('All promises resolved:', results);
    // Output: ['First', 'Second', 'Third']
  })
  .catch(error => {
...

Promise.race() - First to Complete

Promise.race() returns a promise that resolves or rejects as soon as one of the promises in the array resolves or rejects.

const slowPromise = new Promise(resolve => 
  setTimeout(() => resolve('Slow'), 3000));

const fastPromise = new Promise(resolve => 
  setTimeout(() => resolve('Fast'), 1000));

const failingPromise = new Promise((resolve, reject) => 
  setTimeout(() => reject('Failed'), 500));

Promise.race([slowPromise, fastPromise])
...

Promise.allSettled() - Wait for All to Complete

Promise.allSettled() waits for all promises to settle (either resolve or reject) and returns an array of objects describing each promise's outcome.

const promises = [
  Promise.resolve('Success 1'),
  Promise.reject('Error 1'),
  Promise.resolve('Success 2'),
  new Promise(resolve => setTimeout(() => resolve('Success 3'), 1000))
];

Promise.allSettled(promises)
  .then(results => {
    results.forEach((result, index) => {
...

Error Handling Best Practices

// ❌ Bad: No error handling
function riskyOperation() {
  return fetch('/api/data');
}

// ✅ Good: Proper error handling
function safeOperation() {
  return fetch('/api/data')
    .then(response => {
      if (!response.ok) {
...

Converting Callbacks to Promises

// Original callback-based function
function readFile(path, callback) {
  // Simulate async file reading
  setTimeout(() => {
    if (Math.random() > 0.1) {
      callback(null, 'File content');
    } else {
      callback(new Error('File not found'));
    }
  }, 1000);
...

Common Promise Patterns

function retryPromise(fn, maxRetries = 3, delay = 1000) {
  return new Promise((resolve, reject) => {
    function attempt(retriesLeft) {
      fn()
        .then(resolve)
        .catch(error => {
          if (retriesLeft > 0) {
            setTimeout(() => attempt(retriesLeft - 1), delay);
          } else {
            reject(error);
...

function withTimeout(promise, timeoutMs) {
  const timeoutPromise = new Promise((_, reject) => {
    setTimeout(() => reject(new Error('Operation timed out')), timeoutMs);
  });
  
  return Promise.race([promise, timeoutPromise]);
}

// Usage
const slowOperation = new Promise(resolve => 
...

Real-World Example: API Calls

class ApiService {
  constructor(baseURL) {
    this.baseURL = baseURL;
  }

  request(endpoint, options = {}) {
    const url = `${this.baseURL}${endpoint}`;
    
    return fetch(url, {
      headers: {
...