Allow custom Error classes in beforeError hook

Fixes #1353

Author: sindresorhus

documentation/9-hooks.md

@@ -403,16 +403,22 @@ const instance = got.extend({
 **Default: `[]`**
 
 ```ts
-(error: RequestError) => Promisable<RequestError>
+(error: RequestError) => Promisable<Error>
 ```
 
 Called with a [`RequestError`](8-errors.md#requesterror) instance. The error is passed to the hook right before it's thrown.
 
-This is especially useful when you want to have more detailed errors.
+This hook can return any `Error` instance, allowing you to:
+- Return custom error classes for better error handling in your application
+- Extend `RequestError` with additional properties
+- Return plain `Error` instances when you don't need Got-specific error information
+
+This is especially useful when you want to have more detailed errors or maintain backward compatibility with existing error handling code.
 
 ```js
 import got from 'got';
 
+// Modify and return the error
 await got('https://api.github.com/repos/sindresorhus/got/commits', {
 	responseType: 'json',
 	hooks: {
@@ -429,4 +435,27 @@ await got('https://api.github.com/repos/sindresorhus/got/commits', {
 		]
 	}
 });
+
+// Return a custom error class
+class CustomAPIError extends Error {
+	constructor(message, statusCode) {
+		super(message);
+		this.name = 'CustomAPIError';
+		this.statusCode = statusCode;
+	}
+}
+
+await got('https://api.example.com/endpoint', {
+	hooks: {
+		beforeError: [
+			error => {
+				// Return a custom error for backward compatibility with your application
+				return new CustomAPIError(
+					error.message,
+					error.response?.statusCode
+				);
+			}
+		]
+	}
+});
 ```

source/core/index.ts

@@ -136,6 +136,9 @@ const cacheableStore = new WeakableMap<string | StorageAdapter, CacheableRequest
 
 const redirectCodes: ReadonlySet<number> = new Set([300, 301, 302, 303, 304, 307, 308]);
 
+// Track errors that have been processed by beforeError hooks to preserve custom error types
+const errorsProcessedByHooks = new WeakSet<Error>();
+
 const proxiedRequestEvents = [
 	'socket',
 	'connect',
@@ -631,8 +634,16 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 			}
 		}
 
-		if (error !== null && !is.undefined(error) && !(error instanceof RequestError)) {
-			error = new RequestError(error.message, error, this);
+		// Preserve custom errors returned by beforeError hooks.
+		// For other errors, wrap non-RequestError instances for consistency.
+		if (error !== null && !is.undefined(error)) {
+			const processedByHooks = error instanceof Error && errorsProcessedByHooks.has(error);
+
+			if (!processedByHooks && !(error instanceof RequestError)) {
+				error = error instanceof Error
+					? new RequestError(error.message, error, this)
+					: new RequestError(String(error), {}, this);
+			}
 		}
 
 		callback(error);
@@ -1496,9 +1507,24 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 				// Skip calling the hooks on purpose.
 				// See https://github.com/sindresorhus/got/issues/2103
 			} else if (this.options) {
-				for (const hook of this.options.hooks.beforeError) {
-					// eslint-disable-next-line no-await-in-loop
-					error = await hook(error);
+				const hooks = this.options.hooks.beforeError;
+				if (hooks.length > 0) {
+					for (const hook of hooks) {
+						// eslint-disable-next-line no-await-in-loop
+						error = await hook(error) as RequestError;
+
+						// Validate hook return value
+						if (!(error instanceof Error)) {
+							throw new TypeError(`The \`beforeError\` hook must return an Error instance. Received ${is.string(error) ? 'string' : String(typeof error)}.`);
+						}
+					}
+
+					// Mark this error as processed by hooks so _destroy preserves custom error types.
+					// Only mark non-RequestError errors, since RequestErrors are already preserved
+					// by the instanceof check in _destroy (line 642).
+					if (!(error instanceof RequestError)) {
+						errorsProcessedByHooks.add(error);
+					}
 				}
 			}
 		} catch (error_: any) {

source/core/options.ts

@@ -103,7 +103,7 @@ export type BeforeRequestHookContext = {
 
 export type BeforeRequestHook = (options: NormalizedOptions, context: BeforeRequestHookContext) => Promisable<void | Response | ResponseLike>;
 export type BeforeRedirectHook = (updatedOptions: NormalizedOptions, plainResponse: PlainResponse) => Promisable<void>;
-export type BeforeErrorHook = (error: RequestError) => Promisable<RequestError>;
+export type BeforeErrorHook = (error: RequestError) => Promisable<Error>;
 export type BeforeRetryHook = (error: RequestError, retryCount: number) => Promisable<void>;
 export type BeforeCacheHook = (response: PlainResponse) => false | void;
 export type AfterResponseHook<ResponseType = unknown> = (response: Response<ResponseType>, retryWithMergedOptions: (options: OptionsInit) => never) => Promisable<Response | CancelableRequest<Response>>;
@@ -296,13 +296,20 @@ export type Hooks = {
 	/**
 	Called with a `RequestError` instance. The error is passed to the hook right before it's thrown.
 
-	This is especially useful when you want to have more detailed errors.
+	This hook can return any `Error` instance, allowing you to:
+	- Return custom error classes for better error handling in your application
+	- Extend `RequestError` with additional properties
+	- Return plain `Error` instances when you don't need Got-specific error information
+
+	This is especially useful when you want to have more detailed errors or maintain backward compatibility with existing error handling code.
 
 	@default []
 
+	@example
 	```
 	import got from 'got';
 
+	// Modify and return the error
 	await got('https://api.github.com/repos/sindresorhus/got/commits', {
 		responseType: 'json',
 		hooks: {
@@ -319,6 +326,29 @@ export type Hooks = {
 			]
 		}
 	});
+
+	// Return a custom error class
+	class CustomAPIError extends Error {
+		constructor(message, statusCode) {
+			super(message);
+			this.name = 'CustomAPIError';
+			this.statusCode = statusCode;
+		}
+	}
+
+	await got('https://api.example.com/endpoint', {
+		hooks: {
+			beforeError: [
+				error => {
+					// Return a custom error for backward compatibility with your application
+					return new CustomAPIError(
+						error.message,
+						error.response?.statusCode
+					);
+				}
+			]
+		}
+	});
 	```
 	*/
 	beforeError: BeforeErrorHook[];

test/hooks.ts

@@ -2226,3 +2226,60 @@ test('multiple handlers with error transformation work with .json()', withServer
 	// Should get error from first handler (outermost)
 	await t.throwsAsync(instance('').json(), {message: /Handler 1: Handler 2:/});
 });
+
+test('beforeError can return custom Error class', async t => {
+	class CustomError extends Error {
+		constructor(message: string) {
+			super(message);
+			this.name = 'CustomError';
+		}
+	}
+
+	const customMessage = 'This is a custom error';
+
+	const error = await t.throwsAsync(
+		got('https://example.com', {
+			request() {
+				throw new Error('Original error');
+			},
+			hooks: {
+				beforeError: [
+					() => new CustomError(customMessage),
+				],
+			},
+		}),
+	);
+
+	t.is(error?.name, 'CustomError');
+	t.is(error?.message, customMessage);
+	t.true(error instanceof CustomError);
+});
+
+test('beforeError can extend RequestError with custom error', async t => {
+	class MyCustomError extends RequestError {
+		constructor(message: string, error: Error, request: any) {
+			super(message, error, request);
+			this.name = 'MyCustomError';
+		}
+	}
+
+	const customMessage = 'Custom RequestError';
+
+	const error = await t.throwsAsync(
+		got('https://example.com', {
+			request() {
+				throw new Error('Original error');
+			},
+			hooks: {
+				beforeError: [
+					error => new MyCustomError(customMessage, error, error.request),
+				],
+			},
+		}),
+	);
+
+	t.is(error?.name, 'MyCustomError');
+	t.is(error?.message, customMessage);
+	t.true(error instanceof MyCustomError);
+	t.true(error instanceof RequestError);
+});