lib: initial experimental AbortController implementation

AbortController impl based very closely on:
 https://github.com/mysticatea/abort-controller

Marked experimental.
Not currently used by any of the existing promise apis.

Signed-off-by: James M Snell <jasnell@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/33527
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 96 insertions, 0 deletions

diff --git a/doc/api/globals.md b/doc/api/globals.md
index 7e6129e9038..78550035cbc 100644
--- a/doc/api/globals.md
+++ b/doc/api/globals.md
@@ -17,6 +17,101 @@ The objects listed here are specific to Node.js. There are [built-in objects][]
 that are part of the JavaScript language itself, which are also globally
 accessible.
 
+## Class: `AbortController`
+<!--YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+<!-- type=global -->
+
+A utility class used to signal cancelation in selected `Promise`-based APIs.
+The API is based on the Web API [`AbortController`][].
+
+To use, launch Node.js using the `--experimental-abortcontroller` flag.
+
+```js
+const ac = new AbortController();
+
+ac.signal.addEventListener('abort', () => console.log('Aborted!'),
+                           { once: true });
+
+ac.abort();
+
+console.log(ac.signal.aborted);  // Prints True
+```
+
+### `abortController.abort()`
+<!-- YAML
+added: REPLACEME
+-->
+
+Triggers the abort signal, causing the `abortController.signal` to emit
+the `'abort'` event.
+
+### `abortController.signal`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {AbortSignal}
+
+### Class: `AbortSignal extends EventTarget`
+<!-- YAML
+added: REPLACEME
+-->
+
+The `AbortSignal` is used to notify observers when the
+`abortController.abort()` method is called.
+
+#### Event: `'abort'`
+<!-- YAML
+added: REPLACEME
+-->
+
+The `'abort'` event is emitted when the `abortController.abort()` method
+is called. The callback is invoked with a single object argument with a
+single `type` propety set to `'abort'`:
+
+```js
+const ac = new AbortController();
+
+// Use either the onabort property...
+ac.signal.onabort = () => console.log('aborted!');
+
+// Or the EventTarget API...
+ac.signal.addEventListener('abort', (event) => {
+  console.log(event.type);  // Prints 'abort'
+}, { once: true });
+
+ac.abort();
+```
+
+The `AbortController` with which the `AbortSignal` is associated will only
+ever trigger the `'abort'` event once. Any event listeners attached to the
+`AbortSignal` *should* use the `{ once: true }` option (or, if using the
+`EventEmitter` APIs to attach a listener, use the `once()` method) to ensure
+that the event listener is removed as soon as the `'abort'` event is handled.
+Failure to do so may result in memory leaks.
+
+#### `abortSignal.aborted`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {boolean} True after the `AbortController` has been aborted.
+
+#### `abortSignal.onabort`
+<!-- YAML
+added: REPLACEME
+-->
+
+* Type: {Function}
+
+An optional callback function that may be set by user code to be notified
+when the `abortController.abort()` function has been called.
+
 ## Class: `Buffer`
 <!-- YAML
 added: v0.1.103
@@ -226,6 +321,7 @@ The object that acts as the namespace for all W3C
 [WebAssembly][webassembly-org] related functionality. See the
 [Mozilla Developer Network][webassembly-mdn] for usage and compatibility.
 
+[`AbortController`]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController
 [`TextDecoder`]: util.html#util_class_util_textdecoder
 [`TextEncoder`]: util.html#util_class_util_textencoder
 [`URLSearchParams`]: url.html#url_class_urlsearchparams