Circuit Breaker Pattern in Node.js & Microservices: Architecture, States & Implementation

       [Normal Operations]
             |
             v
       +------------+
       |   CLOSED   | <-------------------------+
       +------------+                           |
             |                                  |
    Failure Threshold Exceeded                  |
             |                                  |
             v                                  |
       +------------+                     Trial Request
       |    OPEN    |                       Succeeded
       +------------+                           |
             |                                  |
    Reset Timeout Elapsed                       |
             |                                  |
             v                                  |
       +------------+                           |
       | HALF-OPEN  | --------------------------+
       +------------+
             |
     Trial Request Failed (Trip back to OPEN)

type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";

interface CircuitBreakerOptions {
  failureThreshold?: number; // e.g. 3 consecutive failures
  resetTimeoutMs?: number;   // e.g. 5000ms cool-down
  fallback?: (...args: any[]) => any;
}

interface CircuitBreaker<T extends (...args: any[]) => Promise<any>> {
  (...args: Parameters<T>): Promise<ReturnType<T>>;
  getState(): CircuitState;
  reset(): void;
}

function createCircuitBreaker<T extends (...args: any[]) => Promise<any>>(
  fn: T,
  options: CircuitBreakerOptions = {}
): CircuitBreaker<T> {
  const failureThreshold = options.failureThreshold ?? 3;
  const resetTimeoutMs = options.resetTimeoutMs ?? 5000;
  const fallback = options.fallback;

  let state: CircuitState = "CLOSED";
  let failures = 0;
  let nextAttempt = 0;

  const breaker: any = async function (...args: Parameters<T>): Promise<ReturnType<T>> {
    const now = Date.now();

    // Check if cool-down timer elapsed while OPEN
    if (state === "OPEN") {
      if (now >= nextAttempt) {
        state = "HALF_OPEN";
      } else {
        // Fail-fast immediately
        if (typeof fallback === "function") {
          return await fallback(...args);
        }
        throw new Error("Circuit breaker is OPEN");
      }
    }

    try {
      const result = await fn(...args);
      // Success: reset failures and restore CLOSED state
      failures = 0;
      state = "CLOSED";
      return result;
    } catch (err) {
      failures++;
      // If we failed in HALF-OPEN or hit failureThreshold in CLOSED -> Trip OPEN
      if (state === "HALF_OPEN" || failures >= failureThreshold) {
        state = "OPEN";
        nextAttempt = Date.now() + resetTimeoutMs;
      }

      if (typeof fallback === "function" && state === "OPEN") {
        return await fallback(...args);
      }
      throw err;
    }
  };

  breaker.getState = (): CircuitState => {
    if (state === "OPEN" && Date.now() >= nextAttempt) {
      state = "HALF_OPEN";
    }
    return state;
  };

  breaker.reset = (): void => {
    state = "CLOSED";
    failures = 0;
    nextAttempt = 0;
  };

  return breaker;
}