ts-easy-circuit-breaker
v1.3.0
Published
A lightweight and easy-to-use Circuit Breaker implementation in TypeScript.
Downloads
104
Maintainers
Readme
ts-easy-circuit-breaker
A lightweight and easy-to-use Circuit Breaker implementation in TypeScript.
Table of Contents
- Installation
- Usage
- API
- Configuration
- Initial State and Serverless Environments
- Events
- Examples
- Contributing
- License
Installation
You can install the package using npm:
npm install ts-easy-circuit-breaker
Or using yarn:
yarn add ts-easy-circuit-breaker
Usage
Here's a basic example of how to use the Circuit Breaker:
import { CircuitBreaker } from "ts-easy-circuit-breaker";
const breaker = new CircuitBreaker({
failureThreshold: 0.5,
timeWindow: 10000,
resetTimeout: 30000,
minAttempts: 5,
minFailures: 3,
});
async function makeHttpRequest() {
// Your HTTP request logic here
}
try {
const result = await breaker.execute(makeHttpRequest);
console.log("Request successful:", result);
} catch (error) {
if (error instanceof CircuitBreakerOpenError) {
console.log("Circuit is open, request not made");
} else {
console.error("Request failed:", error);
}
}
API
CircuitBreaker
The main class that implements the Circuit Breaker pattern.
Constructor
new CircuitBreaker(options: CircuitBreakerOptions)
Methods
execute<T>(fn: (...args: any[]) => Promise<T>, ...args: any[]): Promise<T>
Executes the given function through the circuit breaker.exportState(): CircuitBreakerState
Returns the current state of the circuit breaker.
CircuitBreakerOpenError
An error class that is thrown when an execution is attempted while the circuit is open.
Configuration
The CircuitBreaker
constructor accepts an options object with the following properties:
failureThreshold
: The failure rate threshold above which the circuit should open. (0 to 1)timeWindow
: The time window in milliseconds over which the failure threshold is calculated.resetTimeout
: The time in milliseconds after which to attempt closing the circuit.minAttempts
: (Optional) The minimum number of attempts before the failure threshold is considered. Default is 5.minFailures
: (Optional) The minimum number of failures required to open the circuit, regardless of the failure rate. Default is 3.minEvaluationTime
: (Optional) The minimum time in milliseconds that must pass since the first failure before the circuit breaker starts evaluating whether to open. Default is 15ms.
Initial State and Serverless Environments
The CircuitBreaker
constructor also accepts an optional initialState
parameter, which is particularly useful in serverless environments where the state needs to be persisted externally (e.g., in Redis) between function invocations.
Here's an example of how to use the initialState
:
import { CircuitBreaker, CircuitState } from "ts-easy-circuit-breaker";
// Assume this function retrieves the state from an external store (e.g., Redis)
async function getStateFromExternalStore() {
// Implementation to fetch state from external store
}
// Assume this function saves the state to an external store
async function saveStateToExternalStore(state: CircuitBreakerState) {
// Implementation to save state to external store
}
async function initializeCircuitBreaker() {
const options = {
failureThreshold: 0.5,
timeWindow: 10000,
resetTimeout: 30000,
minAttempts: 5,
minFailures: 3,
minEvaluationTime: 5000,
};
const savedState = await getStateFromExternalStore();
const circuitBreaker = new CircuitBreaker(options, savedState);
// Optionally, you can listen for state changes and save the new state
circuitBreaker.on("stateChanged", async (newState) => {
await saveStateToExternalStore(newState);
});
return circuitBreaker;
}
// Usage in a serverless function
export async function handler(event, context) {
const circuitBreaker = await initializeCircuitBreaker();
try {
const result = await circuitBreaker.execute(async () => {
// Your protected operation here
});
return { statusCode: 200, body: JSON.stringify(result) };
} catch (error) {
if (error instanceof CircuitBreakerOpenError) {
return { statusCode: 503, body: "Service temporarily unavailable" };
}
return { statusCode: 500, body: "Internal server error" };
}
}
In this example, the Circuit Breaker's state is retrieved from an external store (like Redis) at the beginning of each serverless function invocation. This allows the Circuit Breaker to maintain its state across multiple invocations, which is crucial in serverless environments where the execution context is not preserved between invocations.
The initialState
object should have the following structure:
interface CircuitBreakerState {
state: CircuitState;
failureCount: number;
successCount: number;
firstFailureTime: number;
lastFailureTime: number;
nextAttempt: number;
}
By using this approach, you can ensure that your Circuit Breaker behaves consistently in serverless environments, properly tracking failures and successes across multiple function invocations.
Events
The Circuit Breaker emits the following events:
'openCircuit'
: Emitted when the circuit opens.'closeCircuit'
: Emitted when the circuit closes.'halfOpen'
: Emitted when the circuit transitions to the half-open state.'success'
: Emitted on successful execution.'failure'
: Emitted on failed execution.
You can listen to these events like this:
breaker.on("openCircuit", () => {
console.log("Circuit opened");
});
Examples
HTTP Request Wrapper with Minimum Failures
import { CircuitBreaker } from "ts-easy-circuit-breaker";
import axios from "axios";
const breaker = new CircuitBreaker({
failureThreshold: 0.5,
timeWindow: 10000,
resetTimeout: 30000,
minAttempts: 10,
minFailures: 5,
});
async function makeRequest(url: string) {
return breaker.execute(async () => {
const response = await axios.get(url);
return response.data;
});
}
// Usage
try {
const data = await makeRequest("https://api.example.com/data");
console.log(data);
} catch (error) {
console.error("Request failed:", error);
}
In this example, the circuit will only open if there have been at least 5 failures, the failure rate is 50% or higher, and there have been at least 10 attempts within the 10-second time window.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License.