TypeScripttypescriptresiliencecircuit-breakermicroservicesproduction-ready

Circuit Breaker Pattern

A resilience pattern that prevents cascading failures by monitoring error rates and temporarily halting requests to failing services.

type CircuitState = "closed" | "open" | "half-open";

interface CircuitBreakerOptions {
  failureThreshold: number;
  successThreshold: number;
  timeout: number; // ms before transitioning from open to half-open
  monitorInterval?: number;
  onStateChange?: (from: CircuitState, to: CircuitState) => void;
}

export class CircuitBreaker {
  private state: CircuitState = "closed";
  private failureCount = 0;
  private successCount = 0;
  private lastFailureTime = 0;
  private readonly options: Required<CircuitBreakerOptions>;

  constructor(options: CircuitBreakerOptions) {
    this.options = {
      monitorInterval: 5000,
      onStateChange: () => {},
      ...options,
    };
  }

  async execute<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === "open") {
      if (Date.now() - this.lastFailureTime >= this.options.timeout) {
        this.transition("half-open");
      } else {
        throw new CircuitOpenError(this.getRemainingTimeout());
      }
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    if (this.state === "half-open") {
      this.successCount++;
      if (this.successCount >= this.options.successThreshold) {
        this.transition("closed");
      }
    }
    this.failureCount = 0;
  }

  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();

    if (this.state === "half-open") {
      this.transition("open");
    } else if (this.failureCount >= this.options.failureThreshold) {
      this.transition("open");
    }
  }

  private transition(newState: CircuitState): void {
    const oldState = this.state;
    this.state = newState;
    this.failureCount = 0;
    this.successCount = 0;
    this.options.onStateChange(oldState, newState);
  }

  private getRemainingTimeout(): number {
    return Math.max(0, this.options.timeout - (Date.now() - this.lastFailureTime));
  }

  getState(): CircuitState {
    return this.state;
  }

  getStats() {
    return {
      state: this.state,
      failureCount: this.failureCount,
      successCount: this.successCount,
      lastFailureTime: this.lastFailureTime,
    };
  }

  reset(): void {
    this.transition("closed");
  }
}

export class CircuitOpenError extends Error {
  constructor(public readonly retryAfterMs: number) {
    super(`Circuit breaker is open. Retry after ${retryAfterMs}ms`);
    this.name = "CircuitOpenError";
  }
}

title: "Circuit Breaker Pattern" description: "A resilience pattern that prevents cascading failures by monitoring error rates and temporarily halting requests to failing services." category: "TypeScript" language: "typescript" tags: ["typescript", "resilience", "circuit-breaker", "microservices", "production-ready"] createdAt: "2025-03-20" updatedAt: "2025-04-05"

Overview

The circuit breaker pattern protects systems from cascading failures by monitoring error rates of downstream dependencies. When failures exceed a threshold, the circuit "opens" and rejects requests immediately, giving the downstream service time to recover without being overwhelmed.

Code

const breaker = new CircuitBreaker({
  failureThreshold: 5,
  successThreshold: 3,
  timeout: 30_000,
});
 
const result = await breaker.execute(() => callExternalService());

Notes

  • Three states: closed (normal), open (rejecting), half-open (testing recovery)
  • In half-open state, a limited number of requests probe if the service has recovered
  • Always implement a fallback strategy (cached data, degraded response, queue for later)
  • Combine with retry logic: retry within the circuit, but let the breaker stop retrying when the service is truly down
  • Monitor state changes with metrics to track service health over time