lib: initial experimental AbortController implementation

.eslintrc.js

@@ -280,6 +280,7 @@ module.exports ={
  'node-core/no-duplicate-requires': 'error',
  },
  globals:{
+ AbortController: 'readable',
  Atomics: 'readable',
  BigInt: 'readable',
  BigInt64Array: 'readable',

doc/api/cli.md

@@ -167,6 +167,18 @@ Enable experimental Source Map V3 support for stack traces.
 Currently, overriding `Error.prepareStackTrace` is ignored when the
 `--enable-source-maps` flag is set.
 
+### `--experimental-abortcontroller`
+<!-- YAML
+added: REPLACEME
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/33527
+ description: --experimental-abortcontroller is no longer required.
+-->
+
+Experimental `AbortController` and `AbortSignal` support is enabled by default.
+Use of this command line flag is no longer required.
+
 ### `--experimental-import-meta-resolve`
 <!-- YAML
 added:
@@ -1209,6 +1221,7 @@ Node.js options that are allowed are:
 * `--disable-proto`
 * `--enable-fips`
 * `--enable-source-maps`
+* `--experimental-abortcontroller`
 * `--experimental-import-meta-resolve`
 * `--experimental-json-modules`
 * `--experimental-loader`

doc/api/globals.md

@@ -17,6 +17,99 @@ 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`][].
+
+```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 +319,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

lib/internal/abort_controller.js

@@ -0,0 +1,83 @@
+'use strict'
+
+// Modeled very closely on the AbortController implementation
+// in https://github.com/mysticatea/abort-controller (MIT license)
+
+const{
+ Object,
+ Symbol,
+} = primordials;
+
+const{
+ EventTarget,
+ Event
+} = require('internal/event_target');
+const{
+ customInspectSymbol,
+ emitExperimentalWarning
+} = require('internal/util');
+const{inspect } = require('internal/util/inspect');
+
+const kAborted = Symbol('kAborted');
+
+function customInspect(self, obj, depth, options){
+ if (depth < 0)
+ return self;
+
+ const opts = Object.assign({}, options,{
+ depth: options.depth === null ? null : options.depth - 1
+ });
+
+ return `${self.constructor.name} ${inspect(obj, opts)}`;
+}
+
+class AbortSignal extends EventTarget{
+ get aborted(){return !!this[kAborted]}
+
+ [customInspectSymbol](depth, options){
+ return customInspect(this,{
+ aborted: this.aborted
+ }, depth, options);
+ }
+}
+
+Object.defineProperties(AbortSignal.prototype,{
+ aborted:{enumerable: true }
+});
+
+function abortSignal(signal){
+ if (signal[kAborted]) return;
+ signal[kAborted] = true;
+ const event = new Event('abort');
+ if (typeof signal.onabort === 'function'){
+ signal.onabort(event);
+ }
+ signal.dispatchEvent(event);
+}
+
+class AbortController{
+ #signal = new AbortSignal();
+
+ constructor(){
+ emitExperimentalWarning('AbortController');
+ }
+
+ get signal(){return this.#signal}
+ abort(){abortSignal(this.#signal)}
+
+ [customInspectSymbol](depth, options){
+ return customInspect(this,{
+ signal: this.signal
+ }, depth, options);
+ }
+}
+
+Object.defineProperties(AbortController.prototype,{
+ signal:{enumerable: true },
+ abort:{enumerable: true }
+});
+
+module.exports ={
+ AbortController,
+ AbortSignal,
+};

lib/internal/bootstrap/node.js

@@ -133,6 +133,13 @@ if (!config.noBrowserGlobals){
  // https://encoding.spec.whatwg.org/#textdecoder
  exposeInterface(global, 'TextDecoder', TextDecoder);
 
+ const{
+ AbortController,
+ AbortSignal,
+ } = require('internal/abort_controller');
+ exposeInterface(global, 'AbortController', AbortController);
+ exposeInterface(global, 'AbortSignal', AbortSignal);
+
  // https://html.spec.whatwg.org/multipage/webappapis.html#windoworworkerglobalscope
  const timers = require('timers');
  defineOperation(global, 'clearInterval', timers.clearInterval);

node.gyp

@@ -95,6 +95,7 @@
  'lib/wasi.js',
  'lib/worker_threads.js',
  'lib/zlib.js',
+ 'lib/internal/abort_controller.js',
  'lib/internal/assert.js',
  'lib/internal/assert/assertion_error.js',
  'lib/internal/assert/calltracker.js',

src/node_options.cc

@@ -275,6 +275,8 @@ EnvironmentOptionsParser::EnvironmentOptionsParser(){
  "experimental Source Map V3 support",
  &EnvironmentOptions::enable_source_maps,
  kAllowedInEnvironment);
+ AddOption("--experimental-abortcontroller", "",
+ NoOp{}, kAllowedInEnvironment);
  AddOption("--experimental-json-modules",
  "experimental JSON interop support for the ES Module loader",
  &EnvironmentOptions::experimental_json_modules,

test/common/index.js

@@ -256,6 +256,7 @@ function platformTimeout(ms){
 }
 
 let knownGlobals = [
+ AbortController,
  clearImmediate,
  clearInterval,
  clearTimeout,

test/parallel/test-abortcontroller.js

@@ -0,0 +1,22 @@
+// Flags: --no-warnings
+'use strict'
+
+const common = require('../common');
+
+const{ok, strictEqual } = require('assert');
+
+{
+ const ac = new AbortController();
+ ok(ac.signal);
+ ac.signal.onabort = common.mustCall((event) =>{
+ ok(event);
+ strictEqual(event.type, 'abort');
+ });
+ ac.signal.addEventListener('abort', common.mustCall((event) =>{
+ ok(event);
+ strictEqual(event.type, 'abort');
+ }),{once: true });
+ ac.abort();
+ ac.abort();
+ ok(ac.signal.aborted);
+}

test/parallel/test-bootstrap-modules.js

@@ -20,6 +20,7 @@ const expectedModules = new Set([
  'Internal Binding module_wrap',
  'Internal Binding native_module',
  'Internal Binding options',
+ 'Internal Binding performance',
  'Internal Binding process_methods',
  'Internal Binding report',
  'Internal Binding string_decoder',
@@ -30,9 +31,11 @@ const expectedModules = new Set([
  'Internal Binding types',
  'Internal Binding url',
  'Internal Binding util',
+ 'NativeModule async_hooks',
  'NativeModule buffer',
  'NativeModule events',
  'NativeModule fs',
+ 'NativeModule internal/abort_controller',
  'NativeModule internal/assert',
  'NativeModule internal/async_hooks',
  'NativeModule internal/bootstrap/pre_execution',
@@ -42,9 +45,11 @@ const expectedModules = new Set([
  'NativeModule internal/constants',
  'NativeModule internal/encoding',
  'NativeModule internal/errors',
+ 'NativeModule internal/event_target',
  'NativeModule internal/fixed_queue',
  'NativeModule internal/fs/dir',
  'NativeModule internal/fs/utils',
+ 'NativeModule internal/histogram',
  'NativeModule internal/idna',
  'NativeModule internal/linkedlist',
  'NativeModule internal/modules/run_main',
@@ -81,8 +86,10 @@ const expectedModules = new Set([
  'NativeModule internal/validators',
  'NativeModule internal/vm/module',
  'NativeModule path',
+ 'NativeModule perf_hooks',
  'NativeModule timers',
  'NativeModule url',
+ 'NativeModule util',
  'NativeModule vm',
 ]);
 

tools/doc/type-parser.js

@@ -26,6 +26,10 @@ const customTypesMap ={
 
  'this': `${jsDocPrefix}Reference/Operators/this`,
 
+ 'AbortController': 'globals.html#globals_class_abortcontroller',
+ 'AbortSignal':
+ 'globals.html#globals_class_abortsignal_extends_eventtarget',
+
  'ArrayBufferView':
  'https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView',