# simple-backoff

Calculates the delay values for various backoff mechanisms. Like backoff, except it doesn't wrap everything up in an arbitrary API. Like backo/backo2, except it provides three choices of algorithm.

# Usage

```
var LinearBackoff = require('simple-backoff').LinearBackoff;
var backoff = new LinearBackoff({
min: 10,
step: 50
});
console.log(backoff.next());
console.log(backoff.next());
backoff.reset();
console.log(backoff.next());
```

Outputs:

```
10
60
10
```

# API

### constructor

Four constructors are exported: `LinearBackoff`

, `ExponentialBackoff`

, `FibonacciBackoff`

, and `FixedBackoff`

. They each have slightly different options, but the first three accept a basic set of core options, passed as an options bag:

```
new LinearBackoff({
min: 10,
max: 10000,
step: 50,
jitter: 0
});
new ExponentialBackoff({
min: 10,
max: 10000,
factor: 2,
jitter: 0
});
new FibonacciBackoff({
min: 10,
max: 10000,
jitter: 0
});
```

The values shown above are the defaults.

`FixedBackoff`

is a bit different, and accepts an array of integers >= 0. `min`

and `max`

are invalid since the sequence is explicit. Jitter is accepted, however.

```
new FixedBackoff({
sequence: [100, 300, 5000, ...],
jitter: 0
});
```

### backoff.next()

Returns the next value in the sequence, with jitter applied (if any). Will not exceed the value of `max`

, except by some amount of jitter.

`backoff.next()`

will always return an integer `>= 0`

.

### backoff.reset()

Resets the sequence to its initial state.

# Options

### min

Specifies the starting/minimum value of the sequence.

### max

Specifies the maximum value of the sequence. Calls to `next`

will not increase the sequence above this value.

### step

Used only for `LinearBackoff`

. This value is added to the previous value to arrive at the next value in the sequence.

### factor

Used only for `ExponentialBackoff`

. This value is multiplied by the previous value to arrive at the next value in the sequence.

### sequence

Used only for `FixedBackoff`

. Must be an array of one or more integers >= 0. It need not be monotonically increasing. Specifies the values to produce in sequence.

### jitter

A number between 0 and 1, inclusive. The `jitter`

value specifies a percentage of the difference between the current and next values, centered on the current value. Jitter is cumulative.

Example:

In a linear sequence, if the current value is `100`

, the step is `50`

, and the jitter is `0.5`

, the result of `backoff.next()`

will be a random value between `87.5`

and `112.5`

:

- The difference between
`100`

and`150`

is`50`

`50`

multiplied by the jitter value is`25`

- A range of
`25`

centered around`100`

is`87.5`

-`112.5`

The range of values used for jitter varies slightly depending on the backoff strategy:

- For linear, the range is the same as the step.
- For exponential, the range is the difference between the previous value and the current value. The previous value is calculated from the initial value when applicable.
- For fibonacci, the range is the difference between the last value in the sequence and the current value in the sequence. When these are the same (e.g. at the beginning of a sequence), the range is the same as the current value.
- For fixed backoff, the range is the difference between the previous value and the current value, or the first value when the backoff is in its initial state.

The point of the `jitter`

option is to vary values such as reconnect times from clients when a server restarts to avoid everything trying to reconnect at the same time.