breaker-box 5.0.0 → 6.0.0

package/README.md

@@ -12,9 +12,7 @@ A zero-dependency [circuit breaker][0] implementation for Node.js.
 npm install breaker-box
 ```
 
-## Usage
-
-### Basic Usage
+## Basic Usage
 
 ```typescript
 import { createCircuitBreaker } from "breaker-box"
@@ -29,7 +27,9 @@ async function unreliableApiCall(data: string) {
 const protectedApiCall = createCircuitBreaker(unreliableApiCall, {
 	errorThreshold: 0.5, // Open circuit when 50% of calls fail
 	errorWindow: 10_000, // Track errors over 10 second window
-	minimumCandidates: 6, // Need at least 6 calls before calculating error rate
+	// Fallback receives the same parameters as the original function
+	fallback: (data) => ({ data: "fallback data", error: "API call failed" }),
+	minimumCandidates: 1, // Need at least 1 call before calculating error rate
 	resetAfter: 30_000, // Try again after 30 seconds
 })
 
@@ -41,59 +41,125 @@ try {
 }
 ```
 
-### Retry Strategies
+The above example creates a function named `protectedApiCall` which, when called will execute the `unreliableApiCall` function with circuit breaker protection. If the underlying function fails, then `fallback` is called instead. If **50%** of the calls fail within a **10-second sliding window**, then the circuit breaker will open and subsequent calls to `protectedApiCall` will **always** use the `fallback` for the next **30 seconds**.
+
+## Composition Helpers
+
+The circuit breaker function doesn't handle timeouts, retries, or cooldowns on
+its own. For these features, you need to compose with other helper functions.
+`breaker-box` provides a set of composable functions that can wrap your API call
+with these features.
+
+### Timeouts
+
+Wrap the `unreliableApiCall` with a timeout using `withTimeout()`. If the timer
+expires before the call completes, then the promise will reject with
+`ERR_CIRCUIT_BREAKER_TIMEOUT`.
+
+This wrapping may not be needed if your API call supports a timeout option
+already (e.g. `axios` already has a `timeout` option).
+
+```typescript
+import { createCircuitBreaker, withTimeout } from "breaker-box"
+
+const protectedApiCall = createCircuitBreaker(
+	withTimeout(unreliableApiCall, 5000),
+)
+```
+
+### Retries
+
+Wrap the `unreliableApiCall` with retry logic using `withRetry()` function. If
+the promise gets rejected, it will be retried up to a certain number of times.
+Once the max number of retries is reached, then the promise will ultimately
+reject with `ERR_CIRCUIT_BREAKER_MAX_ATTEMPTS (${number})`.
+
+This wrapping may not be needed if your API call supports a retry option already
+(e.g. `aws-sdk` already has retry logic).
+
+```typescript
+import { createCircuitBreaker, withRetry } from "breaker-box"
+
+const protectedApiCall = createCircuitBreaker(
+	withRetry(unreliableApiCall, {
+		maxAttempts: 3,
+		shouldRetry: (error) => true, // Check whether error is retryable
+	}),
+)
+```
+
+### Cooldowns
+
+When using retry logic, it may be necessary to introduce a cooldown period
+between retries to prevent overwhelming the remote system. By default,
+`withRetry` will retry immediately. However, you can provide a custom
+`retryDelay` function to introduce a delay before each retry attempt. The
+function should return a promise that resolves after the desired delay.
 
-The circuit breaker doesn't retry - it only tracks failures and prevents calls when too many fail. Use `withRetry` to add retry logic:
+`breaker-box` offers helper functions to generate retry delays:
+
+- `delayMs(ms: number)`: Returns a promise that resolves after the specified
+  number of milliseconds.
+- `useExponentialBackoff(maxSeconds: number)`: Returns a function that
+  calculates the delay using exponential backoff.
+
+- `useFibonacciBackoff(maxSeconds: number)`: Returns a function that calculates
+  the delay using Fibonacci sequence.
 
 ```typescript
 import {
 	createCircuitBreaker,
-	withRetry,
+	delayMs,
 	useExponentialBackoff,
 	useFibonacciBackoff,
+	withRetry,
 } from "breaker-box"
 
-// Exponential backoff: 1s, 2s, 4s, 8s, up to 30s max
-const protectedWithExponential = createCircuitBreaker(
-	withRetry(unreliableApiCall, { retryDelay: useExponentialBackoff(30) }),
+const protectedApiCall1 = createCircuitBreaker(
+	withRetry(unreliableApiCall, {
+		maxAttempts: 3,
+		retryDelay: (attempt, signal) => delayMs(1_000, signal),
+	}),
 )
 
-// Fibonacci backoff: 1s, 2s, 3s, 5s, 8s, up to 60s max
-const protectedWithFibonacci = createCircuitBreaker(
-	withRetry(unreliableApiCall, { retryDelay: useFibonacciBackoff(60) }),
+const protectedApiCall2 = createCircuitBreaker(
+	withRetry(unreliableApiCall, {
+		maxAttempts: 3,
+		retryDelay: useExponentialBackoff(60),
+	}),
+)
+
+const protectedApiCall3 = createCircuitBreaker(
+	withRetry(unreliableApiCall, {
+		maxAttempts: 3,
+		retryDelay: useFibonacciBackoff(60),
+	}),
 )
 ```
 
-### Timeout Protection
+### Complete Example
 
-Compose `withTimeout`, `withRetry`, and circuit breaker for complete fault tolerance:
+The optimal composition should look like this: Circuit Breaker -> Retry -> Timeout -> Implementation. However, you may compose it in any order you prefer as long as you understand the behavior.
 
 ```typescript
 import {
 	createCircuitBreaker,
+	useExponentialBackoff,
 	withRetry,
 	withTimeout,
-	useExponentialBackoff,
 } from "breaker-box"
 
-// 1. Add timeout (innermost - fails fast)
-const timedCall = withTimeout(unreliableApiCall, 5_000, "Request timed out")
-
-// 2. Add retry logic (middle - retries on transient errors)
-const retryCall = withRetry(timedCall, {
-	maxAttempts: 3,
-	retryDelay: useExponentialBackoff(10),
-	shouldRetry: (error) => !error.message.includes("404"), // Don't retry 404s
-})
-
-// 3. Add circuit breaker (outermost - prevents cascading failures)
-const protectedApiCall = createCircuitBreaker(retryCall, {
-	errorThreshold: 0.5,
-	minimumCandidates: 5,
-})
+const protectedApiCall = createCircuitBreaker(
+	withRetry(withTimeout(unreliableApiCall, 4_000), {
+		maxAttempts: 3,
+		retryDelay: useExponentialBackoff(60),
+	}),
+)
 ```
 
-### Event Monitoring
+## Observability
+
+The following callbacks are available:
 
 ```typescript
 const protectedFunction = createCircuitBreaker(unreliableApiCall, {
@@ -107,20 +173,29 @@ const protectedFunction = createCircuitBreaker(unreliableApiCall, {
 		console.log("🔴 Circuit opened due to:", cause.message)
 	},
 })
+```
+
+The following methods can retrieve information about the circuit breaker:
 
-// Check current state
+```typescript
+// Check current state: "closed", "open", "halfOpen"
 console.log("Current state:", protectedFunction.getState())
-// Possible states: 'closed', 'open', 'halfOpen'
+
+// Check failure rate: Number between 0 and 1
+console.log("Failure rate:", protectedFunction.getFailureRate())
+
+// Get the last error that caused the circuit to open: undefined or Error object
+console.log("Last error:", protectedFunction.getLatestError())
 ```
 
-### Cleanup
+## Cleanup
 
 ```typescript
 // Clean up resources when shutting down
 protectedFunction.dispose()
 ```
 
-## API
+## API Reference
 
 ### `createCircuitBreaker(fn, options?)`
 
@@ -130,11 +205,11 @@ Creates a circuit breaker around the provided async function.
 
 - `fn`: The async function to protect
 - `options`: Configuration object (optional)
-  - `errorIsFailure`: Function to determine if an error should not count toward circuit breaker metrics (default: `() => false`)
+  - `errorIsFailure`: Function to determine if an error is a non-retryable failure; when true, the error is thrown immediately without counting toward metrics (default: `() => false`)
   - `errorThreshold`: Percentage (0-1) of errors that triggers circuit opening (default: `0`)
   - `errorWindow`: Time window in ms for tracking errors (default: `10_000`)
-  - `fallback`: Function to call when circuit is open (default: undefined)
-  - `minimumCandidates`: Minimum calls before calculating error rate (default: `6`)
+  - `fallback`: Function to call when an error occurs or circuit is open (default: undefined)
+  - `minimumCandidates`: Minimum calls before calculating error rate (default: `1`)
   - `onClose`: Function called when circuit closes (default: undefined)
   - `onHalfOpen`: Function called when circuit enters half-open state (default: undefined)
   - `onOpen`: Function called when circuit opens (default: undefined)
@@ -145,6 +220,7 @@ Creates a circuit breaker around the provided async function.
 A function with the same signature as `fn` and additional methods:
 
 - `.dispose(message?)`: Clean up resources and reject future calls
+- `.getFailureRate()`: Returns the current failure rate (0-1) or 0 if fewer than `minimumCandidates` calls have been made
 - `.getLatestError()`: Returns the error which triggered the circuit breaker
 - `.getState()`: Returns current circuit state (`'closed'`, `'open'`, `'halfOpen'`)
 
@@ -154,11 +230,13 @@ A function with the same signature as `fn` and additional methods:
 
 Wraps a function with retry logic. Failures will be retried according to the provided options.
 
-**Options:**
+**Parameters:**
 
-- `maxAttempts`: Maximum number of attempts (default: `3`)
-- `retryDelay`: Function returning promise for when to retry (default: immediate)
-- `shouldRetry`: Function to determine if error should be retried (default: `() => true`)
+- `fn`: The async function to wrap with retry logic
+- `options`: Configuration object (optional)
+  - `maxAttempts`: Maximum number of attempts (default: `3`)
+  - `retryDelay`: Function `(attempt: number, signal: AbortSignal) => Promise<void>` for delay before retry (default: immediate)
+  - `shouldRetry`: Function `(error: unknown, attempt: number) => boolean` to determine if error should be retried (default: `() => true`)
 
 **Example:**
 
@@ -170,33 +248,59 @@ const retryCall = withRetry(apiCall, {
 })
 ```
 
+#### `withTimeout(fn, timeoutMs, message?)`
+
+Wraps a function with a timeout. Rejects with `Error(message)` if execution exceeds `timeoutMs`.
+
+**Parameters:**
+
+- `fn`: The async function to wrap with timeout
+- `timeoutMs`: Timeout in milliseconds
+- `message`: Error message to use when timeout occurs (default: `"ERR_CIRCUIT_BREAKER_TIMEOUT"`)
+
 #### `useExponentialBackoff(maxSeconds)`
 
 Returns a retry delay function that implements exponential backoff (2^n seconds, capped at maxSeconds).
 
+**Parameters:**
+
+- `maxSeconds`: Maximum delay in seconds before capping
+
+**Returns:** Function `(attempt: number, signal: AbortSignal) => Promise<void>`
+
 #### `useFibonacciBackoff(maxSeconds)`
 
 Returns a retry delay function that implements Fibonacci backoff (Fibonacci sequence in seconds, capped at maxSeconds).
 
-#### `withTimeout(fn, timeoutMs, message?)`
+**Parameters:**
 
-Wraps a function with a timeout. Rejects with `Error(message)` if execution exceeds `timeoutMs`.
+- `maxSeconds`: Maximum delay in seconds before capping
 
-### Development
+**Returns:** Function `(attempt: number, signal: AbortSignal) => Promise<void>`
 
-### Building the Project
+#### `delayMs(ms, signal?)`
 
-```sh
-npm run build
-```
+Returns a promise that resolves after the specified number of milliseconds. Supports optional abort signal for cancellation.
 
-### Running Tests
+**Parameters:**
 
-```sh
-npm test # once
+- `ms`: Delay in milliseconds
+- `signal`: Optional AbortSignal for cancellation
 
-npm run dev # run and watch for file changes
-```
+**Returns:** `Promise<void>`
+
+## Development Commands
+
+| Command                     | Purpose                                |
+| --------------------------- | -------------------------------------- |
+| `npm run build`             | Build with pkgroll (CJS + ESM + types) |
+| `npm run dev`               | Run tests in watch mode (vitest)       |
+| `npm run format`            | Format with Prettier                   |
+| `npm run test:coverage`     | Run tests with coverage                |
+| `npm test`                  | Run tests once                         |
+| `npx tsc --noEmit`          | Type-check without emit                |
+| `npx vitest index.test.ts`  | Run single test file                   |
+| `npx vitest -t "test name"` | Run specific test by name              |
 
 ## Contributing
 

package/dist/index.cjs

@@ -3,29 +3,43 @@
 function assert(value, message) {
   if (!value) throw new TypeError(message);
 }
+/* v8 ignore next -- @preserve */
 const assertNever = (val, msg = "Unexpected value") => {
   throw new TypeError(`${msg}: ${val}`);
 };
-const delayMs = (ms) => new Promise((next) => setTimeout(next, ms));
-const rejectOnAbort = (signal, pending) => {
-  let teardown;
-  return Promise.race([
-    Promise.resolve(pending).finally(() => {
-      signal.removeEventListener("abort", teardown);
-    }),
-    new Promise((_, reject) => {
-      teardown = () => reject(signal.reason);
-      signal.addEventListener("abort", teardown, { once: true });
-    })
-  ]);
+const delayMs = (ms, signal) => {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new RangeError(
+      `"ms" must be a finite, non-negative number (received ${ms})`
+    );
+  }
+  return signal ? new Promise((resolve, reject) => {
+    signal.throwIfAborted();
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  }) : new Promise((next) => setTimeout(next, ms));
 };
+const abortable = (signal, pending) => new Promise((resolve, reject) => {
+  signal.throwIfAborted();
+  const onAbort = () => reject(signal.reason);
+  signal.addEventListener("abort", onAbort, { once: true });
+  Promise.resolve(pending).then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+});
 
 function parseOptions(options) {
   const {
     errorIsFailure = () => false,
     errorThreshold = 0,
     errorWindow = 1e4,
-    minimumCandidates = 6,
+    fallback,
+    minimumCandidates = 1,
     onClose,
     onHalfOpen,
     onOpen,
@@ -43,6 +57,10 @@ function parseOptions(options) {
     errorWindow >= 1e3,
     `"errorWindow" must be milliseconds of at least 1 second (received ${errorWindow})`
   );
+  assert(
+    !fallback || typeof fallback === "function",
+    `"fallback" must be a function (received ${typeof fallback})`
+  );
   assert(
     minimumCandidates >= 1,
     `"minimumCandidates" must be greater than 0 (received ${minimumCandidates})`
@@ -82,18 +100,18 @@ function parseOptions(options) {
 const disposeKey = Symbol("disposeKey");
 
 function useExponentialBackoff(maxSeconds) {
-  return function exponentialBackoff(attempt) {
+  return function exponentialBackoff(attempt, signal) {
     const num = Math.max(attempt - 2, 0);
     const delay = Math.min(2 ** num, maxSeconds);
-    return delayMs(delay * 1e3);
+    return delayMs(delay * 1e3, signal);
   };
 }
 const sqrt5 = /* @__PURE__ */ Math.sqrt(5);
 const binet = (n) => Math.round(((1 + sqrt5) ** n - (1 - sqrt5) ** n) / (2 ** n * sqrt5));
 function useFibonacciBackoff(maxSeconds) {
-  return function fibonacciBackoff(attempt) {
+  return function fibonacciBackoff(attempt, signal) {
     const delay = Math.min(binet(attempt), maxSeconds);
-    return delayMs(delay * 1e3);
+    return delayMs(delay * 1e3, signal);
   };
 }
 function withRetry(main, options = {}) {
@@ -105,53 +123,40 @@ function withRetry(main, options = {}) {
   assert(maxAttempts >= 1, "maxAttempts must be a number greater than 0");
   const controller = new AbortController();
   const { signal } = controller;
-  async function execute(args, attempt = 1) {
-    try {
-      return await main(...args);
-    } catch (cause) {
-      if (!shouldRetry(cause, attempt)) throw cause;
-      if (attempt >= maxAttempts)
-        throw new Error(`ERR_CIRCUIT_BREAKER_MAX_ATTEMPTS (${maxAttempts})`, {
-          cause
-        });
-      await rejectOnAbort(signal, retryDelay(attempt + 1, signal));
-      return execute(args, attempt + 1);
+  async function withRetryFunction(...args) {
+    let attempt = 1;
+    while (true) {
+      try {
+        return await main(...args);
+      } catch (cause) {
+        if (attempt >= maxAttempts) {
+          throw new Error(`ERR_CIRCUIT_BREAKER_MAX_ATTEMPTS (${maxAttempts})`, {
+            cause
+          });
+        }
+        if (!shouldRetry(cause, attempt)) throw cause;
+      }
+      attempt++;
+      await abortable(signal, retryDelay(attempt, signal));
     }
   }
-  return Object.assign(
-    function withRetryFunction(...args) {
-      return execute(args);
-    },
-    {
-      [disposeKey]: (disposeMessage = "ERR_CIRCUIT_BREAKER_DISPOSED") => {
-        const reason = new ReferenceError(disposeMessage);
-        main[disposeKey]?.(disposeMessage);
-        controller.abort(reason);
-      }
+  return Object.assign(withRetryFunction, {
+    [disposeKey]: (disposeMessage = "ERR_CIRCUIT_BREAKER_DISPOSED") => {
+      const reason = new ReferenceError(disposeMessage);
+      main[disposeKey]?.(disposeMessage);
+      controller.abort(reason);
     }
-  );
+  });
 }
 function withTimeout(main, timeoutMs, timeoutMessage = "ERR_CIRCUIT_BREAKER_TIMEOUT") {
   const error = new Error(timeoutMessage);
   const controller = new AbortController();
   const { signal } = controller;
   function withTimeoutFunction(...args) {
-    let teardown;
-    let timer;
-    return Promise.race([
-      main(...args).finally(() => {
-        clearTimeout(timer);
-        signal.removeEventListener("abort", teardown);
-      }),
-      new Promise((_, reject) => {
-        teardown = () => {
-          clearTimeout(timer);
-          reject(signal.reason);
-        };
-        timer = setTimeout(reject, timeoutMs, error);
-        signal.addEventListener("abort", teardown, { once: true });
-      })
-    ]);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(reject, timeoutMs, error);
+      abortable(signal, main(...args)).then(resolve, reject).finally(() => clearTimeout(timer));
+    });
   }
   return Object.assign(withTimeoutFunction, {
     [disposeKey]: (disposeMessage = "ERR_CIRCUIT_BREAKER_DISPOSED") => {
@@ -177,20 +182,22 @@ function createCircuitBreaker(main, options = {}) {
   const history = /* @__PURE__ */ new Map();
   const signal = controller.signal;
   let failureCause;
+  let failureRate = 0;
   let fallback = options.fallback || (() => Promise.reject(failureCause));
   let halfOpenPending;
   let resetTimer;
   let state = "closed";
   function clearFailure() {
     failureCause = void 0;
+    clearTimeout(resetTimer);
+    resetTimer = void 0;
   }
   function closeCircuit() {
     state = "closed";
     clearFailure();
-    clearTimeout(resetTimer);
-    onClose?.();
+    if (onClose) setImmediate(onClose);
   }
-  function failureRate() {
+  function calculateFailureRate() {
     let failures = 0;
     let total = 0;
     for (const { status } of history.values()) {
@@ -201,14 +208,16 @@ function createCircuitBreaker(main, options = {}) {
     return failures / total;
   }
   function openCircuit(cause) {
-    failureCause = cause;
     state = "open";
+    failureCause = cause;
     clearTimeout(resetTimer);
-    resetTimer = setTimeout(() => {
-      state = "halfOpen";
-      onHalfOpen?.();
-    }, resetAfter);
-    onOpen?.(cause);
+    resetTimer = setTimeout(() => halfOpenCircuit(), resetAfter);
+    if (onOpen) setImmediate(onOpen, cause);
+  }
+  function halfOpenCircuit() {
+    state = "halfOpen";
+    halfOpenPending = void 0;
+    if (onHalfOpen) setImmediate(onHalfOpen);
   }
   function createHistoryItem(pending) {
     const entry = { status: "pending", timer: void 0 };
@@ -219,14 +228,15 @@ function createCircuitBreaker(main, options = {}) {
     };
     signal.addEventListener("abort", teardown, { once: true });
     const settle = (value) => {
-      if (signal.aborted) return;
+      if (signal.aborted) return 0;
       entry.status = value;
       entry.timer = setTimeout(teardown, errorWindow);
+      return failureRate = calculateFailureRate();
     };
     history.set(pending, entry);
     return { pending, settle, teardown };
   }
-  function execute(args) {
+  function execute(...args) {
     if (state === "closed") {
       const { pending, settle, teardown } = createHistoryItem(main(...args));
       return pending.then(
@@ -240,7 +250,7 @@ function createCircuitBreaker(main, options = {}) {
             throw cause;
           }
           settle("rejected");
-          if (failureRate() > errorThreshold) openCircuit(cause);
+          if (failureRate > errorThreshold) openCircuit(cause);
           return fallback(...args);
         }
       );
@@ -260,20 +270,25 @@ function createCircuitBreaker(main, options = {}) {
         }
       );
     }
+    /* v8 ignore next -- @preserve */
     return assertNever(state);
   }
-  return Object.assign((...args) => execute(args), {
+  return Object.assign(execute, {
     dispose: (disposeMessage = "ERR_CIRCUIT_BREAKER_DISPOSED") => {
+      /* v8 ignore if -- @preserve */
+      if (signal.aborted) return;
       const reason = new ReferenceError(disposeMessage);
       main[disposeKey]?.(disposeMessage);
       clearFailure();
-      clearTimeout(resetTimer);
+      halfOpenPending = void 0;
       history.forEach((entry) => clearTimeout(entry.timer));
       history.clear();
+      failureRate = 0;
       fallback = () => Promise.reject(reason);
       state = "open";
       controller.abort(reason);
     },
+    getFailureRate: () => failureRate,
     getLatestError: () => failureCause,
     getState: () => state
   });