circuit-breaker

Overview#

The circuit breaker pattern prevents cascading failures: when a downstream service starts failing repeatedly, the breaker opens — subsequent calls short-circuit immediately without hitting the service — then after a cooldown it enters a half-open state to probe recovery.

The critical differentiator is error classification. Traditional implementations (like opossum) treat all errors equally. In practice a card_declined from Stripe is a business error — the service worked correctly — while a connection timeout is an infrastructure failure. The isFailure callback lets you tell them apart: only infra failures count against the breaker, preventing phantom opens caused by expected business rejections.

Failure rate is measured over a configurable sliding window of recent calls (not a fixed time interval), giving a more accurate picture of current health. Built-in retry with exponential backoff + jitter is available for transient errors before the breaker is involved.

States & Lifecycle#

Configuration#

NestJS Integration#

Register the module once, then use the decorator on any service method. The CircuitBreakerRegistry provides pre-configured factories so you do not need to tune thresholds for common patterns.

import { CircuitBreakerModule } from '@backendkit-labs/circuit-breaker/nestjs';

@Module({
  imports: [CircuitBreakerModule.forRoot()],
})
export class AppModule {}

// payment.service.ts
@Injectable()
export class PaymentService {
  @WithCircuitBreaker({ name: 'stripe', failureThreshold: 40, cooldownMs: 30_000 })
  async charge(dto: ChargeDto): Promise<Result<PaymentIntent, ChargeError>> {
    return this.stripeGateway.createCharge(dto);
    // result.error.type === 'circuit_open' when the breaker is open
  }
}

CircuitBreakerRegistry

Instead of tuning individual instances, the registry provides three pre-configured factory methods covering the most common scenarios:

import { CircuitBreakerRegistry } from '@backendkit-labs/circuit-breaker';

const registry = new CircuitBreakerRegistry();

// Pre-tuned for external HTTP — no manual threshold guessing
const stripeBreaker  = registry.getForHttpExternal('stripe');
const dbBreaker      = registry.getForDatabase('postgres');
const orderBreaker   = registry.getForService('order-service');

Examples#

From basic to production-grade — copy and adapt.

import { CircuitBreaker } from '@backendkit-labs/circuit-breaker';

const cb = new CircuitBreaker({
  name: 'stripe',
  failureThreshold: 40,  // open after 40 % failure rate
  sampleSize: 20,        // over the last 20 calls
  cooldownMs: 30_000,    // wait 30 s before probing again
});

const result = await cb.execute(() => stripe.charges.create(dto));

if (result.ok) {
  return result.value;
} else if (result.error.type === 'circuit_open') {
  throw new ServiceUnavailableException('Payment service down');
}

⚖️ vs. Alternatives#

✅ Supported  ·  ❌ Not supported  ·  ⚠️ Partial / workaround needed. Download counts are approximate weekly npm averages.