Support AbortController (#2020)

jopemachine · szmarczak · sindresorhus · web-flow · commit 6a6d2a93d955 · 2022-07-24T17:18:18.000+02:00
Co-authored-by: Szymon Marczak &lt;36894700+szmarczak@users.noreply.github.com&gt;
Co-authored-by: Sindre Sorhus &lt;sindresorhus@gmail.com&gt;
diff --git a/documentation/2-options.md b/documentation/2-options.md
@@ -209,6 +209,28 @@ await got('https://httpbin.org/anything');
 #### **Note:**
 > - If you're passing an absolute URL as `url`, you need to set `prefixUrl` to an empty string.
 
+### `signal`
+
+**Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)**
+
+You can abort the `request` using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+
+*Requires Node.js 16 or later.*
+
+```js
+import got from 'got';
+
+const abortController = new AbortController();
+
+const request = got('https://httpbin.org/anything', {
+	signal: abortController.signal
+});
+
+setTimeout(() => {
+	abortController.abort();
+}, 100);
+```
+
 ### `method`
 
 **Type: `string`**\
diff --git a/documentation/8-errors.md b/documentation/8-errors.md
@@ -97,3 +97,9 @@ When the request is aborted with `promise.cancel()`.
 **Code: `ERR_RETRYING`**
 
 Always triggers a new retry when thrown.
+
+### `AbortError`
+
+**Code: `ERR_ABORTED`**
+
+When the request is aborted with [AbortController.abort()](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort).
diff --git a/source/core/errors.ts b/source/core/errors.ts
@@ -170,3 +170,14 @@ export class RetryError extends RequestError {
 		this.code = 'ERR_RETRYING';
 	}
 }
+
+/**
+An error to be thrown when the request is aborted by AbortController.
+*/
+export class AbortError extends RequestError {
+	constructor(request: Request) {
+		super('This operation was aborted.', {}, request);
+		this.code = 'ERR_ABORTED';
+		this.name = 'AbortError';
+	}
+}
diff --git a/source/core/index.ts b/source/core/index.ts
@@ -32,6 +32,7 @@ import {
 	TimeoutError,
 	UploadError,
 	CacheError,
+	AbortError,
 } from './errors.js';
 import type {PlainResponse} from './response.js';
 import type {PromiseCookieJar, NativeRequestOptions, RetryOptions} from './options.js';
@@ -241,6 +242,14 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 			return;
 		}
 
+		if (this.options.signal?.aborted) {
+			this.destroy(new AbortError(this));
+		}
+
+		this.options.signal?.addEventListener('abort', () => {
+			this.destroy(new AbortError(this));
+		});
+
 		// Important! If you replace `body` in a handler with another stream, make sure it's readable first.
 		// The below is run only once.
 		const {body} = this.options;
diff --git a/source/core/options.ts b/source/core/options.ts
@@ -827,6 +827,7 @@ const defaultInternals: Options['_internals'] = {
 	},
 	setHost: true,
 	maxHeaderSize: undefined,
+	signal: undefined,
 	enableUnixSockets: true,
 };
 
@@ -1489,6 +1490,38 @@ export default class Options {
 		}
 	}
 
+	/**
+	You can abort the `request` using [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+
+	*Requires Node.js 16 or later.*
+
+	@example
+	```
+	import got from 'got';
+
+	const abortController = new AbortController();
+
+	const request = got('https://httpbin.org/anything', {
+		signal: abortController.signal
+	});
+
+	setTimeout(() => {
+		abortController.abort();
+	}, 100);
+	```
+	*/
+	// TODO: Replace `any` with `AbortSignal` when targeting Node 16.
+	get signal(): any | undefined {
+		return this._internals.signal;
+	}
+
+	// TODO: Replace `any` with `AbortSignal` when targeting Node 16.
+	set signal(value: any | undefined) {
+		assert.object(value);
+
+		this._internals.signal = value;
+	}
+
 	/**
 	Ignore invalid cookies instead of throwing an error.
 	Only useful when the `cookieJar` option has been set. Not recommended.
@@ -2488,5 +2521,6 @@ export default class Options {
 		Object.freeze(options.retry.methods);
 		Object.freeze(options.retry.statusCodes);
 		Object.freeze(options.context);
+		Object.freeze(options.signal);
 	}
 }
diff --git a/test/abort.ts b/test/abort.ts
