Replace retry.resetTimeout with top-level totalTimeout option

Make `timeout` per-attempt by default, matching how every major HTTP client works. Each retry now gets the full timeout value.

Author: sindresorhus

readme.md

@@ -256,10 +256,9 @@ Default:
 - `delay`: `attemptCount => 0.3 * (2 ** (attemptCount - 1)) * 1000`
 - `jitter`: `undefined`
 - `retryOnTimeout`: `false`
-- `resetTimeout`: `false`
 - `shouldRetry`: `undefined`
 
-An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, `resetTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, timeout reset behavior, and custom retry logic.
+An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, and custom retry logic.
 
 If `retry` is a number, it will be used as `limit` and other defaults will remain in place.
 
@@ -281,8 +280,6 @@ The `jitter` option adds random jitter to retry delays to prevent thundering her
 
 The `retryOnTimeout` option determines whether to retry when a request times out. By default, retries are not triggered following a [timeout](#timeout).
 
-The `resetTimeout` option gives each retry attempt the full `timeout` value instead of the remaining budget. By default, `timeout` is a total timeout across all retries, meaning later retries get progressively less time. When `resetTimeout` is `true`, each retry starts with a fresh timeout. If you need both per-request timeout and a total timeout cap, combine `resetTimeout: true` with `signal: AbortSignal.timeout(totalMs)`.
-
 The `shouldRetry` option provides custom retry logic that **takes precedence over the default retry checks** (`retryOnTimeout`, status code checks, etc.) for retriable methods. It is only called after the retry limit and method checks pass.
 
 **Note:** This is different from the `beforeRetry` hook:
@@ -323,21 +320,6 @@ const json = await ky('https://example.com', {
 }).json();
 ```
 
-**Resetting timeout on each retry:**
-
-```js
-import ky from 'ky';
-
-const json = await ky('https://example.com', {
-	timeout: 5000,
-	retry: {
-		limit: 3,
-		retryOnTimeout: true,
-		resetTimeout: true
-	}
-}).json();
-```
-
 **Using jitter to prevent thundering herd:**
 
 ```js
@@ -401,10 +383,33 @@ const json = await ky('https://example.com', {
 Type: `number | false`\
 Default: `10000`
 
-Timeout in milliseconds for getting a response, including any retries. Cannot be greater than 2147483647. Use [`retry.resetTimeout`](#retry) to give each retry attempt the full timeout instead of sharing a single budget across all attempts.
+Timeout in milliseconds for getting a response. Each retry attempt gets the full timeout. Cannot be greater than 2147483647.
 
 If set to `false`, there will be no timeout.
 
+##### totalTimeout
+
+Type: `number | false`\
+Default: `false`
+
+Total timeout in milliseconds for the entire operation, including all retries and delays. Cannot be greater than 2147483647. Throws a `TimeoutError` if exceeded.
+
+This is useful when you want to cap the total time spent on an operation, while still allowing each individual retry to use the full per-attempt `timeout`.
+
+```js
+import ky from 'ky';
+
+// Each attempt gets 5s, but the whole operation must complete within 30s
+const json = await ky('https://example.com', {
+	timeout: 5000,
+	totalTimeout: 30_000,
+	retry: {
+		limit: 3,
+		retryOnTimeout: true,
+	}
+}).json();
+```
+
 ##### hooks
 
 Type: `object<string, Function[]>`\

source/core/Ky.ts

@@ -93,8 +93,12 @@ export class Ky {
 				throw new RangeError(`The \`timeout\` option cannot be greater than ${maxSafeTimeout}`);
 			}
 
-			// Track start time for total timeout across retries
-			if (ky.#startTime === undefined && typeof ky.#options.timeout === 'number') {
+			if (typeof ky.#options.totalTimeout === 'number' && ky.#options.totalTimeout > maxSafeTimeout) {
+				throw new RangeError(`The \`totalTimeout\` option cannot be greater than ${maxSafeTimeout}`);
+			}
+
+			// Track start time for totalTimeout across retries
+			if (ky.#startTime === undefined && typeof ky.#options.totalTimeout === 'number') {
 				ky.#startTime = ky.#getCurrentTime();
 			}
 
@@ -302,6 +306,7 @@ export class Ky {
 			retry: normalizeRetryOptions(options.retry),
 			throwHttpErrors: options.throwHttpErrors ?? true,
 			timeout: options.timeout ?? 10_000,
+			totalTimeout: options.totalTimeout ?? false,
 			fetch: options.fetch ?? globalThis.fetch.bind(globalThis),
 			context: options.context ?? {},
 		};
@@ -698,7 +703,7 @@ export class Ky {
 		const retryDelay = Math.min(await this.#calculateRetryDelay(error), maxSafeTimeout);
 		const delayOptions = this.#userProvidedAbortSignal ? {signal: this.#userProvidedAbortSignal} : {};
 
-		const remainingTimeout = this.#getRemainingTimeout();
+		const remainingTimeout = this.#getRemainingTotalTimeout();
 		if (remainingTimeout !== undefined) {
 			if (remainingTimeout <= 0) {
 				throw new TimeoutError(this.request);
@@ -714,7 +719,7 @@ export class Ky {
 		// Only use user-provided signal for delay, not our internal abortController
 		await delay(retryDelay, delayOptions);
 
-		const remainingTimeoutAfterDelay = this.#getRemainingTimeout();
+		const remainingTimeoutAfterDelay = this.#getRemainingTotalTimeout();
 		if (
 			remainingTimeoutAfterDelay !== undefined
 			&& remainingTimeoutAfterDelay <= 0
@@ -769,7 +774,7 @@ export class Ky {
 			}
 		}
 
-		const remainingTimeoutAfterBeforeRetryHooks = this.#getRemainingTimeout();
+		const remainingTimeoutAfterBeforeRetryHooks = this.#getRemainingTotalTimeout();
 		if (
 			remainingTimeoutAfterBeforeRetryHooks !== undefined
 			&& remainingTimeoutAfterBeforeRetryHooks <= 0
@@ -809,18 +814,29 @@ export class Ky {
 		}
 
 		try {
+			const remainingTotal = this.#getRemainingTotalTimeout();
+			if (remainingTotal !== undefined && remainingTotal <= 0) {
+				throw new TimeoutError(this.request);
+			}
+
 			if (this.#options.timeout === false) {
+				if (remainingTotal !== undefined) {
+					return await timeout(request, nonRequestOptions, this.#abortController, {
+						...this.#options,
+						timeout: remainingTotal,
+					} as TimeoutOptions);
+				}
+
 				return await this.#options.fetch(request, nonRequestOptions);
 			}
 
-			const remainingTimeout = this.#getRemainingTimeout() ?? this.#options.timeout;
-			if (remainingTimeout <= 0) {
-				throw new TimeoutError(this.request);
-			}
+			const effectiveTimeout = remainingTotal === undefined
+				? this.#options.timeout
+				: Math.min(this.#options.timeout, remainingTotal);
 
 			return await timeout(request, nonRequestOptions, this.#abortController, {
 				...this.#options,
-				timeout: remainingTimeout,
+				timeout: effectiveTimeout,
 			} as TimeoutOptions);
 		} catch (error) {
 			if (isRawNetworkError(error)) {
@@ -831,17 +847,13 @@ export class Ky {
 		}
 	}
 
-	#getRemainingTimeout(): number | undefined {
-		if (this.#options.timeout === false) {
+	#getRemainingTotalTimeout(): number | undefined {
+		if (this.#options.totalTimeout === false || this.#startTime === undefined) {
 			return undefined;
 		}
 
-		if (this.#startTime === undefined || this.#options.retry.resetTimeout) {
-			return this.#options.timeout;
-		}
-
 		const elapsed = this.#getCurrentTime() - this.#startTime;
-		return Math.max(0, this.#options.timeout - elapsed);
+		return Math.max(0, this.#options.totalTimeout - elapsed);
 	}
 
 	#getCurrentTime(): number {
@@ -858,6 +870,7 @@ export class Ky {
 				stringifyJson,
 				searchParams,
 				timeout,
+				totalTimeout,
 				throwHttpErrors,
 				fetch,
 				...normalizedOptions

source/core/constants.ts

@@ -250,6 +250,7 @@ export const kyOptionKeys: KyOptionsRegistry = {
 	prefix: true,
 	retry: true,
 	timeout: true,
+	totalTimeout: true,
 	hooks: true,
 	throwHttpErrors: true,
 	onDownloadProgress: true,

source/types/options.ts

@@ -145,7 +145,7 @@ export type KyOptions = {
 	prefix?: URL | string;
 
 	/**
-	An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, `resetTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, timeout reset behavior, and custom retry logic.
+	An object representing `limit`, `methods`, `statusCodes`, `afterStatusCodes`, `maxRetryAfter`, `backoffLimit`, `delay`, `jitter`, `retryOnTimeout`, and `shouldRetry` fields for maximum retry count, allowed methods, allowed status codes, status codes allowed to use the [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, maximum [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) time, backoff limit, delay calculation function, retry jitter, timeout retry behavior, and custom retry logic.
 
 	If `retry` is a number, it will be used as `limit` and other defaults will remain in place.
 
@@ -171,14 +171,40 @@ export type KyOptions = {
 	retry?: RetryOptions | number;
 
 	/**
-	Timeout in milliseconds for getting a response, including any retries. Cannot be greater than 2147483647. Use `retry.resetTimeout` to give each retry attempt the full timeout instead of sharing a single budget across all attempts.
+	Timeout in milliseconds for getting a response. Each retry attempt gets the full timeout. Cannot be greater than 2147483647.
 
 	If set to `false`, there will be no timeout.
 
 	@default 10000
 	*/
 	timeout?: number | false;
 
+	/**
+	Total timeout in milliseconds for the entire operation, including all retries and delays. Cannot be greater than 2147483647. Throws a `TimeoutError` if exceeded.
+
+	This is useful when you want to cap the total time spent on an operation, while still allowing each individual retry to use the full per-attempt `timeout`.
+
+	If set to `false` or not specified, there is no total timeout.
+
+	@default false
+
+	@example
+	```
+	import ky from 'ky';
+
+	// Each attempt gets 5s, but the whole operation must complete within 30s
+	const json = await ky('https://example.com', {
+		timeout: 5000,
+		totalTimeout: 30_000,
+		retry: {
+			limit: 3,
+			retryOnTimeout: true,
+		}
+	}).json();
+	```
+	*/
+	totalTimeout?: number | false;
+
 	/**
 	Hooks allow modifications during the request lifecycle. Hook functions may be async and are run serially.
 	*/
@@ -393,7 +419,7 @@ export interface Options extends KyOptions, Omit<RequestInit, 'headers'> { // es
 
 export type InternalOptions = Required<
 	Omit<Options, 'hooks' | 'retry' | 'context' | 'throwHttpErrors'>,
-'fetch' | 'prefix' | 'timeout'
+'fetch' | 'prefix' | 'timeout' | 'totalTimeout'
 > & {
 	headers: Required<Headers>;
 	hooks: Required<Hooks>;

source/types/retry.ts

@@ -123,31 +123,6 @@ export type RetryOptions = {
 	*/
 	retryOnTimeout?: boolean;
 
-	/**
-	Whether to reset the timeout for each retry attempt.
-
-	By default, the `timeout` option is a total timeout across all retries. When `resetTimeout` is `true`, each retry attempt gets the full `timeout` value instead of the remaining budget.
-
-	If you need both per-request timeout and a total timeout cap, combine `resetTimeout: true` with `signal: AbortSignal.timeout(totalMs)`.
-
-	@default false
-
-	@example
-	```
-	import ky from 'ky';
-
-	const json = await ky('https://example.com', {
-		timeout: 5000,
-		retry: {
-			limit: 3,
-			retryOnTimeout: true,
-			resetTimeout: true
-		}
-	}).json();
-	```
-	*/
-	resetTimeout?: boolean;
-
 	/**
 	A function to determine whether a retry should be attempted.
 

source/utils/normalize.ts

@@ -23,7 +23,6 @@ const defaultRetryOptions: InternalRetryOptions = {
 	delay: attemptCount => 0.3 * (2 ** (attemptCount - 1)) * 1000,
 	jitter: undefined,
 	retryOnTimeout: false,
-	resetTimeout: false,
 };
 
 export const normalizeRetryOptions = (retry: number | RetryOptions = {}): InternalRetryOptions => {

test/hooks.ts

@@ -519,7 +519,7 @@ test('beforeRetry hook is never called for the initial request', async t => {
 	);
 });
 
-test('beforeRequest hook on initial request cannot bypass total timeout budget', async t => {
+test('beforeRequest hook on initial request cannot bypass totalTimeout budget', async t => {
 	let fetchCallCount = 0;
 
 	const customFetch: typeof fetch = async () => {
@@ -530,7 +530,7 @@ test('beforeRequest hook on initial request cannot bypass total timeout budget',
 	const error = await t.throwsAsync(
 		ky('https://example.com', {
 			fetch: customFetch,
-			timeout: 100,
+			totalTimeout: 100,
 			hooks: {
 				beforeRequest: [
 					async () => {
@@ -839,7 +839,7 @@ test('beforeRetry hook can cancel retries by returning `stop`', async t => {
 	t.is(requestCount, 1);
 });
 
-test('beforeRetry hook respects total timeout budget', async t => {
+test('beforeRetry hook respects totalTimeout budget', async t => {
 	let fetchCallCount = 0;
 	let beforeRetryCallCount = 0;
 
@@ -855,7 +855,7 @@ test('beforeRetry hook respects total timeout budget', async t => {
 	await t.throwsAsync(
 		ky('https://example.com', {
 			fetch: customFetch,
-			timeout: 1000,
+			totalTimeout: 1000,
 			retry: {
 				limit: 1,
 				delay: () => 0,
@@ -1534,7 +1534,7 @@ test('beforeError hook receives TimeoutError', async t => {
 	t.true(receivedError instanceof KyError);
 });
 
-test('beforeError receives TimeoutError when beforeRequest consumes remaining timeout budget (gh-508)', async t => {
+test('beforeError receives TimeoutError when beforeRequest consumes remaining totalTimeout budget (gh-508)', async t => {
 	let receivedError: Error | undefined;
 	let fetchCallCount = 0;
 
@@ -1546,7 +1546,7 @@ test('beforeError receives TimeoutError when beforeRequest consumes remaining ti
 	await t.throwsAsync(
 		ky('https://example.com', {
 			fetch: customFetch,
-			timeout: 100,
+			totalTimeout: 100,
 			hooks: {
 				beforeRequest: [
 					async () => {
@@ -1685,9 +1685,8 @@ test('beforeError hook retryCount reflects actual retry count for TimeoutError',
 		},
 	);
 
-	// The 50ms total timeout budget is exhausted before any retry can complete,
-	// so retryCount is 0.
-	t.is(errorRetryCount, 0);
+	// Each retry gets the full per-attempt timeout, so all 2 retries are attempted.
+	t.is(errorRetryCount, 2);
 });
 
 test('beforeError hook can replace error with a different type', async t => {
@@ -2406,7 +2405,7 @@ test('afterResponse hook can force retry with custom delay', async t => {
 	t.true(elapsedTime >= customDelay); // Verify custom delay was used
 });
 
-test('afterResponse forced retry respects total timeout budget', async t => {
+test('afterResponse forced retry respects totalTimeout budget', async t => {
 	let requestCount = 0;
 
 	const server = await createHttpTestServer(t);
@@ -2417,7 +2416,7 @@ test('afterResponse forced retry respects total timeout budget', async t => {
 
 	await t.throwsAsync(
 		ky.get(server.url, {
-			timeout: 100,
+			totalTimeout: 100,
 			retry: {
 				limit: 3,
 			},
@@ -2437,7 +2436,7 @@ test('afterResponse forced retry respects total timeout budget', async t => {
 		},
 	);
 
-	t.true(requestCount <= 1);
+	t.is(requestCount, 1);
 });
 
 test('afterResponse hook forced retry respects retry limit', async t => {