@philiprehberger/circuit-breaker

Circuit breaker pattern for fault-tolerant async service calls.

Installation

npm install @philiprehberger/circuit-breaker

Usage

import { circuitBreaker } from '@philiprehberger/circuit-breaker';

const fetchUser = async (id: string) => {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error('Request failed');
  return res.json();
};

const cb = circuitBreaker(fetchUser, {
  threshold: 3,
  timeout: 10000,
});

try {
  const user = await cb.fire('user-123');
  console.log(user);
} catch (err) {
  console.error('Call failed:', err);
}

Fallback

import { circuitBreaker } from '@philiprehberger/circuit-breaker';

const cb = circuitBreaker(fetchUser, {
  threshold: 3,
  timeout: 10000,
  fallback: (id) => ({ id, name: 'Cached User' }),
});

// When the circuit is open, the fallback is called instead of rejecting
const user = await cb.fire('user-123');

State Callbacks

import { circuitBreaker } from '@philiprehberger/circuit-breaker';

const cb = circuitBreaker(fetchUser, {
  threshold: 5,
  timeout: 30000,
  onOpen: () => console.log('Circuit opened — too many failures'),
  onHalfOpen: () => console.log('Circuit half-open — testing recovery'),
  onClose: () => console.log('Circuit closed — service recovered'),
});

Admin & Stats

import { circuitBreaker } from '@philiprehberger/circuit-breaker';

const cb = circuitBreaker(fetchUser);

cb.forceOpen();   // trip the breaker manually
cb.forceClose();  // close it again

if (cb.isOpen()) {
  return cachedUser;
}

console.log(cb.stats); // { failures, successes, lastFailureAt }

API

| Function / Property | Description | |---------------------|-------------| | circuitBreaker(fn, options?) | Wrap an async function with circuit breaker logic | | .fire(...args) | Call the wrapped function (respects circuit state) | | .state | Current circuit state: 'closed', 'open', or 'half-open' | | .stats | { failures, successes, lastFailureAt } snapshot | | .isOpen() / .isClosed() / .isHalfOpen() | State predicates | | .forceOpen() | Force the circuit open | | .forceClose() | Force the circuit closed | | .reset() | Reset to closed state and clear stats |

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | threshold | number | 5 | Failures before opening the circuit | | timeout | number | 30000 | Milliseconds before trying half-open | | fallback | function | undefined | Called instead of rejecting when open | | onOpen | function | undefined | Called when circuit opens | | onClose | function | undefined | Called when circuit closes | | onHalfOpen | function | undefined | Called when circuit enters half-open |

Development

npm install
npm run build
npm test
npm run typecheck

Support

If you find this project useful:

⭐ Star the repo

🐛 Report issues

💡 Suggest features

❤️ Sponsor development

🌐 All Open Source Projects

💻 GitHub Profile

🔗 LinkedIn Profile

License

MIT