Promise chaining in Node.js - Step-by-Step Execution

Concept Flow - Promise chaining

Create initial Promise

↓

Resolve or Reject initial Promise

↓

Call .then() with first handler

↓

Return value or Promise from first handler

↓

Call next .then() with next handler

↓

Repeat until no more .then()

↓

Final resolved value or error handled

This flow shows how promises are created, resolved, and how each .then() handler runs in sequence passing results along.

Execution Sample

Node.js

Promise.resolve(1)
  .then(x => x + 1)
  .then(x => Promise.resolve(x + 1))
  .then(console.log);

This code creates a promise starting with 1, then adds 1 twice, and finally logs the result.

Execution Table

Step	Action	Input Value	Handler Result	Next Promise State	Output
1	Create initial resolved Promise	N/A	Promise resolved with 1	Resolved with 1	N/A
2	First .then() handler runs	1	1 + 1 = 2	Resolved with 2	N/A
3	Second .then() handler runs	2	Returns Promise resolved with 3	Resolved with 3	N/A
4	Third .then() handler runs	3	console.log(3)	Resolved with undefined	3
5	Chain ends	N/A	N/A	N/A	N/A

💡 No more .then() handlers, promise chain completes with final output 3

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	Final
Promise Value	N/A	2	3	undefined	undefined

Key Moments - 3 Insights

Why does the second .then() return a Promise instead of a direct value?

Because the handler returns Promise.resolve(x + 1), the chain waits for this Promise to resolve before continuing, as shown in step 3 of the execution_table.

What happens if a .then() handler returns a direct value instead of a Promise?

The value is automatically wrapped in a resolved Promise, so the next .then() receives that value immediately, like in step 2 where x + 1 returns 2 directly.

Why is the final output logged only after all .then() handlers complete?

Because each .then() waits for the previous Promise to resolve, ensuring the final console.log runs with the fully processed value, as shown in step 4.

Visual Quiz - 3 Questions

Look at the execution_table, what is the Promise state after the first .then() handler runs?

A Resolved with 2

B Resolved with 1

C Resolved with 3

D Pending

💡 Hint

Check the 'Next Promise State' column at step 2 in the execution_table.

At which step does the chain handle a Promise returned inside a .then() handler?

A Step 1

B Step 3

C Step 2

D Step 4

💡 Hint

Look for the step where the handler returns Promise.resolve(x + 1) in the execution_table.

If the second .then() returned x + 1 directly instead of a Promise, how would the 'Next Promise State' at step 3 change?

A It would be Rejected

B It would be Pending

C It would be Resolved with 3 immediately

D It would stay Resolved with 2

💡 Hint

Refer to the variable_tracker and execution_table rows for step 3 to understand Promise resolution.

Concept Snapshot

Promise chaining lets you run async tasks in order.
Each .then() waits for the previous Promise to resolve.
Handlers can return values or Promises.
Returned Promises delay the chain until resolved.
Final .then() gets the last resolved value.
Use chaining to avoid nested callbacks.

Full Transcript

Promise chaining in Node.js means linking multiple asynchronous steps so each waits for the previous to finish. We start with a Promise, then add .then() handlers. Each handler receives the resolved value from the previous Promise. If a handler returns a direct value, it is wrapped in a resolved Promise automatically. If it returns a Promise, the chain waits for it to resolve before moving on. This way, you can run async tasks in sequence without nesting. The final .then() runs after all previous Promises resolve, receiving the final result. This example starts with Promise.resolve(1), adds 1 twice through handlers, and logs the final value 3. The execution table shows each step's input, output, and Promise state, helping beginners see how values flow through the chain.

Practice

1. What is the main purpose of promise chaining in Node.js?

easy

A. To convert synchronous code into asynchronous code

B. To run all asynchronous tasks at the same time

C. To run asynchronous tasks one after another in order

D. To stop all asynchronous tasks immediately

Solution

1. Step 1: Understand asynchronous task execution

   Promise chaining allows tasks to run one after another, waiting for each to finish.

2. Step 2: Identify the purpose of chaining

   Chaining with .then() ensures order, not parallel or immediate stop.

3. Final Answer:

   To run asynchronous tasks one after another in order -> Option C

4. Quick Check:

   Promise chaining = ordered async tasks [OK]

Hint: Promise chaining runs tasks step-by-step, not all at once [OK]

Common Mistakes:

• Thinking promises run in parallel by default
• Confusing chaining with synchronous loops
• Believing chaining stops tasks immediately

2. Which of the following is the correct syntax to chain two promises promise1 and promise2?

easy

A. promise1.then(promise2)

B. promise1.then(promise2())

C. promise1.then.then(promise2)

D. promise1.then(() => promise2())

Solution

1. Step 1: Understand how to pass functions to .then()

   The .then() method expects a function to call when the promise resolves.

2. Step 2: Check each option's syntax

   promise1.then(() => promise2()) correctly passes a function that calls promise2(). Options A and B call promise2() immediately or pass wrong types. promise1.then.then(promise2) has invalid chaining syntax.

3. Final Answer:

   promise1.then(() => promise2()) -> Option D

4. Quick Check:

   Pass a function to then() = promise1.then(() => promise2()) [OK]

Hint: Use a function inside then() to delay calling next promise [OK]

Common Mistakes:

• Calling the next promise immediately inside then()
• Using double then without parentheses
• Passing promise instead of function to then()

3. What will be logged to the console when running this code?

Promise.resolve(5)
  .then(x => x + 1)
  .then(x => { throw new Error('Fail'); })
  .catch(err => 'Caught: ' + err.message)
  .then(x => console.log(x));

medium

A. Caught: Fail

B. Fail

C. 6

D. undefined

Solution

1. Step 1: Follow the promise chain step-by-step

   The first then adds 1 to 5, resulting in 6. The second then throws an error.

2. Step 2: Understand error handling and final output

   The catch catches the error and returns the string 'Caught: Fail'. The last then logs this string.

3. Final Answer:

   Caught: Fail -> Option A

4. Quick Check:

   Error caught and message logged = Caught: Fail [OK]

Hint: Errors jump to catch, then continue chain with catch result [OK]

Common Mistakes:

• Expecting error to stop all logging
• Thinking catch returns undefined
• Ignoring that catch returns a value to next then

4. Identify the error in this promise chain:

fetchData()
  .then(data => processData(data))
  .then(result => console.log(result))
  .catch(console.error())

medium

A. Missing return in first then

B. Incorrect use of catch with immediate function call

C. processData is not a function

D. console.log should be inside catch

Solution

1. Step 1: Check the catch usage

   The catch method expects a function reference, but console.error() calls the function immediately, passing its result (undefined) instead.

2. Step 2: Correct catch usage

   It should be .catch(console.error) without parentheses to pass the function itself.

3. Final Answer:

   Incorrect use of catch with immediate function call -> Option B

4. Quick Check:

   Pass function to catch, not call it immediately [OK]

Hint: Pass function to catch, don't call it with () [OK]

Common Mistakes:

• Calling catch handler immediately instead of passing function
• Forgetting to return promises inside then
• Misplacing console.log inside catch

5. Given these functions:

function step1() { return Promise.resolve(2); }
function step2(x) { return Promise.resolve(x * 3); }
function step3(x) { return x + 4; }

What will this code log?

step1()
  .then(x => step2(x))
  .then(x => step3(x))
  .then(console.log);

hard

A. 10

B. Promise { 10 }

C. undefined

D. Error: step3 must return a Promise

Solution

1. Step 1: Calculate step1 and step2 results

   step1() resolves to 2. Then step2(2) resolves to 6 (2*3).

2. Step 2: Understand step3 return and final log

   step3(6) returns 10 (6+4) synchronously. Since then accepts a value or promise, it passes 10 to next then which logs 10.

3. Final Answer:

   10 -> Option A

4. Quick Check:

   Sync return in then passes value = 10 [OK]

Hint: then can handle sync values; they become resolved promises [OK]

Common Mistakes:

• Expecting step3 to return a Promise always
• Thinking console.log logs a Promise object
• Confusing synchronous return with Promise return