service-fuse

A flexible circuit breaker for async dependencies (services, databases, queues, SDKs)

This library is built for real systems: APIs that sometimes fail, partial outages, maintenance windows, and the need to observe what is happening without guessing.

It is intentionally simple on the surface and flexible underneath.

Why this exists

Most circuit breaker libraries are either too opinionated, hard to observe, hard to extend, or unsafe in strict TypeScript.

This one is designed to be predictable, observable, testable, and safe in both JavaScript and TypeScript.

No background threads. No magic retries. No hidden state.

Features

• Window‑based failure tracking (default)
• Pluggable failure tracking strategies
• In‑memory store by default (custom stores supported)
• Half‑open / probe recovery
• Manual trip support
• Structured events for logging & metrics
• First‑class TypeScript support
• Zero‑config JavaScript usage

Installation

npm install @ron2395/service-fuse

Basic usage

import { createCircuitBreaker } from '@ron2395/service-fuse';

const breaker = createCircuitBreaker({
  config: {
    failureThreshold: 5,
    failureWindow: 10_000,
    openWindowMs: 30_000,
    probeAfterMs: 5_000,
    requiredSuccessStreak: 2,
  },
});

await breaker.execute('payments-api', async () => {
  return callUpstream();
});

Handling open circuits

When a circuit opens, calls are short‑circuited and a CircuitOpenError is thrown immediately.

import { CircuitOpenError } from '<your-package-name>';

try {
  await breaker.execute('payments-api', callUpstream);
} catch (err) {
  if (err instanceof CircuitOpenError) {
    console.log('Retry after:', new Date(err.openUntil));
    return;
  }
  throw err;
}

Probe & recovery

After opening, the circuit allows a single probe request. If it succeeds, the circuit closes. If it fails, the circuit opens again.

This allows safe and gradual recovery.

Events & observability

The breaker emits structured events for logging and metrics.

onEvent(event) {
  switch (event.type) {
    case 'open':
      console.log('Circuit opened', event.identifier);
      break;
    case 'failure':
      console.log('Failure count', event.failureCount);
      break;
  }
}

Custom failure logic

By default, every error counts as a failure.

You can customize this easily.

Example: only fail on 5xx

await breaker.execute('api', async () => {
  const res = await callUpstream();
  if (res.status >= 500) {
    throw new Error('Server error');
  }
  return res;
});

Advanced: custom failure tracker

createCircuitBreaker({
  config,
  createFailureTracker: (cfg) => new MyFailureTracker(cfg),
});

Manual trip

breaker.tripImmediately('payments-api', 'manual_trip');

License

MIT