EvoHeal SDK

EvoHeal is a production-grade, self-healing backend SDK for Node.js. It automatically detects failures, classifies errors, and applies intelligent recovery strategies to prevent cascading system failures.

Features

• ** Universal Wrapper**: Wrap any async function (API calls, DB queries) with a single line.
• ** Intelligent Classification**: Distinguishes between TRANSIENT (retryable), LOGIC (bugs), and RESOURCE errors.
• ** Smart Retries**: Exponential backoff with jitter to prevent thundering herd problems.
• ** Circuit Breaker**: Automatically blocks traffic to failing services to allow them to recover.
• ** Fallback Execution**: Gracefully degrade by returning cached data or default values when things go wrong.
• ** Human-Readable Logging**: Clear logs explaining why something failed and what EvoHeal did about it.

Installation

npm install evoheal
# or locally linked

Quick Start

const { wrap } = require('evoheal');

// 1. Define your potentially unstable function
const fetchUserData = async (userId) => {
  // ... make API call
};

// 2. Wrap it with EvoHeal
const safeFetch = wrap(fetchUserData, {
  name: 'FetchUser',
  retry: true,
  retryCount: 3,
  retryDelay: 1000,
  fallback: () => ({ id: 'guest', name: 'Guest User' }), // Graceful degradation
  circuitBreaker: true
});

// 3. Use it normally
const user = await safeFetch('123');

Documentation

• API Reference
• Architecture & Flowchart

Strategies Explained

1. Retry

Retries TRANSIENT errors (network timeouts, 503s) using exponential backoff.

• Ignores LOGIC errors (syntax errors, bad arguments) to avoid wasting resources on bugs.

2. Circuit Breaker

Prevents system overload by "opening the circuit" when failures exceed a threshold.

• Closed: Normal operation.
• Open: Fails immediately (fast failure) to protect downstream services.
• Half-Open: Allows a single test request to check if the service has recovered.

3. Fallback

The last line of defense. If retries fail or the circuit is open, the fallback function is executed to provide a default value (e.g., cached data).

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | name | string | function name | Identifier for logs and circuit breaker keys. | | retry | boolean | false | Enable retry strategy. | | retryCount | number | 3 | Maximum number of retry attempts. | | retryDelay | number | 1000 | Initial delay in ms. | | circuitBreaker | boolean | false | Enable circuit breaker. | | failureThreshold | number | 5 | Failures before opening circuit. | | cooldownInterval | number | 10 | Seconds to wait before Half-Open state. | | fallback | function | null | Function to call if all else fails. |

Limitations

• In-Memory Store: Currently, circuit breaker state is stored in-memory. This means state is not shared across multiple Node.js processes/instances. Redis support is planned for v2.
• Node.js Only: Designed specifically for Node.js backend environments.

License

ISC