Promise Chaining0%

Promise Chaining

Beginner12 min read•Updated: Jul 11, 2026

Promise Chaining in Modern JavaScript

One of the greatest advantages of Promises over callbacks is Promise Chaining. Because .then() always returns a brand-new Promise, you can chain sequential asynchronous operations into a clean, flat, readable pipeline with centralized error handling.

1. How Chaining Works

Whenever you return a value inside a .then() handler, the next .then() receives that value wrapped in a resolved Promise:

JavaScript

1Promise.resolve(5)
.then(num => {
  console.log('Step 1:', num); // 5
  return num * 2;              // Returns 10
})
.then(doubled => {
  console.log('Step 2:', doubled); // 10
  return doubled + 20;             // Returns 30
})
.then(finalSum => {
  console.log('Step 3:', finalSum); // 30
});

2. Returning Promises Inside .then()

If you return a new Promise from inside a .then() callback, the chain will pause until that inner Promise settles:

JavaScript

1function fetchUser(userId) {
2  return Promise.resolve({ id: userId, name: 'Elena' });
3}
4 
5function fetchUserPermissions(userId) {
6  return Promise.resolve(['read', 'write', 'admin']);
7}
8 
9// Flat, sequential asynchronous chain:
10fetchUser(101)
11  .then(user => {
12    console.log(`Fetched user: ${user.name}`);
13    return fetchUserPermissions(user.id); // Returning another Promise!
14  })
15  .then(permissions => {
16    console.log('Fetched permissions:', permissions);
17  })
18  .catch(err => {
19    console.error('Error occurred anywhere in the chain:', err);
20  });

Output

1Execution Timeline:
fetchUser(101) ──────► Fulfilled ({ name: 'Elena' })
                             │
                    fetchUserPermissions(101) ──► Fulfilled (['read', 'write'])
                                                       │
                                                  Final .then()

3. Centralized Error Handling

In a Promise chain, errors trickle down until they find the nearest .catch() handler. A single .catch() at the end can handle errors originating from any preceding step:

JavaScript

1fetchUserProfile()
.then(profile => validateProfile(profile))
.then(validData => saveToDatabase(validData))
.then(record => sendConfirmationEmail(record.email))
.catch(error => {
  // Catches validation failures, database errors, OR email errors!
  console.error('Pipeline failed:', error.message);
});

4. Recovering from Errors in a Chain

If you return a fallback value from inside .catch(), subsequent .then() handlers can continue execution:

JavaScript

1function loadCachedConfig() {
2  return { theme: 'default', offline: true };
3}
4 
5fetchRemoteConfig()
6  .catch(err => {
7    console.warn('Remote config failed, falling back to cache...');
8    return loadCachedConfig(); // Recover by returning fallback
9  })
10  .then(config => {
11    console.log('Active configuration:', config); // Executes successfully!
12  });

5. Parallel Promise Combinators

When operations are independent and do not rely on each other, run them concurrently:

Method	Behavior	Resolves When...	Rejects When...
`Promise.all()`	Fail-fast parallel batch	All fulfill	Any single promise rejects
`Promise.allSettled()`	Complete audit	All settle (fulfilled or rejected)	Never rejects
`Promise.race()`	First responder	First promise settles	First promise settles
`Promise.any()`	First success	First promise fulfills	All promises reject (`AggregateError`)

JavaScript

1// Run 3 independent API requests simultaneously:
2const [users, products, settings] = await Promise.all([
3  fetch('/api/users').then(r => r.json()),
4  fetch('/api/products').then(r => r.json()),
5  fetch('/api/settings').then(r => r.json())
6]);

Interactive Quiz• Knowledge Check

Practice Quiz

Question 1

What does a .then() handler return if it does not contain an explicit return statement?

Question 2

How does Promise.all() behave if one of the promises in the array rejects?

Question 3

Which Promise method waits for all promises to finish and returns an array of status objects ({ status, value/reason }) without rejecting?

Question 4

If an error is thrown inside the first .then() of a 4-step chain, where does control jump?

Question 5

What is the primary difference between Promise.any() and Promise.race()?

Next Lesson

Intro to Async/Await

Continue learning with hands-on practice, examples, and exercises in the upcoming topic.

Related Lessons

Previous Lesson	Next Lesson
Promises Basics	Intro to Async/Await

Practice Quiz

Test your understanding of this lesson with 5 questions. Each question has one correct answer.

Previous Next

PreviousPrevNext