feat: Add beforeTimeout hook by constantly-dev · Pull Request #804 · sindresorhus/ky

constantly-dev · 2025-12-18T09:29:56Z

Closes #508

Description

This PR introduces a new hook, beforeTimeout, which allows users to intercept and handle TimeoutErrors globally.

Currently, the beforeError hook only receives HTTPError, forcing users to wrap every request in a try-catch block to handle timeouts (e.g., for logging or UI notifications). This PR solves that inconvenience.

Implementation Details

Based on the discussion in #508, I have implemented the following:

Naming: Named the hook beforeTimeout as suggested by @sindresorhus.
Behavior: The hook receives the TimeoutError, allowing modification (e.g., changing the error message).
Control Flow: Crucially, the error is re-thrown after the hooks are executed. It does not silence the error, preserving Ky's promise rejection behavior.
Types: Added BeforeTimeoutHook type definition and updated Hooks interface.
Tests: Added comprehensive tests to ensure the hook is triggered and can modify the error object.

Example Usage

import ky from 'ky';

await ky('[https://example.com](https://example.com)', {
	timeout: 100,
	hooks: {
		beforeTimeout: [
			error => {
				// Log the timeout globally
				console.error('Request timed out:', error);

				// Or modify the error before it propagates
				error.message = 'Custom timeout message';

				return error;
			}
		]
	}
});

samicey · 2025-12-22T20:56:30Z

source/core/Ky.ts

+					for (const hook of ky.#options.hooks.beforeTimeout) {
+						// eslint-disable-next-line no-await-in-loop
+						timeoutError = await hook(timeoutError);
+					}


quick observation. This suggests that timeoutError is continuously overwritten by each subsequent hook in beforeTimeout, and as a result, only the error returned by the last beforeTimeout hook will be thrown.

@samicey
Thank you for your response!
Yes, you are correct. It works as a pipeline where the output of one hook becomes the input of the next.

I intentionally implemented it this way to maintain consistency with ky's existing beforeError hook logic.
If you check the beforeError implementation in Ky.ts, it uses the exact same pattern:

// Existing beforeError logic in Ky.ts for (const hook of ky.#options.hooks.beforeError) { error = await hook(error, {retryCount: ky.#retryCount}); }

I believe applying the same pattern to beforeTimeout is the most consistent approach for this library.

Do you think there is a better approach for this?

sholladay · 2025-12-23T18:04:53Z

I think I would mildly prefer to send TimeoutError through beforeError rather than a new beforeTimeout hook (or do both). It enables simpler handling of multiple error types.

sholladay · 2025-12-23T18:25:36Z

source/core/Ky.ts

+						timeoutError = await hook(timeoutError);
+					}
+
+					throw timeoutError;


This can throw undefined pretty easily, if the hook just doesn't return anything, which is bad. Looks like beforeError already has this problem, too.

I think we should check the hook result and overwrite error if the result is an error (of any kind)..

Regarding the potential undefined issue, I plan to fix it by verifying the hook's return value before assigning it. Here is the implementation:

for (const hook of ky.#options.hooks.beforeTimeout) { // eslint-disable-next-line no-await-in-loop const result = await hook(timeoutError); // Only overwrite if the hook returns a valid Error instance if (result instanceof Error) { timeoutError = result; } }

Does this look good to you?

Yes, exactly. 👍

@sholladay
Thanks! I see that #829 resolves the main feature request.
Would you be okay with me opening a small follow-up PR to add a defensive guard so we only overwrite the error when the hook returns a valid Error instance? For example:

// change to beforeError (new) for (const hook of ky.#options.hooks.beforeError) { // eslint-disable-next-line no-await-in-loop const result = await hook(error); if (result instanceof Error) { error = result; } }

@sholladay
Thanks — I took the suggestion and opened a small follow-up PR with the defensive guard: #833. Feedback welcome! 😀

constantly-dev · 2025-12-24T03:46:42Z

I think I would mildly prefer to send TimeoutError through beforeError rather than a new beforeTimeout hook (or do both). It enables simpler handling of multiple error types.

@sholladay
In the original issue (#508), suggested naming it beforeTimeout explicitly. I am happy to merge this into beforeError if that is the preferred direction now.

However, beforeError is currently typed to strictly receive HTTPError. If we merge them, we'll need to broaden the type definition (e.g., HTTPError | TimeoutError).

Which direction should I proceed with? I'll update the PR as soon as you guys decide.

sindresorhus · 2025-12-26T15:50:53Z

source/types/hooks.ts

+                    // Or modify the error message
+                    error.message = 'Custom timeout message';
+
+                    return error;


use tab-indentation

sindresorhus · 2025-12-26T15:50:56Z

source/types/hooks.ts

+    ```
+    import ky from 'ky';
+
+    await ky('[https://example.com](https://example.com)', {


sindresorhus · 2025-12-26T15:52:04Z

source/types/hooks.ts


 export type BeforeErrorHook = (error: HTTPError, state: BeforeErrorState) => HTTPError | Promise<HTTPError>;

+export type BeforeTimeoutHook = (error: TimeoutError) => TimeoutError | Promise<TimeoutError>;


Must be exported from index.d.ts too.

sindresorhus · 2025-12-26T15:52:41Z

source/core/Ky.ts

+
+					for (const hook of ky.#options.hooks.beforeTimeout) {
+						// eslint-disable-next-line no-await-in-loop
+						timeoutError = await hook(timeoutError);


Suggested change

timeoutError = await hook(timeoutError);

timeoutError = await hook({error: timeoutError});

should be an options-object in case we need to add more parameters in the future.

sindresorhus · 2025-12-26T16:15:14Z

I think it should be in beforeError, but it's a breaking change, so cannot happen yet. You can do the PR, but we cannot merge until we start work on v2, which is not going to happen yet.

sholladay · 2025-12-26T17:44:19Z

In the original issue (#508), suggested naming it beforeTimeout explicitly. I am happy to merge this into beforeError if that is the preferred direction now.

@constantly-dev if you look closely, you'll notice that I edited the issue title to specify beforeError after the initial discussion where Sindre and I both seemed a bit skeptical of the need for a separate hook. But you're right, I didn't add a note to the top of the thread. I tend to avoid editing people's posts unless it's really necessary. Sorry for the confusion.

Let's proceed with beforeError.

sholladay · 2026-03-02T10:08:42Z

Closing since I believe #829 made this PR obsolete. Feel free to let me know if I missed anything.

feat: Add hook

e431476

samicey reviewed Dec 22, 2025

View reviewed changes

sholladay reviewed Dec 23, 2025

View reviewed changes

sindresorhus requested changes Dec 26, 2025

View reviewed changes

constantly-dev mentioned this pull request Mar 2, 2026

Ignore non-Errors returned by beforeError hooks #833

Merged

sholladay closed this Mar 2, 2026


		export type BeforeErrorHook = (error: HTTPError, state: BeforeErrorState) => HTTPError \| Promise<HTTPError>;

		export type BeforeTimeoutHook = (error: TimeoutError) => TimeoutError \| Promise<TimeoutError>;

	timeoutError = await hook(timeoutError);
	timeoutError = await hook({error: timeoutError});

Uh oh!

Conversation

constantly-dev commented Dec 18, 2025

Description

Implementation Details

Example Usage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

constantly-dev Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sholladay commented Dec 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

constantly-dev Dec 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

constantly-dev Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

constantly-dev commented Dec 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sindresorhus commented Dec 26, 2025

Uh oh!

sholladay commented Dec 26, 2025

Uh oh!

sholladay commented Mar 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

constantly-dev Dec 23, 2025 •

edited

Loading

constantly-dev Dec 24, 2025 •

edited

Loading

constantly-dev Mar 2, 2026 •

edited

Loading