🚀 Advanced Promises in Node.js

A visual, example-driven, backend-oriented repository that teaches Promise combinators and Custom Promise Wrappers through clean, runnable Node.js examples.

This repo is structured so that:

• 📖 You can understand everything by reading the README alone
• ▶️ You can run each example independently
• 🧠 You clearly see why and when each pattern is used in real backend systems

By the end of this repository, you will understand:

• How Promise combinators actually behave at runtime
• The strengths and limits of each combinator
• Why combinators alone are not sufficient for backend control
• What Custom Promise Wrappers are
• How wrappers are built on top of combinators
• How these patterns appear in production-grade Node.js backends

This repository is example-driven.
Each folder contains a standalone runnable example.

Make sure you have:

• Node.js v18+ (recommended: latest LTS)
• npm

Check versions:

node -v
npm -v

Clone the repository:

git clone https://github.com/Maryam-Skaik/nodejs-promise-patterns.git
cd nodejs-promise-patterns

Install dependencies:

npm install

ℹ️ axios is used to simulate real HTTP requests.

nodejs-promise-patterns/
│
├── package.json
├── package-lock.json
│
├── examples/
│   │
│   ├── 01-promise-all/
│   │   └── index.js
│   │
│   ├── 02-promise-race/
│   │   └── index.js        # timeout + fastest winner
│   │
│   ├── 03-promise-allSettled/
│   │   └── index.js        # batch processing + partial failure
│   │
│   ├── 04-promise-any/
│   │   └── index.js        # fallback services
│   │
│   ├── 05-wrapper-timeout/
│   │   └── index.js
│   │
│   ├── 06-wrapper-retry/
│   │   └── index.js
│   │
│   ├── 07-wrapper-fallback/
│   │   └── index.js
│   │
│   └── 08-wrapper-fail-fast/
│       └── index.js
│
└── README.md

Each folder:

• Contains one clear concept
• Is clean, minimal, and runnable
• Is written in a teaching-friendly style

▶️ Running an Example

From the project root:

node 01-promise-all/index.js

Run any other example by changing the folder name:

node 05-wrapper-timeout/index.js

1. Start with Promise Combinators 01 → 04
2. Understand why they are insufficient alone
3. Move to Custom Promise Wrappers 05 → 08
4. Modify examples: - Change URLs - Adjust timeouts - Increase retry count

A Promise represents an asynchronous operation that can be:

PENDING → RESOLVED
        → REJECTED

In Node.js backend development, promises appear everywhere:

• 🌐 HTTP requests
• 🗄️ Database queries
• 📂 File system operations
• 🔌 External services

This repository assumes you already know async / await.

Promise combinators are built-in coordination tools.

👉 They decide how multiple promises settle together

👉 They do not enforce business rules

📂 01-promise-all/index.js

Rule

✅ resolve only if ALL promises resolve

❌ reject immediately if ANY promise rejects

Mental Model

[A ✅] [B ✅] [C ❌]
        ↓
     ❌ reject

When to use:

• Every operation is mandatory
• Partial success is useless

📂 02-promise-race/index.js

Rule

• First promise to settle wins (resolve OR reject)

Mental Model

[A 🐢] [B ⚡]
        ↓
     B wins

When to use

• ⏱️ Timeouts
• Fastest response wins

This example demonstrates:

• Racing an API call against a timeout
• How rejection can win the race

📂 03-promise-allSettled/index.js

Rule

• Waits for ALL promises
• Returns both resolve and reject results

Mental Model

[A ✅] [B ❌] [C ✅]
        ↓
   ALL results

When to use

• Batch jobs
• Logging failures
• Partial success is acceptable

📂 04-promise-any/index.js

Rule

• First resolve wins
• Rejects only if ALL promises reject

Mental Model

[A ❌] [B ❌] [C ✅]
        ↓
     C wins

When to use

• Fallback services
• Redundant APIs
• High availability

Combinators answer:

“How do promises settle together?”

They do NOT answer:

• ⏱️ How long is too long?
• 🔁 Should we retry?
• 🛑 Should we fail fast?
• 🔄 Should we fallback?

👉 Backend systems need policy + control, not just coordination.

A Custom Promise Wrapper is:

A function that takes a promise (or a function returning a promise), applies rules, and returns a new controlled promise.

Original Promise
      ↓
   Wrapper Logic
      ↓
 Controlled Promise

Wrappers enforce backend behavior and guarantees.

📂 05-wrapper-timeout/index.js

Goal

• Enforce a maximum execution time

Technique

• Race the original promise against a timer

🧠 Uses: Promise.race

📂 06-wrapper-retry/index.js

Goal

• Retry transient failures (network, temporary DB issues)

Technique

• Re-execute promise function with retry limits

🧠 Uses: controlled re-execution + async/await

📂 07-wrapper-fallback/index.js

Goal

• Use alternative services when one fails

Technique

• Try multiple promises, accept first resolve

🧠 Uses: Promise.any

📂 08-wrapper-fail-fast/index.js

Goal

• Abort immediately if any critical operation fails

Technique

• Force strict success requirement

🧠 Uses: Promise.all

🔩 Combinators = low-level coordination

🧠 Wrappers = application-level control

✔ External APIs

✔ Microservices

✔ Batch processing

✔ Fault-tolerant systems

✔ SLA enforcement

🧾 Final Takeaway

🧩 Promise combinators define how promises settle

🧠 Custom Promise Wrappers define how your backend behaves

🚀 Professional Node.js systems rely on both together

This repository is suitable for:

• Teaching
• Mentorship
• Interview preparation
• Real-world backend reference