CircuitBreakerOptions

failureRateThreshold

failureRateThreshold?: number

Failure rate threshold as a ratio between 0 (exclusive) and 1 (inclusive). The circuit opens when the failure rate in the sliding window meets or exceeds this value and at least minimumThroughput requests have been recorded.

Default: 0.5

minimumThroughput

minimumThroughput?: number

Minimum number of requests in the sliding window before the failure rate is evaluated. Prevents the circuit from tripping on statistically insignificant samples during low traffic.

Default: 20

windowMs

windowMs?: number

Duration of the sliding window in milliseconds.

Default: 60000

segmentsPerWindow

segmentsPerWindow?: number

Number of segments the sliding window is divided into. More segments give finer-grained decay at the cost of slightly more memory.

Default: 10

cooldownMs

cooldownMs?: number

Duration in milliseconds the circuit stays open before entering half-open.

Default: 30000

successThreshold

successThreshold?: number

Number of consecutive successes needed to close from half-open state.

Default: 2

halfOpenMaxConcurrent

halfOpenMaxConcurrent?: number

Maximum concurrent requests allowed in half-open state.

Default: 3

isFailure

isFailure?: (error: unknown) => boolean

Custom predicate to determine if an error should count as a circuit failure. By default, any thrown error is a failure.

Returns

true if the error should count as a circuit failure.

isResultFailure

isResultFailure?: (result: T) => boolean

Custom predicate to determine if a successful result should count as failure. Useful for HTTP responses where status codes indicate logical failures.

Returns

true if the result should count as a circuit failure.

onStateChange

onStateChange?: (from: CircuitState, to: CircuitState) => void

Callback invoked when circuit state changes.

If this callback throws, the error is reported asynchronously without disrupting circuit breaker operation.

onFailure

onFailure?: (error: unknown, failureCount: number, totalRequests: number) => void

Callback invoked when a failure is recorded.

If this callback throws, the error is reported asynchronously without disrupting circuit breaker operation.

onOpen

onOpen?: (failureCount: number, totalRequests: number) => void

Callback invoked when circuit opens.

If this callback throws, the error is reported asynchronously without disrupting circuit breaker operation.

onHalfOpen

onHalfOpen?: () => void

Callback invoked when circuit enters half-open state (testing recovery).

If this callback throws, the error is reported asynchronously without disrupting circuit breaker operation.

onClose

onClose?: () => void

Callback invoked when circuit closes (recovery complete).

If this callback throws, the error is reported asynchronously without disrupting circuit breaker operation.