A simple circuit breaker utility

Usage no npm install needed!

<script type="module">
  import easyBreaker from 'https://cdn.skypack.dev/easy-breaker';



js-standard-style Build Status Coverage Status

A simple and low overhead circuit breaker utility.


npm i easy-breaker


Require the library and initialize it with the function you want to put under the Circuit Breaker.

const EasyBreaker = require('easy-breaker')
const simpleGet = require('simple-get')

const get = EasyBreaker(simpleGet)

get('http://example.com', function (err, res) {
  if (err) throw err

If the function times out, the error will be a TimeoutError.
If the threshold has been reached and the circuit is open the error will be a CircuitOpenError.

You can access the errors constructors with require('easy-breaker').errors.
You can access the state constants with require('easy-breaker').states.


You can pass some custom option to change the default behavior of EasyBreaker:

const EasyBreaker = require('easy-breaker')
const simpleGet = require('simple-get')

// the following options object contains the default values
const get = EasyBreaker(simpleGet, {
  threshold: 5
  timeout: 1000 * 10
  resetTimeout: 1000 * 10
  context: null,
  maxEventListeners: 100
  promise: false
  • threshold: is the maximum numbers of failures you accept to have before opening the circuit.
  • timeout: is the maximum number of milliseconds you can wait before return a TimeoutError (read the caveats section about how the timeout is handled).
  • resetTimeout: time before the circuit will move from open to half-open
  • context: a custom context for the function to call
  • maxEventListeners: since this library relies on events, it can happen that you reach the maximum number of events listeners before the memory leak warn. To avoid that log, just set an higher number with this property.
  • promise: if you need to handle promised API, see below.


Promises and async-await are supported as well!
Just pass the option { promise: true } and you are done!
Note the if you use the promise version of the api also the function you are wrapping should return a promise.

const EasyBreaker = require('easy-breaker')
const got = require('got')

const get = EasyBreaker(got, { promise: true })



This circuit breaker is an event emitter, if needed you can listen to its events:

  • open
  • half-open
  • close
  • result
  • tick


Run a timer for every function is pretty expensive, especially if you are running the code in a heavy load environment.
To fix this problem and get better performances, EasyBreaker uses an atomic clock, in other words uses an interval that emits a tick event every timeout / 2 milliseconds.
Every running functions listens for that event and if the number of ticks received is higher than 3 it will return a TimeoutError.


Image curtesy of Martin Fowler.



Copyright © 2018 Tomas Della Vedova