Add preserveHooks option for retryWithMergedOptions

sindresorhus · sindresorhus · commit 1abeba4d112e · 2025-10-10T00:39:47.000+09:00
Fixes #2347
diff --git a/documentation/9-hooks.md b/documentation/9-hooks.md
@@ -224,9 +224,15 @@ Each function should return the response. This is especially useful when you wan
 > - When using the Stream API, this hook is ignored.
 
 **Note:**
-> - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. If the retry is successful, all remaining `afterResponse` hooks will be called. In case of an error, `beforeRetry` hooks will be called instead.
+> - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. By default, remaining `afterResponse` hooks are removed to prevent duplicate execution. To preserve remaining hooks on retry, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. In case of an error, `beforeRetry` hooks will be called instead.
 Meanwhile the `init`, `beforeRequest` , `beforeRedirect` as well as already executed `afterResponse` hooks will be skipped.
 
+**Note:**
+> - To preserve remaining `afterResponse` hooks after calling `retryWithMergedOptions`, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. This is useful when you want hooks to run on retried requests.
+
+**Warning:**
+> - Be cautious when using `preserveHooks: true`. If a hook unconditionally calls `retryWithMergedOptions` with `preserveHooks: true`, it will create an infinite retry loop. Always ensure hooks have proper conditional logic to avoid infinite retries.
+
 ```js
 import got from 'got';
 
@@ -264,6 +270,37 @@ const instance = got.extend({
 });
 ```
 
+**Example with `preserveHooks`:**
+
+```js
+import got from 'got';
+
+const instance = got.extend({
+	hooks: {
+		afterResponse: [
+			(response, retryWithMergedOptions) => {
+				if (response.statusCode === 401) {
+					return retryWithMergedOptions({
+						headers: {
+							authorization: getNewToken()
+						},
+						preserveHooks: true  // Keep remaining hooks
+					});
+				}
+
+				return response;
+			},
+			(response) => {
+				// This hook will run on the retried request
+				// (the original request is interrupted when the first hook triggers a retry)
+				console.log('Response received:', response.statusCode);
+				return response;
+			}
+		]
+	}
+});
+```
+
 #### `beforeError`
 
 **Type: `BeforeErrorHook[]`**\
diff --git a/source/as-promise/index.ts b/source/as-promise/index.ts
@@ -87,6 +87,8 @@ export default function asPromise<T>(firstRequest?: Request): CancelableRequest<
 						// @ts-expect-error TS doesn't notice that CancelableRequest is a Promise
 						// eslint-disable-next-line no-await-in-loop
 						response = await hook(response, async (updatedOptions): CancelableRequest<Response> => {
+							const preserveHooks = updatedOptions.preserveHooks ?? false;
+
 							options.merge(updatedOptions);
 							options.prefixUrl = '';
 
@@ -96,7 +98,10 @@ export default function asPromise<T>(firstRequest?: Request): CancelableRequest<
 
 							// Remove any further hooks for that request, because we'll call them anyway.
 							// The loop continues. We don't want duplicates (asPromise recursion).
-							options.hooks.afterResponse = options.hooks.afterResponse.slice(0, index);
+							// Unless preserveHooks is true, in which case we keep the remaining hooks.
+							if (!preserveHooks) {
+								options.hooks.afterResponse = options.hooks.afterResponse.slice(0, index);
+							}
 
 							throw new RetryError(request);
 						});
diff --git a/source/core/options.ts b/source/core/options.ts
@@ -305,9 +305,15 @@ export type Hooks = {
 	> - When using the Stream API, this hook is ignored.
 
 	**Note:**
-	> - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. If the retry is successful, all remaining `afterResponse` hooks will be called. In case of an error, `beforeRetry` hooks will be called instead.
+	> - Calling the `retryWithMergedOptions` function will trigger `beforeRetry` hooks. By default, remaining `afterResponse` hooks are removed to prevent duplicate execution. To preserve remaining hooks on retry, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. In case of an error, `beforeRetry` hooks will be called instead.
 	Meanwhile the `init`, `beforeRequest` , `beforeRedirect` as well as already executed `afterResponse` hooks will be skipped.
 
+	**Note:**
+	> - To preserve remaining `afterResponse` hooks after calling `retryWithMergedOptions`, set `preserveHooks: true` in the options passed to `retryWithMergedOptions`. This is useful when you want hooks to run on retried requests.
+
+	**Warning:**
+	> - Be cautious when using `preserveHooks: true`. If a hook unconditionally calls `retryWithMergedOptions` with `preserveHooks: true`, it will create an infinite retry loop. Always ensure hooks have proper conditional logic to avoid infinite retries.
+
 	@example
 	```
 	import got from 'got';
@@ -345,6 +351,37 @@ export type Hooks = {
 		mutableDefaults: true
 	});
 	```
+
+	@example
+	```
+	// Example with preserveHooks
+	import got from 'got';
+
+	const instance = got.extend({
+		hooks: {
+			afterResponse: [
+				(response, retryWithMergedOptions) => {
+					if (response.statusCode === 401) {
+						return retryWithMergedOptions({
+							headers: {
+								authorization: getNewToken()
+							},
+							preserveHooks: true  // Keep remaining hooks
+						});
+					}
+
+					return response;
+				},
+				(response) => {
+					// This hook will run on the retried request
+					// (the original request is interrupted when the first hook triggers a retry)
+					console.log('Response received:', response.statusCode);
+					return response;
+				}
+			]
+		}
+	});
+	```
 	*/
 	afterResponse: AfterResponseHook[];
 };
@@ -678,6 +715,7 @@ export type OptionsInit =
 	& {
 		hooks?: Partial<Hooks>;
 		retry?: Partial<RetryOptions>;
+		preserveHooks?: boolean;
 	};
 
 const globalCache = new Map();
@@ -1135,6 +1173,11 @@ export default class Options {
 					continue;
 				}
 
+				// Never merge `preserveHooks` - it's a control flag, not a persistent option
+				if (key === 'preserveHooks') {
+					continue;
+				}
+
 				if (!(key in this)) {
 					throw new Error(`Unexpected option: ${key}`);
 				}
diff --git a/test/hooks.ts b/test/hooks.ts
@@ -774,6 +774,185 @@ test('does not throw on afterResponse retry HTTP failure if throwHttpErrors is f
 	t.is(statusCode, 500);
 });
 
+test('afterResponse preserveHooks keeps remaining hooks on retry', withServer, async (t, server, got) => {
+	server.get('/', (request, response) => {
+		if (request.headers.token !== 'unicorn') {
+			response.statusCode = 401;
+		}
+
+		response.end();
+	});
+
+	let firstHookCalls = 0;
+	let secondHookCalls = 0;
+
+	const {statusCode} = await got({
+		hooks: {
+			afterResponse: [
+				(response, retryWithMergedOptions) => {
+					firstHookCalls++;
+
+					if (response.statusCode === 401) {
+						return retryWithMergedOptions({
+							headers: {
+								token: 'unicorn',
+							},
+							preserveHooks: true,
+						});
+					}
+
+					return response;
+				},
+				response => {
+					secondHookCalls++;
+					return response;
+				},
+			],
+		},
+	});
+
+	t.is(statusCode, 200);
+	t.is(firstHookCalls, 2); // Called for both original and retry
+	t.is(secondHookCalls, 1); // Called only on retry (original was interrupted by RetryError)
+});
+
+test('afterResponse without preserveHooks skips remaining hooks on retry', withServer, async (t, server, got) => {
+	server.get('/', (request, response) => {
+		if (request.headers.token !== 'unicorn') {
+			response.statusCode = 401;
+		}
+
+		response.end();
+	});
+
+	let firstHookCalls = 0;
+	let secondHookCalls = 0;
+
+	const {statusCode} = await got({
+		hooks: {
+			afterResponse: [
+				(response, retryWithMergedOptions) => {
+					firstHookCalls++;
+
+					if (response.statusCode === 401) {
+						return retryWithMergedOptions({
+							headers: {
+								token: 'unicorn',
+							},
+						});
+					}
+
+					return response;
+				},
+				response => {
+					secondHookCalls++;
+					return response;
+				},
+			],
+		},
+	});
+
+	t.is(statusCode, 200);
+	t.is(firstHookCalls, 1); // Called only on original request (removed from retry by default)
+	t.is(secondHookCalls, 0); // Never called (removed by slice before it could run)
+});
+
+test('afterResponse preserveHooks with three hooks', withServer, async (t, server, got) => {
+	server.get('/', (request, response) => {
+		if (request.headers.token !== 'unicorn') {
+			response.statusCode = 401;
+		}
+
+		response.end();
+	});
+
+	let firstHookCalls = 0;
+	let secondHookCalls = 0;
+	let thirdHookCalls = 0;
+
+	const {statusCode} = await got({
+		hooks: {
+			afterResponse: [
+				(response, retryWithMergedOptions) => {
+					firstHookCalls++;
+
+					if (response.statusCode === 401) {
+						return retryWithMergedOptions({
+							headers: {
+								token: 'unicorn',
+							},
+							preserveHooks: true,
+						});
+					}
+
+					return response;
+				},
+				response => {
+					secondHookCalls++;
+					return response;
+				},
+				response => {
+					thirdHookCalls++;
+					return response;
+				},
+			],
+		},
+	});
+
+	t.is(statusCode, 200);
+	t.is(firstHookCalls, 2); // Called for both original and retry
+	t.is(secondHookCalls, 1); // Called only on retry
+	t.is(thirdHookCalls, 1); // Called only on retry
+});
+
+test('afterResponse preserveHooks when second hook triggers retry', withServer, async (t, server, got) => {
+	server.get('/', (request, response) => {
+		if (request.headers.token !== 'unicorn') {
+			response.statusCode = 401;
+		}
+
+		response.end();
+	});
+
+	let firstHookCalls = 0;
+	let secondHookCalls = 0;
+	let thirdHookCalls = 0;
+
+	const {statusCode} = await got({
+		hooks: {
+			afterResponse: [
+				response => {
+					firstHookCalls++;
+					return response;
+				},
+				(response, retryWithMergedOptions) => {
+					secondHookCalls++;
+
+					if (response.statusCode === 401) {
+						return retryWithMergedOptions({
+							headers: {
+								token: 'unicorn',
+							},
+							preserveHooks: true,
+						});
+					}
+
+					return response;
+				},
+				response => {
+					thirdHookCalls++;
+					return response;
+				},
+			],
+		},
+	});
+
+	t.is(statusCode, 200);
+	t.is(firstHookCalls, 2); // Called for both original and retry (preserved by preserveHooks)
+	t.is(secondHookCalls, 2); // Called for both original and retry
+	t.is(thirdHookCalls, 1); // Called only on retry
+});
+
 test('throwing in a beforeError hook - promise', withServer, async (t, server, got) => {
 	server.get('/', (_request, response) => {
 		response.end('ok');
