breaker-box 4.2.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"
@@ -27,10 +25,11 @@ async function unreliableApiCall(data: string) {
 }
 
 const protectedApiCall = createCircuitBreaker(unreliableApiCall, {
-	errorIsFailure: (error) => error.message.includes("404"), // Don't retry 404s
 	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
 })
 
@@ -42,66 +41,161 @@ 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.
+
+`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,
+	delayMs,
 	useExponentialBackoff,
 	useFibonacciBackoff,
+	withRetry,
 } from "breaker-box"
 
-// Exponential backoff: 1s, 2s, 4s, 8s, up to 30s max
-const protectedWithExponential = createCircuitBreaker(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(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
+
+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, withTimeout } from "breaker-box"
+import {
+	createCircuitBreaker,
+	useExponentialBackoff,
+	withRetry,
+	withTimeout,
+} from "breaker-box"
 
-// Wrap function with 5-second timeout
-const timeoutProtectedCall = withTimeout(
-	unreliableApiCall,
-	5_000,
-	"Request timed out",
+const protectedApiCall = createCircuitBreaker(
+	withRetry(withTimeout(unreliableApiCall, 4_000), {
+		maxAttempts: 3,
+		retryDelay: useExponentialBackoff(60),
+	}),
 )
-
-const protectedApiCall = createCircuitBreaker(timeoutProtectedCall, {})
 ```
 
-### Event Monitoring
+## Observability
+
+The following callbacks are available:
 
 ```typescript
 const protectedFunction = createCircuitBreaker(unreliableApiCall, {
 	onClose: () => {
-		console.log("Circuit closed - normal operation resumed")
+		console.log("🟢 Circuit closed - normal operation resumed")
+	},
+	onHalfOpen: () => {
+		console.log("🟡 Circuit half-opened - waiting for success")
 	},
 	onOpen: (cause) => {
-		console.log("Circuit opened due to:", cause.message)
+		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?)`
 
@@ -111,53 +205,102 @@ 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 is non-retryable (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)
   - `resetAfter`: Milliseconds to wait before trying half-open (default: `30_000`)
-  - `retryDelay`: Function returning promise for retry delays (default: immediate retry)
 
 #### Returns
 
 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'`)
 
 ### Helper Functions
 
+#### `withRetry(fn, options?)`
+
+Wraps a function with retry logic. Failures will be retried according to the provided options.
+
+**Parameters:**
+
+- `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:**
+
+```typescript
+const retryCall = withRetry(apiCall, {
+	maxAttempts: 5,
+	retryDelay: useExponentialBackoff(30),
+	shouldRetry: (error) => error.statusCode !== 404,
+})
+```
+
+#### `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,34 +3,47 @@
 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);
-    })
-  ]);
+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,
-    resetAfter = 3e4,
-    retryDelay = () => void 0
+    resetAfter = 3e4
   } = options;
   assert(
     typeof errorIsFailure === "function",
@@ -44,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})`
@@ -68,10 +85,6 @@ function parseOptions(options) {
     resetAfter >= errorWindow,
     `"resetAfter" must be greater than or equal to "errorWindow" (received ${resetAfter}, expected >= ${errorWindow})`
   );
-  assert(
-    typeof retryDelay === "function",
-    `"retryDelay" must be a function (received ${typeof retryDelay})`
-  );
   return {
     errorIsFailure,
     errorThreshold,
@@ -80,37 +93,78 @@ function parseOptions(options) {
     onClose,
     onHalfOpen,
     onOpen,
-    resetAfter,
-    retryDelay
+    resetAfter
   };
 }
 
+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 = {}) {
+  const {
+    shouldRetry = () => true,
+    maxAttempts = 3,
+    retryDelay = () => Promise.resolve()
+  } = options;
+  assert(maxAttempts >= 1, "maxAttempts must be a number greater than 0");
+  const controller = new AbortController();
+  const { signal } = controller;
+  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(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);
-  return function withTimeoutFunction(...args) {
-    let timer;
-    return Promise.race([
-      main(...args).finally(() => clearTimeout(timer)),
-      new Promise((_, reject) => {
-        timer = setTimeout(reject, timeoutMs, error);
-      })
-    ]);
-  };
+  const controller = new AbortController();
+  const { signal } = controller;
+  function withTimeoutFunction(...args) {
+    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") => {
+      const reason = new ReferenceError(disposeMessage);
+      main[disposeKey]?.(disposeMessage);
+      controller.abort(reason);
+    }
+  });
 }
 
 function createCircuitBreaker(main, options = {}) {
@@ -122,27 +176,28 @@ function createCircuitBreaker(main, options = {}) {
     onClose,
     onHalfOpen,
     onOpen,
-    resetAfter,
-    retryDelay
+    resetAfter
   } = parseOptions(options);
   const controller = new AbortController();
   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()) {
@@ -153,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 };
@@ -169,16 +226,17 @@ function createCircuitBreaker(main, options = {}) {
       history.delete(pending);
       signal.removeEventListener("abort", teardown);
     };
-    signal.addEventListener("abort", teardown);
+    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(attempt, args) {
+  function execute(...args) {
     if (state === "closed") {
       const { pending, settle, teardown } = createHistoryItem(main(...args));
       return pending.then(
@@ -186,16 +244,14 @@ function createCircuitBreaker(main, options = {}) {
           settle("resolved");
           return result;
         },
-        async (cause) => {
+        (cause) => {
           if (signal.aborted || errorIsFailure(cause)) {
             teardown();
             throw cause;
           }
           settle("rejected");
-          if (failureRate() > errorThreshold) openCircuit(cause);
-          const next = attempt + 1;
-          await rejectOnAbort(signal, retryDelay(next, signal));
-          return execute(next, args);
+          if (failureRate > errorThreshold) openCircuit(cause);
+          return fallback(...args);
         }
       );
     } else if (state === "open" || halfOpenPending) {
@@ -207,28 +263,32 @@ function createCircuitBreaker(main, options = {}) {
           closeCircuit();
           return result;
         },
-        async (cause) => {
+        (cause) => {
           if (signal.aborted || errorIsFailure(cause)) throw cause;
           openCircuit(cause);
-          const next = attempt + 1;
-          await rejectOnAbort(signal, retryDelay(next, signal));
-          return execute(next, args);
+          return fallback(...args);
         }
       );
     }
+    /* v8 ignore next -- @preserve */
     return assertNever(state);
   }
-  return Object.assign((...args) => execute(1, 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
   });
@@ -238,5 +298,6 @@ exports.createCircuitBreaker = createCircuitBreaker;
 exports.delayMs = delayMs;
 exports.useExponentialBackoff = useExponentialBackoff;
 exports.useFibonacciBackoff = useFibonacciBackoff;
+exports.withRetry = withRetry;
 exports.withTimeout = withTimeout;
 //# sourceMappingURL=index.cjs.map