90 lines
2.4 KiB
Markdown
90 lines
2.4 KiB
Markdown
|
# exponential-backoff
|
||
|
|
|
||
|
|
A utility that allows retrying a function with an exponential delay between attempts.
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
```
|
||
|
|
npm i exponential-backoff
|
||
|
|
```
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
The `backOff<T>` function takes a promise-returning function to retry, and an optional `BackOffOptions` object. It returns a `Promise<T>`.
|
||
|
|
|
||
|
|
```ts
|
||
|
|
function backOff<T>(
|
||
|
|
request: () => Promise<T>,
|
||
|
|
options?: BackOffOptions
|
||
|
|
): Promise<T>;
|
||
|
|
```
|
||
|
|
|
||
|
|
Here is an example retrying a function that calls a hypothetical weather endpoint:
|
||
|
|
|
||
|
|
```js
|
||
|
|
import { backOff } from "exponential-backoff";
|
||
|
|
|
||
|
|
function getWeather() {
|
||
|
|
return fetch("weather-endpoint");
|
||
|
|
}
|
||
|
|
|
||
|
|
async function main() {
|
||
|
|
try {
|
||
|
|
const response = await backOff(() => getWeather());
|
||
|
|
// process response
|
||
|
|
} catch (e) {
|
||
|
|
// handle error
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
main();
|
||
|
|
```
|
||
|
|
|
||
|
|
Migrating across major versions? Here are our [breaking changes](https://github.com/coveo/exponential-backoff/tree/master/doc/migration-guide.md).
|
||
|
|
|
||
|
|
### `BackOffOptions`
|
||
|
|
|
||
|
|
- `delayFirstAttempt?: boolean`
|
||
|
|
|
||
|
|
Decides whether the `startingDelay` should be applied before the first call. If `false`, the first call will occur without a delay.
|
||
|
|
|
||
|
|
Default value is `false`.
|
||
|
|
|
||
|
|
- `jitter?: JitterType | string`
|
||
|
|
|
||
|
|
Decides whether a [jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) should be applied to the delay. Possible values are `full` and `none`.
|
||
|
|
|
||
|
|
Default value is `none`.
|
||
|
|
|
||
|
|
- `maxDelay?: number`
|
||
|
|
|
||
|
|
The maximum delay, in milliseconds, between two consecutive attempts.
|
||
|
|
|
||
|
|
Default value is `Infinity`.
|
||
|
|
|
||
|
|
- `numOfAttempts?: number`
|
||
|
|
|
||
|
|
The maximum number of times to attempt the function.
|
||
|
|
|
||
|
|
Default value is `10`.
|
||
|
|
|
||
|
|
Minimum value is `1`.
|
||
|
|
|
||
|
|
- `retry?: (e: any, attemptNumber: number) => boolean | Promise<boolean>`
|
||
|
|
|
||
|
|
The `retry` function can be used to run logic after every failed attempt (e.g. logging a message, assessing the last error, etc.). It is called with the last error and the upcoming attempt number. Returning `true` will retry the function as long as the `numOfAttempts` has not been exceeded. Returning `false` will end the execution.
|
||
|
|
|
||
|
|
Default value is a function that always returns `true`.
|
||
|
|
|
||
|
|
- `startingDelay?: number`
|
||
|
|
|
||
|
|
The delay, in milliseconds, before executing the function for the first time.
|
||
|
|
|
||
|
|
Default value is `100` ms.
|
||
|
|
|
||
|
|
- `timeMultiple?: number`
|
||
|
|
|
||
|
|
The `startingDelay` is multiplied by the `timeMultiple` to increase the delay between reattempts.
|
||
|
|
|
||
|
|
Default value is `2`.
|