Stop decorating errors

sindresorhus · sindresorhus · commit bff36bb860a8 · 2025-05-06T21:47:03.000+07:00
Fixes #25
diff --git a/index.d.ts b/index.d.ts
@@ -10,14 +10,15 @@ export class AbortError extends Error {
 	constructor(message: string | Error);
 }
 
-export type FailedAttemptError = {
+export type RetryContext = {
+	readonly error: Error;
 	readonly attemptNumber: number;
 	readonly retriesLeft: number;
-} & Error;
+};
 
 export type Options = {
 	/**
-	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.
+	Callback invoked on each retry. Receives a context object containing the error and retry state information.
 
 	@example
 	```
@@ -34,8 +35,8 @@ export type Options = {
 	};
 
 	const result = await pRetry(run, {
-		onFailedAttempt: error => {
-			console.log(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
+		onFailedAttempt: ({error, attemptNumber, retriesLeft}) => {
+			console.log(`Attempt ${attemptNumber} failed. There are ${retriesLeft} retries left.`);
 			// 1st request => Attempt 1 failed. There are 5 retries left.
 			// 2nd request => Attempt 2 failed. There are 4 retries left.
 			// …
@@ -56,7 +57,7 @@ export type Options = {
 	const run = async () => { … };
 
 	const result = await pRetry(run, {
-		onFailedAttempt: async error => {
+		onFailedAttempt: async () => {
 			console.log('Waiting for 1 second before retrying');
 			await delay(1000);
 		}
@@ -65,29 +66,27 @@ export type Options = {
 
 	If the `onFailedAttempt` function throws, all retries will be aborted and the original promise will reject with the thrown error.
 	*/
-	readonly onFailedAttempt?: (error: FailedAttemptError) => void | Promise<void>;
+	readonly onFailedAttempt?: (context: RetryContext) => void | Promise<void>;
 
 	/**
-	Decide if a retry should occur based on the error. Returning true triggers a retry, false aborts with the error.
+	Decide if a retry should occur based on the context. Returning true triggers a retry, false aborts with the error.
 
 	It is not called for `TypeError` (except network errors) and `AbortError`.
 
-	@param error - The error thrown by the input function.
-
 	@example
 	```
 	import pRetry from 'p-retry';
 
 	const run = async () => { … };
 
 	const result = await pRetry(run, {
-		shouldRetry: error => !(error instanceof CustomError);
+		shouldRetry: ({error, attemptNumber, retriesLeft}) => !(error instanceof CustomError);
 	});
 	```
 
 	In the example above, the operation will be retried unless the error is an instance of `CustomError`.
 	*/
-	readonly shouldRetry?: (error: FailedAttemptError) => boolean | Promise<boolean>;
+	readonly shouldRetry?: (context: RetryContext) => boolean | Promise<boolean>;
 
 	/**
 	The maximum amount of times to retry the operation.
@@ -175,7 +174,6 @@ Does not retry on most `TypeErrors`, with the exception of network errors. This
 @example
 ```
 import pRetry, {AbortError} from 'p-retry';
-import fetch from 'node-fetch';
 
 const run = async () => {
 	const response = await fetch('https://sindresorhus.com/unicorn');
diff --git a/index.js b/index.js
@@ -17,13 +17,15 @@ export class AbortError extends Error {
 	}
 }
 
-const decorateErrorWithCounts = (error, attemptNumber, options) => {
+const createRetryContext = (error, attemptNumber, options) => {
 	// Minus 1 from attemptNumber because the first attempt does not count as a retry
 	const retriesLeft = options.retries - (attemptNumber - 1);
 
-	error.attemptNumber = attemptNumber;
-	error.retriesLeft = retriesLeft;
-	return error;
+	return Object.freeze({
+		error,
+		attemptNumber,
+		retriesLeft,
+	});
 };
 
 function calculateDelay(attempt, options) {
@@ -87,16 +89,16 @@ export default async function pRetry(input, options = {}) {
 				throw error;
 			}
 
-			decorateErrorWithCounts(error, attemptNumber, options);
+			const context = createRetryContext(error, attemptNumber, options);
 
 			// Always call onFailedAttempt
-			await options.onFailedAttempt(error);
+			await options.onFailedAttempt(context);
 
 			const currentTime = Date.now();
 			if (
 				currentTime - startTime >= maxRetryTime
 				|| attemptNumber >= options.retries + 1
-				|| !(await options.shouldRetry(error))
+				|| !(await options.shouldRetry(context))
 			) {
 				throw error; // Do not retry, throw the original error
 			}
diff --git a/index.test-d.ts b/index.test-d.ts
@@ -1,5 +1,5 @@
 import {expectType} from 'tsd';
-import pRetry, {AbortError, type FailedAttemptError} from './index.js';
+import pRetry, {AbortError, type RetryContext} from './index.js';
 
 expectType<Promise<number>>(
 	pRetry(async count => {
@@ -9,10 +9,10 @@ expectType<Promise<number>>(
 );
 expectType<Promise<void>>(
 	pRetry(() => {}, { // eslint-disable-line @typescript-eslint/no-empty-function
-		onFailedAttempt(error) {
-			expectType<FailedAttemptError>(error);
-			expectType<number>(error.attemptNumber);
-			expectType<number>(error.retriesLeft);
+		onFailedAttempt(context) {
+			expectType<RetryContext>(context);
+			expectType<number>(context.attemptNumber);
+			expectType<number>(context.retriesLeft);
 		},
 	}),
 );
diff --git a/readme.md b/readme.md
@@ -14,7 +14,6 @@ npm install p-retry
 
 ```js
 import pRetry, {AbortError} from 'p-retry';
-import fetch from 'node-fetch';
 
 const run = async () => {
 	const response = await fetch('https://sindresorhus.com/unicorn');
@@ -48,11 +47,11 @@ Receives the number of attempts as the first argument and is expected to return
 
 Type: `object`
 
-##### onFailedAttempt(error)
+##### onFailedAttempt(context)
 
 Type: `Function`
 
-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.
+Callback invoked on each retry. Receives a context object containing the error and retry state information.
 
 ```js
 import pRetry from 'p-retry';
@@ -68,8 +67,8 @@ const run = async () => {
 };
 
 const result = await pRetry(run, {
-	onFailedAttempt: error => {
-		console.log(`Attempt ${error.attemptNumber} failed. There are ${error.retriesLeft} retries left.`);
+	onFailedAttempt: ({error, attemptNumber, retriesLeft}) => {
+		console.log(`Attempt ${attemptNumber} failed. There are ${retriesLeft} retries left.`);
 		// 1st request => Attempt 1 failed. There are 5 retries left.
 		// 2nd request => Attempt 2 failed. There are 4 retries left.
 		// …
@@ -89,7 +88,7 @@ import delay from 'delay';
 const run = async () => { … };
 
 const result = await pRetry(run, {
-	onFailedAttempt: async error => {
+	onFailedAttempt: async () => {
 		console.log('Waiting for 1 second before retrying');
 		await delay(1000);
 	}
@@ -98,11 +97,11 @@ const result = await pRetry(run, {
 
 If the `onFailedAttempt` function throws, all retries will be aborted and the original promise will reject with the thrown error.
 
-##### shouldRetry(error)
+##### shouldRetry(context)
 
 Type: `Function`
 
-Decide if a retry should occur based on the error. Returning true triggers a retry, false aborts with the error.
+Decide if a retry should occur based on the context. Returning true triggers a retry, false aborts with the error.
 
 It is not called for `TypeError` (except network errors) and `AbortError`.
 
@@ -112,7 +111,7 @@ import pRetry from 'p-retry';
 const run = async () => { … };
 
 const result = await pRetry(run, {
-	shouldRetry: error => !(error instanceof CustomError);
+	shouldRetry: ({error, attemptNumber, retriesLeft}) => !(error instanceof CustomError);
 });
 ```
 
diff --git a/test.js b/test.js
@@ -151,7 +151,7 @@ test('operation stops immediately on AbortError', async t => {
 // 	let index = 0;
 // 	const controller = new AbortController();
 
-// 	await t.throwsAsync(pRetry(async attemptNumber => {
+// 	await t.throwsAsync(pRetry(async ({attemptNumber}) => {
 // 		await delay(40);
 // 		index++;
 // 		if (attemptNumber === 3) {
@@ -201,7 +201,7 @@ test('shouldRetry controls retry behavior', async t => {
 		const error = index < 3 ? shouldRetryError : customError;
 		throw error;
 	}, {
-		async shouldRetry(error) {
+		async shouldRetry({error}) {
 			return error.message === shouldRetryError.message;
 		},
 		retries: 10,
@@ -248,10 +248,10 @@ test('onFailedAttempt provides correct error details', async t => {
 			return attemptNumber === 3 ? fixture : Promise.reject(fixtureError);
 		},
 		{
-			onFailedAttempt(error) {
+			onFailedAttempt({error, attemptNumber: attempt, retriesLeft}) {
 				t.is(error, fixtureError);
-				t.is(error.attemptNumber, ++attemptNumber);
-				t.is(error.retriesLeft, retries - (index - 1));
+				t.is(attempt, ++attemptNumber);
+				t.is(retriesLeft, retries - (index - 1));
 			},
 			retries,
 		},
