Promises in JavaScript ⏳

Most people jump straight into async/await without understanding what a Promise really is. A Promise is just an object that represents a value you'll get later. It has three states: pending, fulfilled, and rejected.

This guide will take you from the basics to advanced Promise patterns, helping you understand the foundation of asynchronous JavaScript before diving into async/await.

Table of content

What is a Promise?
The Three States of a Promise
Creating Promises
Using .then(), .catch(), and .finally()
Promise Chaining
Promise.all(), Promise.race(), and Promise.allSettled()
Error Handling in Promises
Advanced Promise Patterns

1. What is a Promise?

A Promise is a JavaScript object that represents the eventual completion (or failure) of an asynchronous operation and its resulting value. Think of it as a placeholder for a value that will be available in the future.

Key Points:

A Promise is an object, not a function or a value
It represents a value that will be available later
It helps you handle asynchronous operations more elegantly than callbacks
Once a Promise is settled (fulfilled or rejected), its state cannot change

promise-basics.js

// A Promise is an object representing a value you'll get later
// It has three states: pending, fulfilled, and rejected

// Creating a Promise
const myPromise = new Promise((resolve, reject) => {
  // Simulate async operation
  setTimeout(() => {
    const success = true;
    if (success) {
      resolve('Operation completed!');  // Fulfilled state
    } else {
      reject('Operation failed!');  // Rejected state
    }
  }, 1000);
});

// Promise states:
// 1. Pending: Initial state, neither fulfilled nor rejected
// 2. Fulfilled: Operation completed successfully
// 3. Rejected: Operation failed

// Using the Promise
myPromise
  .then((result) => {
    console.log(result);  // "Operation completed!"
  })
  .catch((error) => {
    console.error(error);  // "Operation failed!"
  });

// Simple example: Fetching data
const fetchUser = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve({ name: 'John', age: 30 });
  }, 2000);
});

fetchUser.then(user => {
  console.log(user);  // { name: 'John', age: 30 }
});

2. The Three States of a Promise

Every Promise has one of three states:

1. Pending

The initial state. The Promise is neither fulfilled nor rejected. It's waiting for the asynchronous operation to complete.

2. Fulfilled (Resolved)

The operation completed successfully. The Promise has a resulting value.

3. Rejected

The operation failed. The Promise has a reason for the failure.

Important: Once a Promise transitions from pending to either fulfilled or rejected, it cannot change states again. It's immutable.

promise-states.js

// Understanding Promise States

// 1. PENDING - Initial state
const pendingPromise = new Promise((resolve, reject) => {
  // Promise is pending until resolve or reject is called
  console.log('Promise is pending...');
  // Not calling resolve/reject yet - stays pending
});

// 2. FULFILLED - Successfully completed
const fulfilledPromise = Promise.resolve('Success!');
// Immediately fulfilled with value 'Success!'

fulfilledPromise.then(value => {
  console.log(value);  // "Success!"
});

// 3. REJECTED - Failed
const rejectedPromise = Promise.reject('Error occurred!');
// Immediately rejected with error 'Error occurred!'

rejectedPromise.catch(error => {
  console.error(error);  // "Error occurred!"
});

// Checking Promise state (using a helper)
function checkPromiseState(promise) {
  // Note: There's no direct way to check state in JavaScript
  // But we can infer it from behavior
  
  let state = 'pending';
  
  promise
    .then(() => {
      state = 'fulfilled';
      console.log('Promise is fulfilled');
    })
    .catch(() => {
      state = 'rejected';
      console.log('Promise is rejected');
    });
  
  return state;
}

// Example: Promise that transitions from pending to fulfilled
const asyncOperation = new Promise((resolve) => {
  setTimeout(() => {
    resolve('Data loaded');
  }, 1000);
});

console.log('Promise created - state: pending');
asyncOperation.then(result => {
  console.log('Promise resolved - state: fulfilled');
  console.log('Result:', result);
});

3. Creating Promises

You create a Promise using the new Promise() constructor, which takes an executor function with two parameters: resolve and reject.

Executor Function:

resolve(value) - Call this when the operation succeeds
reject(reason) - Call this when the operation fails
The executor runs immediately when the Promise is created

Quick Promise Creation:

Promise.resolve(value) - Creates an immediately fulfilled Promise
Promise.reject(reason) - Creates an immediately rejected Promise

4. Using .then(), .catch(), and .finally()

These are the three main methods for handling Promises:

.then(onFulfilled, onRejected) - Handles fulfilled promises. Returns a new Promise, allowing chaining.
.catch(onRejected) - Handles rejected promises. It's essentially .then(null, onRejected).
.finally(onFinally) - Executes regardless of the outcome (fulfilled or rejected). Useful for cleanup.

promise-then-catch.js

// Using .then() and .catch()

// .then() - handles fulfilled promises
const promise = new Promise((resolve, reject) => {
  setTimeout(() => resolve('Success!'), 1000);
});

promise.then((value) => {
  console.log(value);  // "Success!"
});

// .catch() - handles rejected promises
const failingPromise = new Promise((resolve, reject) => {
  setTimeout(() => reject('Error!'), 1000);
});

failingPromise
  .then((value) => {
    console.log(value);  // Won't execute
  })
  .catch((error) => {
    console.error(error);  // "Error!"
  });

// Chaining .then() calls
Promise.resolve(10)
  .then(value => {
    console.log(value);  // 10
    return value * 2;  // Return value for next .then()
  })
  .then(value => {
    console.log(value);  // 20
    return value + 5;
  })
  .then(value => {
    console.log(value);  // 25
  })
  .catch(error => {
    console.error(error);  // Catches errors from any .then()
  });

// .finally() - executes regardless of outcome
Promise.resolve('Data')
  .then(data => {
    console.log(data);
    return data.toUpperCase();
  })
  .finally(() => {
    console.log('Cleanup: This always runs');
  });

// Error handling in promise chains
function fetchData() {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      const random = Math.random();
      if (random > 0.5) {
        resolve('Data received');
      } else {
        reject('Network error');
      }
    }, 1000);
  });
}

fetchData()
  .then(data => {
    console.log('Success:', data);
    return processData(data);
  })
  .then(processed => {
    console.log('Processed:', processed);
  })
  .catch(error => {
    console.error('Error:', error);
  })
  .finally(() => {
    console.log('Request completed');
  });

5. Promise Chaining

One of the most powerful features of Promises is chaining. Since.then() returns a new Promise, you can chain multiple operations together.

How Chaining Works:

Each .then() returns a new Promise
The return value of a .then() callback becomes the resolved value of the next Promise
Errors propagate down the chain until caught by a .catch()
This allows you to perform sequential asynchronous operations

promise-chaining.js

// Promise Chaining - Sequential async operations

// Basic chaining
fetchUser(1)
  .then(user => {
    console.log('User:', user);
    return fetchPosts(user.id);  // Return next promise
  })
  .then(posts => {
    console.log('Posts:', posts);
    return fetchComments(posts[0].id);
  })
  .then(comments => {
    console.log('Comments:', comments);
  })
  .catch(error => {
    console.error('Error in chain:', error);
  });

// Helper functions
function fetchUser(userId) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({ id: userId, name: 'John' });
    }, 500);
  });
}

function fetchPosts(userId) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve([{ id: 1, title: 'Post 1' }, { id: 2, title: 'Post 2' }]);
    }, 500);
  });
}

function fetchComments(postId) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve([{ id: 1, text: 'Great post!' }]);
    }, 500);
  });
}

// Chaining with transformations
Promise.resolve(5)
  .then(x => {
    console.log('Step 1:', x);
    return x * 2;
  })
  .then(x => {
    console.log('Step 2:', x);
    return x + 10;
  })
  .then(x => {
    console.log('Step 3:', x);
    return x / 2;
  })
  .then(x => {
    console.log('Final:', x);  // 10
  });

// Error propagation in chains
Promise.resolve(10)
  .then(x => {
    if (x > 5) {
      throw new Error('Value too large');
    }
    return x * 2;
  })
  .then(x => {
    console.log('This won't execute');
    return x + 5;
  })
  .catch(error => {
    console.error('Caught error:', error.message);
    return 0;  // Return default value
  })
  .then(x => {
    console.log('After catch:', x);  // 0
  });

6. Promise.all(), Promise.race(), and Promise.allSettled()

These static methods help you work with multiple Promises:

Promise.all([...promises])

Waits for all promises to resolve. Returns an array of results in the same order.

Fails fast: If any promise rejects, the entirePromise.all() rejects immediately.

Promise.race([...promises])

Returns the first promise that settles (fulfills or rejects).

Use case: Timeout patterns, getting the fastest response.

Promise.allSettled([...promises])

Waits for all promises to settle (fulfill or reject).

Never rejects: Returns results for all promises, regardless of outcome. Useful when you need partial results.

promise-all.js

// Promise.all() - Wait for all promises to resolve

// All promises must succeed
const promise1 = Promise.resolve(1);
const promise2 = Promise.resolve(2);
const promise3 = Promise.resolve(3);

Promise.all([promise1, promise2, promise3])
  .then(values => {
    console.log(values);  // [1, 2, 3]
  })
  .catch(error => {
    console.error(error);  // If any promise rejects
  });

// Real-world example: Fetching multiple resources
const fetchUser = fetch('/api/user').then(r => r.json());
const fetchPosts = fetch('/api/posts').then(r => r.json());
const fetchComments = fetch('/api/comments').then(r => r.json());

Promise.all([fetchUser, fetchPosts, fetchComments])
  .then(([user, posts, comments]) => {
    console.log('User:', user);
    console.log('Posts:', posts);
    console.log('Comments:', comments);
  })
  .catch(error => {
    console.error('One or more requests failed:', error);
  });

// Promise.all() fails fast - if one rejects, all fail
const p1 = Promise.resolve('Success 1');
const p2 = Promise.reject('Error 2');
const p3 = Promise.resolve('Success 3');

Promise.all([p1, p2, p3])
  .then(values => {
    console.log(values);  // Won't execute
  })
  .catch(error => {
    console.error(error);  // "Error 2" - fails immediately
  });

// Promise.allSettled() - Wait for all, regardless of outcome
Promise.allSettled([p1, p2, p3])
  .then(results => {
    results.forEach((result, index) => {
      if (result.status === 'fulfilled') {
        console.log(`Promise ${index + 1} succeeded:`, result.value);
      } else {
        console.log(`Promise ${index + 1} failed:`, result.reason);
      }
    });
  });

// Promise.race() - First promise to settle wins
const fastPromise = new Promise(resolve => 
  setTimeout(() => resolve('Fast'), 100)
);
const slowPromise = new Promise(resolve => 
  setTimeout(() => resolve('Slow'), 1000)
);

Promise.race([fastPromise, slowPromise])
  .then(result => {
    console.log(result);  // "Fast" - first to complete
  });

// Use case: Timeout pattern
function fetchWithTimeout(url, timeout = 5000) {
  const fetchPromise = fetch(url);
  const timeoutPromise = new Promise((_, reject) =>
    setTimeout(() => reject(new Error('Timeout')), timeout)
  );
  
  return Promise.race([fetchPromise, timeoutPromise]);
}

fetchWithTimeout('/api/data', 3000)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => {
    if (error.message === 'Timeout') {
      console.error('Request timed out');
    } else {
      console.error('Request failed:', error);
    }
  });

7. Error Handling in Promises

Proper error handling is crucial when working with Promises. Errors can occur in several places:

In the executor function (reject is called)
In a .then() callback (throws an error)
In a rejected Promise

Key Points:

Errors propagate down the chain until caught by a .catch()
A single .catch() can handle errors from multiple.then() calls
Always handle promise rejections to avoid "UnhandledPromiseRejectionWarning"
Promise.allSettled() is useful when you want partial results even if some promises fail

promise-error-handling.js

// Error Handling in Promises

// 1. Basic Error Handling
const promise = new Promise((resolve, reject) => {
  setTimeout(() => {
    reject(new Error('Something went wrong'));
  }, 1000);
});

promise
  .then(result => console.log(result))
  .catch(error => {
    console.error('Caught error:', error.message);
  });

// 2. Error in .then() chain
Promise.resolve(10)
  .then(value => {
    throw new Error('Error in then');
    return value * 2;
  })
  .then(value => {
    console.log('This won't execute');
  })
  .catch(error => {
    console.error('Caught:', error.message);
  });

// 3. Multiple .catch() handlers
Promise.reject('First error')
  .catch(error => {
    console.log('First catch:', error);
    throw 'Second error';
  })
  .catch(error => {
    console.log('Second catch:', error);
  });

// 4. Handling errors in Promise.all()
const promises = [
  Promise.resolve('Success 1'),
  Promise.reject('Error 2'),
  Promise.resolve('Success 3')
];

Promise.all(promises)
  .then(results => {
    console.log(results);  // Won't execute
  })
  .catch(error => {
    console.error('Promise.all failed:', error);
  });

// 5. Using Promise.allSettled() for partial failures
Promise.allSettled(promises)
  .then(results => {
    results.forEach((result, index) => {
      if (result.status === 'fulfilled') {
        console.log(`Promise ${index + 1} succeeded:`, result.value);
      } else {
        console.log(`Promise ${index + 1} failed:`, result.reason);
      }
    });
  });

// 6. Error recovery
function fetchWithFallback(url) {
  return fetch(url)
    .then(response => {
      if (!response.ok) {
        throw new Error('Network error');
      }
      return response.json();
    })
    .catch(error => {
      console.warn('Primary fetch failed, using fallback');
      return fetch('/api/fallback').then(r => r.json());
    });
}

// 7. Try-catch with async/await (for comparison)
async function handleErrors() {
  try {
    const result = await Promise.reject('Error');
    console.log(result);
  } catch (error) {
    console.error('Caught:', error);
  }
}

// 8. Unhandled Promise Rejections
// Always handle promise rejections!
const unhandled = Promise.reject('Unhandled error');
// This will cause "UnhandledPromiseRejectionWarning" in Node.js

// Proper handling:
unhandled.catch(error => {
  console.error('Handled:', error);
});

8. Advanced Promise Patterns

Once you understand the basics, you can use Promises to solve complex problems:

Retry Pattern: Automatically retry failed operations
Sequential Processing: Process items one at a time usingreduce()
Promise Pool: Limit concurrent operations
Cancellable Promises: Cancel long-running operations
Converting Callbacks: Wrap callback-based APIs in Promises

promise-advanced.js

// Advanced Promise Patterns

// 1. Converting Callbacks to Promises
function readFilePromise(filename) {
  return new Promise((resolve, reject) => {
    // Simulating file read
    setTimeout(() => {
      if (filename) {
        resolve(`Content of ${filename}`);
      } else {
        reject(new Error('Filename required'));
      }
    }, 1000);
  });
}

// 2. Retry Pattern
function retryPromise(fn, maxRetries = 3) {
  return new Promise((resolve, reject) => {
    let attempts = 0;
    
    function attempt() {
      fn()
        .then(resolve)
        .catch(error => {
          attempts++;
          if (attempts >= maxRetries) {
            reject(error);
          } else {
            console.log(`Retry attempt ${attempts}`);
            setTimeout(attempt, 1000);
          }
        });
    }
    
    attempt();
  });
}

// Usage
retryPromise(() => fetch('/api/data'))
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Failed after retries:', error));

// 3. Sequential Processing with reduce
const urls = ['/api/user', '/api/posts', '/api/comments'];

urls.reduce((promise, url) => {
  return promise.then(results => {
    return fetch(url)
      .then(response => response.json())
      .then(data => {
        results.push(data);
        return results;
      });
  });
}, Promise.resolve([]))
  .then(allResults => {
    console.log('All data:', allResults);
  });

// 4. Promise Pool (Limit Concurrent Promises)
function promisePool(tasks, limit) {
  const results = [];
  let running = 0;
  let index = 0;
  
  return new Promise((resolve) => {
    function runNext() {
      if (index >= tasks.length && running === 0) {
        resolve(results);
        return;
      }
      
      while (running < limit && index < tasks.length) {
        const currentIndex = index++;
        running++;
        
        tasks[currentIndex]()
          .then(result => {
            results[currentIndex] = result;
          })
          .catch(error => {
            results[currentIndex] = { error };
          })
          .finally(() => {
            running--;
            runNext();
          });
      }
    }
    
    runNext();
  });
}

// 5. Cancellable Promise
function cancellablePromise(executor) {
  let cancel;
  const promise = new Promise((resolve, reject) => {
    cancel = () => {
      reject(new Error('Cancelled'));
    };
    executor(resolve, reject);
  });
  
  promise.cancel = cancel;
  return promise;
}

const task = cancellablePromise((resolve) => {
  setTimeout(() => resolve('Done'), 5000);
});

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

task
  .then(result => console.log(result))
  .catch(error => console.log(error.message));  // "Cancelled"

Key Takeaways

A Promise is an object representing a future value, not the value itself
Promises have three states: pending, fulfilled, andrejected
Once settled, a Promise's state cannot change
.then() returns a new Promise, enabling chaining
Errors propagate down the chain until caught by .catch()
Promise.all() fails fast; Promise.allSettled() waits for all
Understanding Promises is essential before using async/await

💡 Why Learn Promises Before async/await?

async/await is syntactic sugar over Promises. When you use async/await, you're still working with Promises under the hood.

Understanding Promises helps you:

Debug async/await code more effectively
Handle errors properly in async functions
Use Promise methods like Promise.all() when needed
Understand what's happening behind the scenes