Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve README and code comprehensibility #286

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Improve README and code comprehensibility #286

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f95579
refactor: Harmonise names of retryCount and retryNumber
Sidnioulz Sep 25, 2024
9b56bc0
docs: Add examples and mention Retry-After in README
Sidnioulz Sep 25, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 22 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,17 +26,25 @@ axios.get('http://example.com/test') // The first request fails and the second r
result.data; // 'ok'
});

// No retry delay
axiosRetry(axios, { retryDelay: axiosRetry.noDelay });

// Exponential back-off retry delay between requests
axiosRetry(axios, { retryDelay: axiosRetry.exponentialDelay });

// Liner retry delay between requests
// Liner retry delay between requests; note the different function signature
axiosRetry(axios, { retryDelay: axiosRetry.linearDelay() });

// Custom retry delay
axiosRetry(axios, { retryDelay: (retryCount) => {
return retryCount * 1000;
}});

// Exponential back-off retry delay with a custom initial delay
axiosRetry(axios, { retryDelay: (retryCount, error) => {
return axiosRetry.exponentialDelay(retryCount, error, 1000);
}});

// Works with custom axios instances
const client = axios.create({ baseURL: 'http://example.com' });
axiosRetry(client, { retries: 3 });
Expand All @@ -62,15 +70,19 @@ client

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| retries | `Number` | `3` | The number of times to retry before failing. 1 = One retry after first failure |
| retryCondition | `Function` | `isNetworkOrIdempotentRequestError` | A callback to further control if a request should be retried. By default, it retries if it is a network error or a 5xx error on an idempotent request (GET, HEAD, OPTIONS, PUT or DELETE). |
| shouldResetTimeout | `Boolean` | false | Defines if the timeout should be reset between retries |
| retryDelay | `Function` | `function noDelay() { return 0; }` | A callback to further control the delay in milliseconds between retried requests. By default there is no delay between retries. Another option is exponentialDelay ([Exponential Backoff](https://developers.google.com/analytics/devguides/reporting/core/v3/errors#backoff)) or `linearDelay`. The function is passed `retryCount` and `error`. |
| onRetry | `Function` | `function onRetry(retryCount, error, requestConfig) { return; }` | A callback to notify when a retry is about to occur. Useful for tracing and you can any async process for example refresh a token on 401. By default nothing will occur. The function is passed `retryCount`, `error`, and `requestConfig`. |
| onMaxRetryTimesExceeded | `Function` | `function onMaxRetryTimesExceeded(error, retryCount) { return; }` | After all the retries are failed, this callback will be called with the last error before throwing the error. |
| validateResponse | `Function \| null` | `null` | A callback to define whether a response should be resolved or rejected. If null is passed, it will fallback to the axios default (only 2xx status codes are resolved). |
| Name | Type | Default | Description |
| ----------------------- | ------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| retries | `Number` | `3` | The number of times to retry before failing. 1 = One retry after first failure |
| retryCondition | `Function` | `isNetworkOrIdempotentRequestError` | A callback to further control if a request should be retried. By default, it retries if it is a network error or a 5xx error on an idempotent request (GET, HEAD, OPTIONS, PUT or DELETE). |
| shouldResetTimeout | `Boolean` | false | Defines if the timeout should be reset between retries |
| retryDelay | `Function` | `function noDelay() { return 0; }` | A callback to further control the delay in milliseconds between retried requests. By default there is no delay between retries. Another option is exponentialDelay ([Exponential Backoff](https://developers.google.com/analytics/devguides/reporting/core/v3/errors#backoff)) or `linearDelay`. The function is passed `retryCount` and `error`. |
| onRetry | `Function` | `function onRetry(retryCount, error, requestConfig) { return; }` | A callback to notify when a retry is about to occur. Useful for tracing and you can any async process for example refresh a token on 401. By default nothing will occur. The function is passed `retryCount`, `error`, and `requestConfig`. |
| onMaxRetryTimesExceeded | `Function` | `function onMaxRetryTimesExceeded(error, retryCount) { return; }` | After all the retries are failed, this callback will be called with the last error before throwing the error. |
| validateResponse | `Function \| null` | `null` | A callback to define whether a response should be resolved or rejected. If null is passed, it will fallback to the axios default (only 2xx status codes are resolved). |

## Retry-After Header

Note that axios-retry respects the [`Retry-After` response header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After). If a response contains a `Retry-After` header, axios-retry will wait as long as the biggest value between the `Retry-After` header and the configured `retryDelay` option.

## Testing

Expand Down
28 changes: 14 additions & 14 deletions spec/index.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1078,10 +1078,10 @@ describe('isIdempotentRequestError(error)', () => {

describe('exponentialDelay', () => {
it('should return exponential retry delay', () => {
function assertTime(retryNumber) {
const min = Math.pow(2, retryNumber) * 100;
const max = Math.pow(2, retryNumber * 100) * 0.2;
const time = exponentialDelay(retryNumber);
function assertTime(retryCount) {
const min = Math.pow(2, retryCount) * 100;
const max = Math.pow(2, retryCount * 100) * 0.2;
const time = exponentialDelay(retryCount);

expect(time >= min && time <= max).toBe(true);
}
Expand All @@ -1090,10 +1090,10 @@ describe('exponentialDelay', () => {
});

it('should change delay time when specifying delay factor', () => {
function assertTime(retryNumber) {
const min = Math.pow(2, retryNumber) * 1000;
const max = Math.pow(2, retryNumber * 1000) * 0.2;
const time = exponentialDelay(retryNumber, undefined, 1000);
function assertTime(retryCount) {
const min = Math.pow(2, retryCount) * 1000;
const max = Math.pow(2, retryCount * 1000) * 0.2;
const time = exponentialDelay(retryCount, undefined, 1000);

expect(time >= min && time <= max).toBe(true);
}
Expand All @@ -1106,10 +1106,10 @@ describe('linearDelay', () => {
it('should return liner retry delay', () => {
const linearDelayFunc = linearDelay();

function assertTime(retryNumber) {
const time = linearDelayFunc(retryNumber, undefined);
function assertTime(retryCount) {
const time = linearDelayFunc(retryCount, undefined);

expect(time).toBe(100 * retryNumber);
expect(time).toBe(100 * retryCount);
}

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10].forEach(assertTime);
Expand All @@ -1119,10 +1119,10 @@ describe('linearDelay', () => {
const delayFactor = 300;
const linearDelayFunc = linearDelay(delayFactor);

function assertTime(retryNumber) {
const time = linearDelayFunc(retryNumber, undefined);
function assertTime(retryCount) {
const time = linearDelayFunc(retryCount, undefined);

expect(time).toBe(delayFactor * retryNumber);
expect(time).toBe(delayFactor * retryCount);
}

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10].forEach(assertTime);
Expand Down
18 changes: 9 additions & 9 deletions src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,8 +80,8 @@ export interface AxiosRetry {
isSafeRequestError(error: AxiosError): boolean;
isIdempotentRequestError(error: AxiosError): boolean;
isNetworkOrIdempotentRequestError(error: AxiosError): boolean;
exponentialDelay(retryNumber?: number, error?: AxiosError, delayFactor?: number): number;
linearDelay(delayFactor?: number): (retryNumber: number, error: AxiosError | undefined) => number;
exponentialDelay(retryCount?: number, error?: AxiosError, delayFactor?: number): number;
linearDelay(delayFactor?: number): (retryCount: number, error: AxiosError | undefined) => number;
}

declare module 'axios' {
Expand Down Expand Up @@ -155,16 +155,16 @@ export function retryAfter(error: AxiosError | undefined = undefined): number {
return Math.max(0, retryAfterMs);
}

function noDelay(_retryNumber = 0, error: AxiosError | undefined = undefined) {
function noDelay(_retryCount = 0, error: AxiosError | undefined = undefined) {
return Math.max(0, retryAfter(error));
}

export function exponentialDelay(
retryNumber = 0,
retryCount = 0,
error: AxiosError | undefined = undefined,
delayFactor = 100
): number {
const calculatedDelay = 2 ** retryNumber * delayFactor;
const calculatedDelay = 2 ** retryCount * delayFactor;
const delay = Math.max(calculatedDelay, retryAfter(error));
const randomSum = delay * 0.2 * Math.random(); // 0-20% of the delay
return delay + randomSum;
Expand All @@ -173,13 +173,13 @@ export function exponentialDelay(
/**
* Linear delay
* @param {number | undefined} delayFactor - delay factor in milliseconds (default: 100)
* @returns {function} (retryNumber: number, error: AxiosError | undefined) => number
* @returns {function} (retryCount: number, error: AxiosError | undefined) => number
*/
export function linearDelay(
delayFactor: number | undefined = 100
): (retryNumber: number, error: AxiosError | undefined) => number {
return (retryNumber = 0, error = undefined) => {
const delay = retryNumber * delayFactor;
): (retryCount: number, error: AxiosError | undefined) => number {
return (retryCount = 0, error = undefined) => {
const delay = retryCount * delayFactor;
return Math.max(delay, retryAfter(error));
};
}
Expand Down