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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168 |
x11
x11
x11
x16
x16
x16
x16
x11
x11
x11
x11
x24
x24
x24
x24
x24
x24
x24
x24
x25
x25
x25
x24
x25
x25
x25
x24
x25
x25
x25
x34
x24
x54
x54
x54
x104
x108
x108
x124
x124
x124
x124
x124
x124
x124
x124
x100
x100
x24 |
|
// Copyright 2018-2025 the Deno authors. MIT license.
// This module is browser compatible.
import { exponentialBackoffWithJitter } from "./_util.ts";
/**
* Error thrown in {@linkcode retry} once the maximum number of failed attempts
* has been reached.
*
* @example Usage
* ```ts no-assert ignore
* import { RetryError } from "@std/async/retry";
*
* throw new RetryError({ foo: "bar" }, 3);
* ```
*/
export class RetryError extends Error {
/**
* Constructs a new {@linkcode RetryError} instance.
*
* @param cause the cause for this error.
* @param attempts the number of retry attempts made.
*/
constructor(cause: unknown, attempts: number) {
super(`Retrying exceeded the maxAttempts (${attempts}).`);
this.name = "RetryError";
this.cause = cause;
}
}
/** Options for {@linkcode retry}. */
export interface RetryOptions {
/**
* How much to backoff after each retry.
*
* @default {2}
*/
multiplier?: number;
/**
* The maximum milliseconds between attempts.
*
* @default {60000}
*/
maxTimeout?: number;
/**
* The maximum amount of attempts until failure.
*
* @default {5}
*/
maxAttempts?: number;
/**
* The initial and minimum amount of milliseconds between attempts.
*
* @default {1000}
*/
minTimeout?: number;
/**
* Amount of jitter to introduce to the time between attempts. This is `1`
* for full jitter by default.
*
* @default {1}
*/
jitter?: number;
}
/**
* Calls the given (possibly asynchronous) function up to `maxAttempts` times.
* Retries as long as the given function throws. If the attempts are exhausted,
* throws a {@linkcode RetryError} with `cause` set to the inner exception.
*
* The backoff is calculated by multiplying `minTimeout` with `multiplier` to the power of the current attempt counter (starting at 0 up to `maxAttempts - 1`). It is capped at `maxTimeout` however.
* How long the actual delay is, depends on `jitter`.
*
* When `jitter` is the default value of `1`, waits between two attempts for a
* randomized amount between 0 and the backoff time. With the default options
* the maximal delay will be `15s = 1s + 2s + 4s + 8s`. If all five attempts
* are exhausted the mean delay will be `9.5s = ½(4s + 15s)`.
*
* When `jitter` is `0`, waits the full backoff time.
*
* @example Example configuration 1
* ```ts no-assert
* import { retry } from "@std/async/retry";
* const req = async () => {
* // some function that throws sometimes
* };
*
* // Below resolves to the first non-error result of `req`
* const retryPromise = await retry(req, {
* multiplier: 2,
* maxTimeout: 60000,
* maxAttempts: 5,
* minTimeout: 100,
* jitter: 1,
* });
* ```
*
* @example Example configuration 2
* ```ts no-assert
* import { retry } from "@std/async/retry";
* const req = async () => {
* // some function that throws sometimes
* };
*
* // Make sure we wait at least 1 minute, but at most 2 minutes
* const retryPromise = await retry(req, {
* multiplier: 2.34,
* maxTimeout: 80000,
* maxAttempts: 7,
* minTimeout: 1000,
* jitter: 0.5,
* });
* ```
*
* @typeParam T The return type of the function to retry and returned promise.
* @param fn The function to retry.
* @param options Additional options.
* @returns The promise that resolves with the value returned by the function to retry.
*/
export async function retry<T>(
fn: (() => Promise<T>) | (() => T),
options?: RetryOptions,
): Promise<T> {
const {
multiplier = 2,
maxTimeout = 60000,
maxAttempts = 5,
minTimeout = 1000,
jitter = 1,
} = options ?? {};
if (maxTimeout <= 0) {
throw new TypeError(
`Cannot retry as 'maxTimeout' must be positive: current value is ${maxTimeout}`,
);
}
if (minTimeout > maxTimeout) {
throw new TypeError(
`Cannot retry as 'minTimeout' must be <= 'maxTimeout': current values 'minTimeout=${minTimeout}', 'maxTimeout=${maxTimeout}'`,
);
}
if (jitter > 1) {
throw new TypeError(
`Cannot retry as 'jitter' must be <= 1: current value is ${jitter}`,
);
}
let attempt = 0;
while (true) {
try {
return await fn();
} catch (error) {
if (attempt + 1 >= maxAttempts) {
throw new RetryError(error, maxAttempts);
}
const timeout = exponentialBackoffWithJitter(
maxTimeout,
minTimeout,
attempt,
multiplier,
jitter,
);
await new Promise((r) => setTimeout(r, timeout));
}
attempt++;
}
}
|