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