Add ky.retry() to force retries from afterResponse hooks

sindresorhus · sindresorhus · commit 909d78696f9b · 2025-10-24T22:00:30.000+07:00
Fixes #778
diff --git a/readme.md b/readme.md
@@ -489,6 +489,8 @@ Default: `[]`
 
 This hook enables you to read and optionally modify the response. The hook function receives normalized request, options, a clone of the response, and a state object. The return value of the hook function will be used by Ky as the response object if it's an instance of [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
 
+You can also force a retry by returning [`ky.retry(options)`](#kyretryoptions). This is useful when you need to retry based on the response body content, even if the response has a successful status code. The retry will respect the `retry.limit` option and be observable in `beforeRetry` hooks.
+
 The `state.retryCount` is `0` for the initial request and increments with each retry. This allows you to distinguish between initial requests and retries, which is useful when you need different behavior for retries (e.g., showing a notification only on the final retry).
 
 ```js
@@ -518,6 +520,20 @@ const response = await ky('https://example.com', {
 				}
 			},
 
+			// Or force retry based on response body content
+			async (request, options, response) => {
+				if (response.status === 200) {
+					const data = await response.clone().json();
+					if (data.error?.code === 'RATE_LIMIT') {
+						// Retry with custom delay from API response
+						return ky.retry({
+							delay: data.error.retryAfter * 1000,
+							reason: 'RATE_LIMIT'
+						});
+					}
+				}
+			},
+
 			// Or show a notification only on the last retry for 5xx errors
 			(request, options, response, {retryCount}) => {
 				if (response.status >= 500 && response.status <= 599) {
@@ -840,6 +856,73 @@ const response = await ky.post('https://example.com', options);
 const text = await ky('https://example.com', options).text();
 ```
 
+### ky.retry(options?)
+
+Force a retry from an `afterResponse` hook.
+
+This allows you to retry a request based on the response content, even if the response has a successful status code. The retry will respect the `retry.limit` option and skip the `shouldRetry` check. The forced retry is observable in `beforeRetry` hooks, where the error will be a `ForceRetryError` with the error name `'ForceRetryError'`.
+
+#### options
+
+Type: `object`
+
+##### delay
+
+Type: `number`
+
+Custom delay in milliseconds before retrying. If not provided, uses the default retry delay calculation based on `retry.delay` configuration.
+
+**Note:** Custom delays bypass jitter and `backoffLimit`. This is intentional, as custom delays often come from server responses (e.g., `Retry-After` headers) and should be respected exactly as specified.
+
+##### reason
+
+Type: `string`
+
+Reason for the retry. This will be included in the error message passed to `beforeRetry` hooks, allowing you to distinguish between different types of forced retries.
+
+#### Example
+
+```js
+import ky, {isForceRetryError} from 'ky';
+
+const api = ky.extend({
+	hooks: {
+		afterResponse: [
+			async (request, options, response) => {
+				// Retry based on response body content
+				if (response.status === 200) {
+					const data = await response.clone().json();
+
+					// Simple retry with default delay
+					if (data.error?.code === 'TEMPORARY_ERROR') {
+						return ky.retry();
+					}
+
+					// Retry with custom delay from API response
+					if (data.error?.code === 'RATE_LIMIT') {
+						return ky.retry({
+							delay: data.error.retryAfter * 1000,
+							reason: 'RATE_LIMIT'
+						});
+					}
+				}
+			}
+		],
+		beforeRetry: [
+			({error, retryCount}) => {
+				// Observable in beforeRetry hooks
+				if (isForceRetryError(error)) {
+					console.log(`Forced retry #${retryCount}: ${error.message}`);
+					// Example output: "Forced retry #1: Forced retry: RATE_LIMIT"
+				}
+			}
+		]
+	}
+});
+
+const response = await api.get('https://example.com/api');
+```
+
 ### HTTPError
 
 Exposed for `instanceof` checks. The error has a `response` property with the [`Response` object](https://developer.mozilla.org/en-US/docs/Web/API/Response), `request` property with the [`Request` object](https://developer.mozilla.org/en-US/docs/Web/API/Request), and `options` property with normalized options (either passed to `ky` when creating an instance with `ky.create()` or directly when performing the request).
diff --git a/source/core/Ky.ts b/source/core/Ky.ts
@@ -1,5 +1,6 @@
 import {HTTPError} from '../errors/HTTPError.js';
 import {NonError} from '../errors/NonError.js';
+import {ForceRetryError} from '../errors/ForceRetryError.js';
 import type {
 	Input,
 	InternalOptions,
@@ -21,6 +22,7 @@ import {
 	maxSafeTimeout,
 	responseTypes,
 	stop,
+	RetryMarker,
 	supportsAbortController,
 	supportsAbortSignal,
 	supportsFormData,
@@ -44,17 +46,31 @@ export class Ky {
 			let response = await ky.#fetch();
 
 			for (const hook of ky.#options.hooks.afterResponse) {
+				// Clone the response before passing to hook so we can cancel it if needed
+				const clonedResponse = ky.#decorateResponse(response.clone());
+
 				// eslint-disable-next-line no-await-in-loop
 				const modifiedResponse = await hook(
 					ky.request,
 					ky.#getNormalizedOptions(),
-					ky.#decorateResponse(response.clone()),
+					clonedResponse,
 					{retryCount: ky.#retryCount},
 				);
 
 				if (modifiedResponse instanceof globalThis.Response) {
 					response = modifiedResponse;
 				}
+
+				if (modifiedResponse instanceof RetryMarker) {
+					// Cancel both the cloned response passed to the hook and the current response
+					// to prevent resource leaks (especially important in Deno/Bun)
+					// eslint-disable-next-line no-await-in-loop
+					await Promise.all([
+						clonedResponse.body?.cancel(),
+						response.body?.cancel(),
+					]);
+					throw new ForceRetryError(modifiedResponse.options);
+				}
 			}
 
 			ky.#decorateResponse(response);
@@ -86,8 +102,9 @@ export class Ky {
 			return response;
 		};
 
-		const isRetriableMethod = ky.#options.retry.methods.includes(ky.request.method.toLowerCase());
-		const result = (isRetriableMethod ? ky.#retry(function_) : function_())
+		// Always wrap in #retry to catch forced retries from afterResponse hooks
+		// Method retriability is checked in #calculateRetryDelay for non-forced retries
+		const result = ky.#retry(function_)
 			.finally(async () => {
 				const originalRequest = ky.#originalRequest;
 				const cleanupPromises = [];
@@ -293,6 +310,16 @@ export class Ky {
 		// Wrap non-Error throws to ensure consistent error handling
 		const errorObject = error instanceof Error ? error : new NonError(error);
 
+		// Handle forced retry from afterResponse hook - skip method check and shouldRetry
+		if (errorObject instanceof ForceRetryError) {
+			return errorObject.customDelay ?? this.#calculateDelay();
+		}
+
+		// Check if method is retriable for non-forced retries
+		if (!this.#options.retry.methods.includes(this.request.method.toLowerCase())) {
+			throw error;
+		}
+
 		// User-provided shouldRetry function takes precedence over all other checks
 		if (this.#options.retry.shouldRetry !== undefined) {
 			const result = await this.#options.retry.shouldRetry({error: errorObject, retryCount: this.#retryCount});
diff --git a/source/core/constants.ts b/source/core/constants.ts
@@ -62,6 +62,85 @@ export const usualFormBoundarySize = new TextEncoder().encode('------WebKitFormB
 
 export const stop = Symbol('stop');
 
+/**
+Options for forcing a retry via `ky.retry()`.
+*/
+export type ForceRetryOptions = {
+	/**
+	Custom delay in milliseconds before retrying.
+
+	If not provided, uses the default retry delay calculation based on `retry.delay` configuration.
+
+	**Note:** Custom delays bypass jitter and `backoffLimit`. This is intentional, as custom delays often come from server responses (e.g., `Retry-After` headers) and should be respected exactly as specified.
+	*/
+	delay?: number;
+
+	/**
+	Reason for the retry.
+
+	This will be included in the error message passed to `beforeRetry` hooks, allowing you to distinguish between different types of forced retries.
+	*/
+	reason?: string;
+};
+
+/**
+Marker returned by ky.retry() to signal a forced retry from afterResponse hooks.
+*/
+export class RetryMarker {
+	constructor(public options?: ForceRetryOptions) {}
+}
+
+/**
+Force a retry from an `afterResponse` hook.
+
+This allows you to retry a request based on the response content, even if the response has a successful status code. The retry will respect the `retry.limit` option and skip the `shouldRetry` check. The forced retry is observable in `beforeRetry` hooks, where the error will be a `ForceRetryError`.
+
+@param options - Optional configuration for the retry.
+
+@example
+```
+import ky, {isForceRetryError} from 'ky';
+
+const api = ky.extend({
+	hooks: {
+		afterResponse: [
+			async (request, options, response) => {
+				// Retry based on response body content
+				if (response.status === 200) {
+					const data = await response.clone().json();
+
+					// Simple retry with default delay
+					if (data.error?.code === 'TEMPORARY_ERROR') {
+						return ky.retry();
+					}
+
+					// Retry with custom delay from API response
+					if (data.error?.code === 'RATE_LIMIT') {
+						return ky.retry({
+							delay: data.error.retryAfter * 1000,
+							reason: 'RATE_LIMIT'
+						});
+					}
+				}
+			}
+		],
+		beforeRetry: [
+			({error, retryCount}) => {
+				// Observable in beforeRetry hooks
+				if (isForceRetryError(error)) {
+					console.log(`Forced retry #${retryCount}: ${error.message}`);
+					// Example output: "Forced retry #1: Forced retry: RATE_LIMIT"
+				}
+			}
+		]
+	}
+});
+
+const response = await api.get('https://example.com/api');
+```
+*/
+export const retry = (options?: ForceRetryOptions) => new RetryMarker(options);
+
 export const kyOptionKeys: KyOptionsRegistry = {
 	json: true,
 	parseJson: true,
diff --git a/source/errors/ForceRetryError.ts b/source/errors/ForceRetryError.ts
@@ -0,0 +1,17 @@
+import type {ForceRetryOptions} from '../core/constants.js';
+
+/**
+Internal error used to signal a forced retry from afterResponse hooks.
+This is thrown when a user returns ky.retry() from an afterResponse hook.
+*/
+export class ForceRetryError extends Error {
+	override name = 'ForceRetryError' as const;
+	customDelay: number | undefined;
+	reason: string | undefined;
+
+	constructor(options?: ForceRetryOptions) {
+		super(options?.reason ? `Forced retry: ${options.reason}` : 'Forced retry');
+		this.customDelay = options?.delay;
+		this.reason = options?.reason;
+	}
+}
diff --git a/source/index.ts b/source/index.ts
@@ -1,7 +1,7 @@
 /*! MIT License © Sindre Sorhus */
 
 import {Ky} from './core/Ky.js';
-import {requestMethods, stop} from './core/constants.js';
+import {requestMethods, stop, retry} from './core/constants.js';
 import type {KyInstance} from './types/ky.js';
 import type {Input, Options} from './types/options.js';
 import {validateAndMerge} from './utils/merge.js';
@@ -26,6 +26,7 @@ const createInstance = (defaults?: Partial<Options>): KyInstance => {
 	};
 
 	ky.stop = stop;
+	ky.retry = retry;
 
 	return ky as KyInstance;
 };
@@ -63,7 +64,13 @@ export type {KyRequest} from './types/request.js';
 export type {KyResponse} from './types/response.js';
 export {HTTPError} from './errors/HTTPError.js';
 export {TimeoutError} from './errors/TimeoutError.js';
-export {isKyError, isHTTPError, isTimeoutError} from './utils/type-guards.js';
+export {ForceRetryError} from './errors/ForceRetryError.js';
+export {
+	isKyError,
+	isHTTPError,
+	isTimeoutError,
+	isForceRetryError,
+} from './utils/type-guards.js';
 
 // Intentionally not exporting this for now as it's just an implementation detail and we don't want to commit to a certain API yet at least.
 // export {NonError} from './errors/NonError.js';
diff --git a/source/types/hooks.ts b/source/types/hooks.ts
@@ -1,4 +1,4 @@
-import {type stop} from '../core/constants.js';
+import {type stop, type RetryMarker} from '../core/constants.js';
 import type {KyRequest, KyResponse, HTTPError} from '../index.js';
 import type {NormalizedOptions} from './options.js';
 
@@ -43,7 +43,7 @@ export type AfterResponseHook = (
 	options: NormalizedOptions,
 	response: KyResponse,
 	state: AfterResponseState
-) => Response | void | Promise<Response | void>;
+) => Response | RetryMarker | void | Promise<Response | RetryMarker | void>;
 
 export type BeforeErrorState = {
 	/**
@@ -164,6 +164,8 @@ export type Hooks = {
 	/**
 	This hook enables you to read and optionally modify the response. The hook function receives normalized request, options, a clone of the response, and a state object. The return value of the hook function will be used by Ky as the response object if it's an instance of [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response).
 
+	You can also force a retry by returning `ky.retry()` or `ky.retry(options)`. This is useful when you need to retry based on the response body content, even if the response has a successful status code. The retry will respect the retry limit and be observable in `beforeRetry` hooks.
+
 	@default []
 
 	@example
@@ -194,6 +196,20 @@ export type Hooks = {
 					}
 				},
 
+				// Or force retry based on response body content
+				async (request, options, response) => {
+					if (response.status === 200) {
+						const data = await response.clone().json();
+						if (data.error?.code === 'RATE_LIMIT') {
+							// Force retry with custom delay from API response
+							return ky.retry({
+								delay: data.error.retryAfter * 1000,
+								reason: 'RATE_LIMIT'
+							});
+						}
+					}
+				},
+
 				// Or show a notification only on the last retry for 5xx errors
 				(request, options, response, {retryCount}) => {
 					if (response.status >= 500 && response.status <= 599) {
diff --git a/source/types/ky.ts b/source/types/ky.ts
diff --git a/source/utils/type-guards.ts b/source/utils/type-guards.ts
diff --git a/test/hooks.ts b/test/hooks.ts
