@fortify-ts/circuit-breaker

Circuit breaker pattern implementation for the Fortify-TS resilience library.

Installation

npm install @fortify-ts/circuit-breaker
# or
pnpm add @fortify-ts/circuit-breaker

Features

• State Machine: CLOSED, OPEN, and HALF-OPEN states
• Configurable Thresholds: Max failures, timeout, half-open requests
• Custom Predicates: readyToTrip and isSuccessful callbacks
• State Change Notifications: onStateChange callback
• Automatic Recovery: Transitions from OPEN to HALF-OPEN after timeout

Usage

Basic Usage

import { CircuitBreaker } from '@fortify-ts/circuit-breaker';

const breaker = new CircuitBreaker<Response>({
  maxFailures: 5,
  timeout: 60000, // 60 seconds
});

try {
  const result = await breaker.execute(async (signal) => {
    return fetch('/api/data', { signal });
  });
} catch (error) {
  if (error instanceof CircuitOpenError) {
    console.log('Circuit is open, try again later');
  }
}

Configuration Options

const breaker = new CircuitBreaker<Response>({
  // Maximum failures before opening circuit
  maxFailures: 5,

  // Time in ms before attempting recovery
  timeout: 60000,

  // Requests allowed in half-open state
  halfOpenMaxRequests: 1,

  // Reset counts interval (0 = disabled)
  interval: 0,

  // Custom trip condition
  readyToTrip: (counts) => counts.consecutiveFailures >= 3,

  // Custom success condition
  isSuccessful: (result) => result.ok,

  // State change notification
  onStateChange: (from, to) => {
    console.log(`Circuit state: ${from} -> ${to}`);
  },

  // Optional logger
  logger: myLogger,
});

State Machine

     ┌─────────────────────────────────────────────────┐
     │                                                 │
     ▼                                                 │
  CLOSED ──── failures >= maxFailures ────► OPEN ────►│
     ▲                                        │        │
     │                                        │ timeout
     │                                        ▼        │
     └────── success ◄──────────────────── HALF-OPEN ─┘
                                               │
                                               │ failure
                                               ▼
                                             OPEN

Checking State

// Get current state
const state = breaker.getState(); // 'closed' | 'open' | 'half-open'

// Get request counts
const counts = breaker.getCounts();
console.log(counts.requests, counts.totalSuccesses, counts.totalFailures);

// Reset circuit breaker
breaker.reset();

// Clean up resources
await breaker.close();

Configuration Reference

| Option | Type | Default | Description | |--------|------|---------|-------------| | maxFailures | number | 5 | Failures before opening | | timeout | number | 60000 | Recovery timeout (ms) | | halfOpenMaxRequests | number | 1 | Requests in half-open | | interval | number | 0 | Count reset interval | | readyToTrip | function | - | Custom trip condition | | isSuccessful | function | - | Custom success check | | onStateChange | function | - | State change callback | | logger | FortifyLogger | - | Optional logger |

License

MIT