1 | export interface RetryOperation {
|
2 | /**
|
3 | * Returns an array of all errors that have been passed to `retryOperation.retry()` so far.
|
4 | * The returning array has the errors ordered chronologically based on when they were passed to
|
5 | * `retryOperation.retry()`, which means the first passed error is at index zero and the last is at the last index.
|
6 | */
|
7 | errors(): Error[];
|
8 |
|
9 | /**
|
10 | * A reference to the error object that occured most frequently.
|
11 | * Errors are compared using the `error.message` property.
|
12 | * If multiple error messages occured the same amount of time, the last error object with that message is returned.
|
13 | *
|
14 | * @return If no errors occured so far the value will be `null`.
|
15 | */
|
16 | mainError(): Error | null;
|
17 |
|
18 | /**
|
19 | * Defines the function that is to be retried and executes it for the first time right away.
|
20 | *
|
21 | * @param fn The function that is to be retried. `currentAttempt` represents the number of attempts
|
22 | * callback has been executed so far.
|
23 | * @param [timeoutOps.timeout] A timeout in milliseconds.
|
24 | * @param [timeoutOps.callback] Callback to execute when the operation takes longer than the timeout.
|
25 | */
|
26 | attempt(fn: (currentAttempt: number) => void, timeoutOps?: AttemptTimeoutOptions): void;
|
27 |
|
28 | /**
|
29 | * Returns `false` when no `error` value is given, or the maximum amount of retries has been reached.
|
30 | * Otherwise it returns `true`, and retries the operation after the timeout for the current attempt number.
|
31 | */
|
32 | retry(err?: Error): boolean;
|
33 |
|
34 | /**
|
35 | * Stops the operation being retried. Useful for aborting the operation on a fatal error etc.
|
36 | */
|
37 | stop(): void;
|
38 |
|
39 | /**
|
40 | * Resets the internal state of the operation object, so that you can call `attempt()` again as if
|
41 | * this was a new operation object.
|
42 | */
|
43 | reset(): void;
|
44 |
|
45 | /**
|
46 | * Returns an int representing the number of attempts it took to call `fn` before it was successful.
|
47 | */
|
48 | attempts(): number;
|
49 | }
|
50 |
|
51 | export interface AttemptTimeoutOptions {
|
52 | /**
|
53 | * A timeout in milliseconds.
|
54 | */
|
55 | timeout?: number | undefined;
|
56 | /**
|
57 | * Callback to execute when the operation takes longer than the timeout.
|
58 | */
|
59 | callback?(): void;
|
60 | }
|
61 |
|
62 | /**
|
63 | * Create a new RetryOperation object.
|
64 | *
|
65 | * @param [options.retries=10] The maximum amount of times to retry the operation.
|
66 | * @param [options.factor=2] The exponential factor to use.
|
67 | * @param [options.minTimeout=1000] The number of milliseconds before starting the first retry.
|
68 | * @param [options.maxTimeout=Infinity] The maximum number of milliseconds between two retries.
|
69 | * @param [options.randomize=false] Randomizes the timeouts by multiplying a factor between 1-2.
|
70 | * @param [options.forever=false] Wether to retry forever.
|
71 | * @param [options.unref=false] Wether to unref the setTimeout's.
|
72 | */
|
73 | export function operation(options?: OperationOptions): RetryOperation;
|
74 |
|
75 | export type OperationOptions = WrapOptions | number[];
|
76 |
|
77 | export interface WrapOptions extends TimeoutsOptions {
|
78 | /**
|
79 | * Whether to retry forever.
|
80 | * @default false
|
81 | */
|
82 | forever?: boolean | undefined;
|
83 | /**
|
84 | * Whether to [unref](https://nodejs.org/api/timers.html#timers_unref) the setTimeout's.
|
85 | * @default false
|
86 | */
|
87 | unref?: boolean | undefined;
|
88 | /**
|
89 | * The maximum time (in milliseconds) that the retried operation is allowed to run.
|
90 | * @default Infinity
|
91 | */
|
92 | maxRetryTime?: number | undefined;
|
93 | }
|
94 |
|
95 | /** Get an array with timeouts and their return values in milliseconds. */
|
96 | export function timeouts(options?: TimeoutsOptions): number[];
|
97 |
|
98 | export interface TimeoutsOptions extends CreateTimeoutOptions {
|
99 | /**
|
100 | * The maximum amount of times to retry the operation.
|
101 | * @default 10
|
102 | */
|
103 | retries?: number | undefined;
|
104 | }
|
105 |
|
106 | /**
|
107 | * Create a new timeout (in milliseconds) based on the given parameters.
|
108 | *
|
109 | * @param attempt Representing for which retry the timeout should be calculated.
|
110 | * @return timeout
|
111 | */
|
112 | export function createTimeout(attempt: number, options?: CreateTimeoutOptions): number;
|
113 |
|
114 | export interface CreateTimeoutOptions {
|
115 | /**
|
116 | * The exponential factor to use.
|
117 | * @default 2
|
118 | */
|
119 | factor?: number | undefined;
|
120 | /**
|
121 | * The number of milliseconds before starting the first retry.
|
122 | * @default 1000
|
123 | */
|
124 | minTimeout?: number | undefined;
|
125 | /**
|
126 | * The maximum number of milliseconds between two retries.
|
127 | * @default Infinity
|
128 | */
|
129 | maxTimeout?: number | undefined;
|
130 | /**
|
131 | * Randomizes the timeouts by multiplying a factor between 1-2.
|
132 | * @default false
|
133 | */
|
134 | randomize?: boolean | undefined;
|
135 | }
|
136 |
|
137 | /**
|
138 | * Wrap all functions of the object with retry.
|
139 | *
|
140 | * @param object The object to be wrapped
|
141 | * @param methods Methods which need to be wrapped
|
142 | */
|
143 | export function wrap(object: object, methods?: string[]): void;
|
144 | export function wrap(object: object, options?: WrapOptions, methods?: string[]): void;
|