service-fuse

A lightweight and 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: 10,
    failureWindow: 60_000,
    openWindowMs: 120_000,
    probeAfterMs: 30_000,
    requiredSuccessStreak: 3,
  },
});

await breaker.execute('identifier', async () => {
  return callService();
});

Handling open circuits

When a circuit opens, , execution is short-circuited and a CircuitOpenError error is thrown.

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

try {
  await breaker.execute('identifier', callService);
} catch (err) {
  if (err instanceof CircuitOpenError) {
    console.log('Circuit open until:', new Date(err.openUntil));
    return;
  }
  throw err;
}

CircuitOpenError

class CircuitOpenError extends Error {
  identifier: string;
  openUntil: number;
}

Events & Observability

The breaker emits structured events for every important state and transition.

Subscribing to events

const breaker = createCircuitBreaker({
  config,
  onEvent(event) {
    switch (event.type) {
      case 'open':
        console.log('Circuit opened', event.identifier, event.openUntil);
        break;

      case 'failure':
        console.log('Failure count', event.failureCount);
        break;

      case 'short_circuit':
        console.log('Short-circuited until', event.openUntil);
        break;
    }
  },
});

Event Types

All events include:

{
  identifier: string;
  timestamp: number;
}

• attempt

{
  type: 'attempt';
  wasProbe: boolean;
}

• success

{
  type: 'success';
  wasProbe: boolean;
}

• failure

{
  type: 'failure';
  failureCount: number;
  wasProbe: boolean;
  reason?: string;
}

• open

{
  type: 'open';
  reason: 'failure_threshold' | 'probe_failure' | 'manual_trip' | string;
  openUntil: number;
  failureCount: number;
  from: 'closed' | 'half_open';
  metadata?: Record<string, unknown>;
}

• half_open

{
  type: 'half_open';
  from: 'open';
}

• close

{
  type: 'close';
  from: 'half_open' | 'open';
}

• short_circuit

{
  type: 'short_circuit';
  openUntil: number;
}

Manual Trip

You can force-open a circuit as needed:

breaker.tripImmediately('identifier', 'manual_trip', {
   maintenance: true
})

This:

• Opens the circuit.
• Emits an open event.
• Prevents execution until recovery.

Probe/Recovery Behavior

When a circuit opens:

1. Requests are short-circuited.
2. After probeAfterMs, the circuit enters half-open.
3. One request is allowed as a probe.
4. If probe succeeds → circuit closes.
5. If probe fails → circuit stays open.
6. Probe behavior is customizable via config.

Custom failure logic

By default, every error counts as a failure in a rolling time window.

However, this is customizable.

Example: only fail on 5xx

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

Advanced: custom failure tracker

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

• Any tracker implementing:

interface FailureTracker {
  recordFailure(timestamp: number): void;
  recordSuccess(timestamp: number): void
  shouldTrip(timestamp: number): boolean;
  reset(): void;
}

Stores

A store is responsible for persisting circuit state per identifier. Circuit state storage is pluggable.

A store must:

• return the same state object for a given identifier
• preserve state across calls
• not mutate state unexpectedly

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

createCircuitBreaker({
   config,
   store: new MemoryStore(), //default
})

Available options are:

• Memory Store (default).
• Hybrid Store (Redis for state + Memory for failures)
• Custom Store (Own implementation)

Custom Store

[!NOTE] The default MemoryStore is suitable for single-process usage. [!WARNING] For multi-process or distributed systems, implement a custom store (e.g. Redis-backed).

[!TIP] A distributed store implementation will be added to future versions.

JavaScript Support

Out of the box support for JavaScipt:

const { createCircuitBreaker } = require('@ron2395/service-fuse');

const breaker = createCircuitBreaker({ config });

breaker.execute('identifier', async () => {
  return callService();
});

License

MIT