Add retryDelay to onFailedAttempt context

sindresorhus · sindresorhus · commit 96cce98ea2f9 · 2026-01-25T10:41:35.000+07:00
Fixes #66
diff --git a/index.d.ts b/index.d.ts
@@ -15,6 +15,15 @@ export type RetryContext = {
 	readonly attemptNumber: number;
 	readonly retriesLeft: number;
 	readonly retriesConsumed: number;
+
+	/**
+	The delay in milliseconds before the next retry attempt.
+
+	This is calculated based on `minTimeout`, `factor`, `maxTimeout`, and `randomize` options.
+
+	Note: The actual delay may be shorter if it would exceed `maxRetryTime`.
+	*/
+	readonly retryDelay: number;
 };
 
 export type Options = {
@@ -40,10 +49,10 @@ export type Options = {
 	};
 
 	const result = await pRetry(run, {
-		onFailedAttempt: ({error, attemptNumber, retriesLeft, retriesConsumed}) => {
-			console.log(`Attempt ${attemptNumber} failed. ${retriesLeft} retries left. ${retriesConsumed} retries consumed.`);
-			// 1st request => Attempt 1 failed. 5 retries left. 0 retries consumed.
-			// 2nd request => Attempt 2 failed. 4 retries left. 1 retries consumed.
+		onFailedAttempt: ({error, attemptNumber, retriesLeft, retriesConsumed, retryDelay}) => {
+			console.log(`Attempt ${attemptNumber} failed. Retrying in ${retryDelay}ms. ${retriesLeft} retries left.`);
+			// 1st request => Attempt 1 failed. Retrying in 1000ms. 5 retries left.
+			// 2nd request => Attempt 2 failed. Retrying in 2000ms. 4 retries left.
 			// …
 		},
 		retries: 5
diff --git a/index.js b/index.js
@@ -82,11 +82,15 @@ async function onAttemptFailure({error, attemptNumber, retriesConsumed, startTim
 
 	const maxRetryTime = options.maxRetryTime ?? Number.POSITIVE_INFINITY;
 
+	// Calculate the delay upfront so it can be included in the context
+	const delayTime = calculateDelay(retriesConsumed, options);
+
 	const context = Object.freeze({
 		error: normalizedError,
 		attemptNumber,
 		retriesLeft,
 		retriesConsumed,
+		retryDelay: delayTime,
 	});
 
 	await options.onFailedAttempt(context);
@@ -121,7 +125,6 @@ async function onAttemptFailure({error, attemptNumber, retriesConsumed, startTim
 		return false;
 	}
 
-	const delayTime = calculateDelay(retriesConsumed, options);
 	const finalDelay = Math.min(delayTime, remainingTime);
 
 	options.signal?.throwIfAborted();
diff --git a/readme.md b/readme.md
@@ -71,10 +71,10 @@ const run = async () => {
 };
 
 const result = await pRetry(run, {
-	onFailedAttempt: ({error, attemptNumber, retriesLeft, retriesConsumed}) => {
-		console.log(`Attempt ${attemptNumber} failed. ${retriesLeft} retries left. ${retriesConsumed} retries consumed.`);
-		// 1st request => Attempt 1 failed. 5 retries left. 0 retries consumed.
-		// 2nd request => Attempt 2 failed. 4 retries left. 1 retries consumed.
+	onFailedAttempt: ({error, attemptNumber, retriesLeft, retriesConsumed, retryDelay}) => {
+		console.log(`Attempt ${attemptNumber} failed. Retrying in ${retryDelay}ms. ${retriesLeft} retries left.`);
+		// 1st request => Attempt 1 failed. Retrying in 1000ms. 5 retries left.
+		// 2nd request => Attempt 2 failed. Retrying in 2000ms. 4 retries left.
 		// …
 	},
 	retries: 5
@@ -83,6 +83,13 @@ const result = await pRetry(run, {
 console.log(result);
 ```
 
+The `context` object contains:
+- `error` - The error that was thrown
+- `attemptNumber` - The attempt number (starts at 1)
+- `retriesLeft` - Number of retries remaining
+- `retriesConsumed` - Number of retries consumed so far
+- `retryDelay` - The delay in milliseconds before the next retry (based on `minTimeout`, `factor`, `maxTimeout`, and `randomize`)
+
 The `onFailedAttempt` function can return a promise. For example, to add a [delay](https://github.com/sindresorhus/delay):
 
 ```js
@@ -244,7 +251,7 @@ const response = await fetchWithRetry('https://sindresorhus.com/unicorn');
 ### AbortError(message)
 ### AbortError(error)
 
-Abort retrying and reject the promise. No callbacks functions will be called.
+Abort retrying and reject the promise. No callback functions will be called.
 
 ### message
 
diff --git a/test.js b/test.js
@@ -1,7 +1,6 @@
 import process from 'node:process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import {performance} from 'node:perf_hooks';
 import {execa} from 'execa';
 import test from 'ava';
 import delay from 'delay';
@@ -1267,6 +1266,35 @@ test('shouldConsumeRetry returning false still calls shouldRetry', async t => {
 	t.is(shouldRetryCalls, 1);
 });
 
+test.serial('retryDelay is provided in onFailedAttempt context', async t => {
+	const retryDelays = [];
+	const originalSetTimeout = setTimeout;
+
+	globalThis.setTimeout = (function_, _ms) => originalSetTimeout(function_, 0);
+
+	t.teardown(() => {
+		globalThis.setTimeout = originalSetTimeout;
+	});
+
+	await t.throwsAsync(pRetry(
+		async () => {
+			throw new Error('test');
+		},
+		{
+			retries: 3,
+			factor: 2,
+			minTimeout: 100,
+			randomize: false,
+			onFailedAttempt({retryDelay}) {
+				retryDelays.push(retryDelay);
+			},
+		},
+	));
+
+	// Verify retryDelay follows exponential backoff formula
+	t.deepEqual(retryDelays, [100, 200, 400, 800]);
+});
+
 test.serial('Only consumed retries advance backoff', async t => {
 	let attempts = 0;
 	const timeouts = [];
