1 | import {type OperationOptions} from 'retry';
|
2 |
|
3 | export class AbortError extends Error {
|
4 | readonly name: 'AbortError';
|
5 | readonly originalError: Error;
|
6 |
|
7 | /**
|
8 | Abort retrying and reject the promise.
|
9 |
|
10 | @param message - An error message or a custom error.
|
11 | */
|
12 | constructor(message: string | Error);
|
13 | }
|
14 |
|
15 | export type FailedAttemptError = {
|
16 | readonly attemptNumber: number;
|
17 | readonly retriesLeft: number;
|
18 | } & Error;
|
19 |
|
20 | export type Options = {
|
21 | /**
|
22 | 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.
|
23 |
|
24 | The `onFailedAttempt` function can return a promise. For example, to add a [delay](https://github.com/sindresorhus/delay):
|
25 |
|
26 | ```
|
27 | import pRetry from 'p-retry';
|
28 | import delay from 'delay';
|
29 |
|
30 | const run = async () => { ... };
|
31 |
|
32 | const result = await pRetry(run, {
|
33 | onFailedAttempt: async error => {
|
34 | console.log('Waiting for 1 second before retrying');
|
35 | await delay(1000);
|
36 | }
|
37 | });
|
38 | ```
|
39 |
|
40 | If the `onFailedAttempt` function throws, all retries will be aborted and the original promise will reject with the thrown error.
|
41 | */
|
42 | readonly onFailedAttempt?: (error: FailedAttemptError) => void | Promise<void>;
|
43 |
|
44 | /**
|
45 | You can abort retrying using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
|
46 |
|
47 | ```
|
48 | import pRetry from 'p-retry';
|
49 |
|
50 | const run = async () => { … };
|
51 | const controller = new AbortController();
|
52 |
|
53 | cancelButton.addEventListener('click', () => {
|
54 | controller.abort(new Error('User clicked cancel button'));
|
55 | });
|
56 |
|
57 | try {
|
58 | await pRetry(run, {signal: controller.signal});
|
59 | } catch (error) {
|
60 | console.log(error.message);
|
61 | //=> 'User clicked cancel button'
|
62 | }
|
63 | ```
|
64 | */
|
65 | readonly signal?: AbortSignal;
|
66 | } & OperationOptions;
|
67 |
|
68 | /**
|
69 | 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.
|
70 |
|
71 | 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.
|
72 | See [whatwg/fetch#526 (comment)](https://github.com/whatwg/fetch/issues/526#issuecomment-554604080)
|
73 |
|
74 | @param input - Receives the number of attempts as the first argument and is expected to return a `Promise` or any value.
|
75 | @param options - Options are passed to the [`retry`](https://github.com/tim-kos/node-retry#retryoperationoptions) module.
|
76 |
|
77 | @example
|
78 | ```
|
79 | import pRetry, {AbortError} from 'p-retry';
|
80 | import fetch from 'node-fetch';
|
81 |
|
82 | const run = async () => {
|
83 | const response = await fetch('https://sindresorhus.com/unicorn');
|
84 |
|
85 | // Abort retrying if the resource doesn't exist
|
86 | if (response.status === 404) {
|
87 | throw new AbortError(response.statusText);
|
88 | }
|
89 |
|
90 | return response.blob();
|
91 | };
|
92 |
|
93 | console.log(await pRetry(run, {retries: 5}));
|
94 |
|
95 | // With the `onFailedAttempt` option:
|
96 | const result = await pRetry(run, {
|
97 | onFailedAttempt: error => {
|
98 | console.log(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
|
99 | // 1st request => Attempt 1 failed. There are 4 retries left.
|
100 | // 2nd request => Attempt 2 failed. There are 3 retries left.
|
101 | // …
|
102 | },
|
103 | retries: 5
|
104 | });
|
105 |
|
106 | console.log(result);
|
107 | ```
|
108 | */
|
109 | export default function pRetry<T>(
|
110 | input: (attemptCount: number) => PromiseLike<T> | T,
|
111 | options?: Options
|
112 | ): Promise<T>;
|