Nodejs Advanced Retry System

A lightweight and resilient retry library for Node.js featuring:

• Exponential Backoff
• Optional Jitter
• Circuit Breaker Pattern
• Retry Metrics
• Custom Retry Errors
• Promise-based API
• Production-ready fault tolerance

Perfect for:

• API requests
• Database operations
• External service calls
• Network retry strategies
• Preventing cascading failures

---

Installation

npm install node-retry-system

---

Features

✅ Exponential backoff retry strategy
✅ Optional jitter support
✅ Circuit breaker protection
✅ Custom retry error handling
✅ Promise-based execution
✅ Lightweight and dependency-free

---

Quick Start

Basic Retry

const {
  RetrySystem
} = require("node-retry-system");

const retry = new RetrySystem({
  retry: {
    delay: 1000,
    maxRetries: 3,
    jitter: true
  },
  circuitBreaker: {
    failureThreshold: 5,
    restTimeout: 10000
  }
});

async function fetchData() {
  return "Success";
}

(async () => {
  try {
    const result = await retry.execute(fetchData);
    console.log(result);
  } catch (err) {
    console.error(err);
  }
})();

---

Retry Example

Simulating an unstable API.

const {
  RetrySystem
} = require("node-retry-system");

const retry = new RetrySystem({
  retry: {
    delay: 1000,
    maxRetries: 5,
    jitter: true
  }
});

async function fakeApiCall() {
  return new Promise((resolve, reject) => {
    const success = Math.random() > 0.5;

    setTimeout(() => {
      if (success) {
        resolve({
          status: 200,
          message: "API request successful"
        });
      } else {
        reject({
          status: 500,
          message: "Server error"
        });
      }
    }, 500);
  });
}

(async () => {
  try {
    const response = await retry.execute(
      async () => await fakeApiCall()
    );

    console.log(response);
  } catch (err) {
    console.error(err);
  }
})();

---

API Reference

---

RetrySystem

Combines:

• Exponential Backoff
• Circuit Breaker
• Retry Error Handling

Constructor

new RetrySystem(options)

Options

Property	Type	Description
retry	Object	Retry strategy configuration
circuitBreaker	Object	Circuit breaker configuration

Execute

await retry.execute(fn)

Param	Type	Description
fn	Function	Async function to execute

Returns:

Promise<T>

Throws:

RetryError

---

ExponentialBackoff

Retry strategy using exponentially increasing delays.

Constructor

new ExponentialBackoff(options)

Options

Property	Type	Default	Description
delay	number	1000	Base retry delay (ms)
maxRetries	number	3	Maximum retry attempts
jitter	boolean	false	Randomized delay

Delay Formula

Without jitter:

delay × (2 ^ attempt)

With jitter:

random(0, delay × 2 ^ attempt)

---

CircuitBreaker

Protects failing services from repeated execution.

States

State	Description
CLOSED	Requests flow normally
OPEN	Requests blocked
HALF_OPEN	Trial execution allowed

Constructor

new CircuitBreaker(options)

Options

Property	Type	Default	Description
failureThreshold	number	5	Failures before OPEN
restTimeout	number	10000	Recovery timeout

---

RetryError

Custom error containing retry execution details.

Example:

try {
  await retry.execute(fn);
} catch (err) {
  console.log(err.message);
  console.log(err.attempts);
  console.log(err.duration);
}

---

How It Works

Execution flow:

Request
   │
   ▼
Circuit Breaker
   │
   ▼
Exponential Backoff Retry
   │
   ▼
Success / RetryError

Retry Lifecycle

Attempt 1 → Fail
      ↓
Wait (Backoff)
      ↓
Attempt 2 → Fail
      ↓
Wait (Backoff)
      ↓
Attempt 3 → Success

Circuit breaker lifecycle:

CLOSED
   ↓
Failures exceed threshold
   ↓
OPEN
   ↓
Timeout expires
   ↓
HALF_OPEN
   ↓
Success → CLOSED
Failure → OPEN

---

Error Handling

Example:

try {
  await retry.execute(fetchUsers);
} catch (err) {
  console.error(
    "Operation failed after retries",
    err
  );
}

---

Use Cases

This package is useful for:

• REST API retry handling
• Payment gateway requests
• Database reconnection logic
• Third-party service integrations
• Microservice communication
• Network fault tolerance

---

Development

Clone repository:

git clone [https://github.com/Dipaque/nodejs-retry-system](https://github.com/Dipaque/nodejs-retry-system)

Install dependencies:

npm install

Run tests:

npm test

---

License

MIT License.

---

Contributing

Contributions, issues, and feature requests are welcome.

Feel free to open a pull request or create an issue.

---

Author

Deepak R

GitHub: Deepak R