forked from sindresorhus/p-retry
-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.d.ts
134 lines (102 loc) · 4.15 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
import {type OperationOptions} from 'retry';
export class AbortError extends Error {
readonly name: 'AbortError';
readonly originalError: Error;
/**
Abort retrying and reject the promise.
@param message - An error message or a custom error.
*/
constructor(message: string | Error);
}
export type FailedAttemptError = {
readonly attemptNumber: number;
readonly retriesLeft: number;
} & Error;
export type Options = {
/**
Callback invoked on each retry. Receives the error thrown by `input` as the first argument with properties `attemptNumber` and `retriesLeft` which indicate the current attempt number and the number of attempts left, respectively.
The `onFailedAttempt` function can return a promise. For example, to add a [delay](https://github.com/sindresorhus/delay):
```
import pRetry from 'p-retry';
import delay from 'delay';
const run = async () => { ... };
const result = await pRetry(run, {
onFailedAttempt: async error => {
console.log('Waiting for 1 second before retrying');
await delay(1000);
}
});
```
If the `onFailedAttempt` function throws, all retries will be aborted and the original promise will reject with the thrown error.
*/
readonly onFailedAttempt?: (error: FailedAttemptError) => void | Promise<void>;
/**
Decide if a retry should occur based on the error. Returning true triggers a retry, false aborts with the error.
It is not called for `TypeError` (except network errors) and `AbortError`.
@param error - The error thrown by the input function.
@example
```
import pRetry from 'p-retry';
const run = async () => { … };
const result = await pRetry(run, {
shouldRetry: error => !(error instanceof CustomError);
});
```
In the example above, the operation will be retried unless the error is an instance of `CustomError`.
*/
readonly shouldRetry?: (error: FailedAttemptError) => boolean | Promise<boolean>;
/**
You can abort retrying using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
```
import pRetry from 'p-retry';
const run = async () => { … };
const controller = new AbortController();
cancelButton.addEventListener('click', () => {
controller.abort(new Error('User clicked cancel button'));
});
try {
await pRetry(run, {signal: controller.signal});
} catch (error) {
console.log(error.message);
//=> 'User clicked cancel button'
}
```
*/
readonly signal?: AbortSignal;
} & OperationOptions;
/**
Returns a `Promise` that is fulfilled when calling `input` returns a fulfilled promise. If calling `input` returns a rejected promise, `input` is called again until the max retries are reached, it then rejects with the last rejection reason.
Does not retry on most `TypeErrors`, with the exception of network errors. This is done on a best case basis as different browsers have different [messages](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch#Checking_that_the_fetch_was_successful) to indicate this.
See [whatwg/fetch#526 (comment)](https://github.com/whatwg/fetch/issues/526#issuecomment-554604080)
@param input - Receives the number of attempts as the first argument and is expected to return a `Promise` or any value.
@param options - Options are passed to the [`retry`](https://github.com/tim-kos/node-retry#retryoperationoptions) module.
@example
```
import pRetry, {AbortError} from 'p-retry';
import fetch from 'node-fetch';
const run = async () => {
const response = await fetch('https://sindresorhus.com/unicorn');
// Abort retrying if the resource doesn't exist
if (response.status === 404) {
throw new AbortError(response.statusText);
}
return response.blob();
};
console.log(await pRetry(run, {retries: 5}));
// With the `onFailedAttempt` option:
const result = await pRetry(run, {
onFailedAttempt: error => {
console.log(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
// 1st request => Attempt 1 failed. There are 4 retries left.
// 2nd request => Attempt 2 failed. There are 3 retries left.
// …
},
retries: 5
});
console.log(result);
```
*/
export default function pRetry<T>(
input: (attemptCount: number) => PromiseLike<T> | T,
options?: Options
): Promise<T>;