lib: Symbol.dispose should be enabled with experimental flag

The TC39 explicit resource management proposal is still at stage 3 and
under active development. It must be enabled with an experimental
flag `--experimental-explicit-resource-management`. The flag implies
that the V8 option `--js-explicit-resource-management` to be enabled.

Author: legendecas

doc/api/cli.md

@@ -941,6 +941,14 @@ added: v22.3.0
 
 Enable exposition of [EventSource Web API][] on the global scope.
 
+### `--experimental-explicit-resource-management`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+Use this flag to enable [Explicit Resource Management][] support.
+
 ### `--experimental-import-meta-resolve`
 
 <!-- YAML
@@ -2912,6 +2920,7 @@ one is included in the list below.
 * `--experimental-default-type`
 * `--experimental-detect-module`
 * `--experimental-eventsource`
+* `--experimental-explicit-resource-management`
 * `--experimental-import-meta-resolve`
 * `--experimental-json-modules`
 * `--experimental-loader`
@@ -3435,6 +3444,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [ECMAScript module]: esm.md#modules-ecmascript-modules
 [EventSource Web API]: https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events
 [ExperimentalWarning: `vm.measureMemory` is an experimental feature]: vm.md#vmmeasurememoryoptions
+[Explicit Resource Management]: https://github.com/tc39/proposal-explicit-resource-management
 [File System Permissions]: permissions.md#file-system-permissions
 [Loading ECMAScript modules using `require()`]: modules.md#loading-ecmascript-modules-using-require
 [Module customization hooks]: module.md#customization-hooks

doc/api/test.md

@@ -2276,6 +2276,8 @@ mock.timers.reset();
 
 ### `timers[Symbol.dispose]()`
 
+> Stability: 1 - Experimental
+
 Calls `timers.reset()`.
 
 ### `timers.tick([milliseconds])`

lib/internal/process/pre_execution.js

@@ -160,6 +160,9 @@ function prepareExecution(options) {
 }
 
 function setupSymbolDisposePolyfill() {
+  if (!getOptionValue('--experimental-explicit-resource-management')) {
+    return;
+  }
   // TODO(MoLow): Remove this polyfill once Symbol.dispose and Symbol.asyncDispose are available in V8.
   // eslint-disable-next-line node-core/prefer-primordials
   if (typeof Symbol.dispose !== 'symbol') {

src/node_options.cc

@@ -905,6 +905,19 @@ PerIsolateOptionsParser::PerIsolateOptionsParser(
   Implies("--experimental-shadow-realm", "--harmony-shadow-realm");
   Implies("--harmony-shadow-realm", "--experimental-shadow-realm");
   ImpliesNot("--no-harmony-shadow-realm", "--experimental-shadow-realm");
+
+  AddOption("--experimental-explicit-resource-management",
+            "",
+            &PerIsolateOptions::experimental_explicit_resource_management,
+            kAllowedInEnvvar);
+  AddOption("--js-explicit-resource-management", "", V8Option{});
+  Implies("--experimental-explicit-resource-management",
+          "--js-explicit-resource-management");
+  Implies("--js-explicit-resource-management",
+          "--experimental-explicit-resource-management");
+  ImpliesNot("--no-js-explicit-resource-management",
+             "--experimental-explicit-resource-management");
+
   AddOption("--build-snapshot",
             "Generate a snapshot blob when the process exits.",
             &PerIsolateOptions::build_snapshot,

src/node_options.h

@@ -264,6 +264,7 @@ class PerIsolateOptions : public Options {
   bool report_uncaught_exception = false;
   bool report_on_signal = false;
   bool experimental_shadow_realm = false;
+  bool experimental_explicit_resource_management = false;
   std::string report_signal = "SIGUSR2";
   bool build_snapshot = false;
   std::string build_snapshot_config;

test/parallel/test-child-process-destroy.js

@@ -1,3 +1,5 @@
+// Flags: --experimental-explicit-resource-management
+
 'use strict';
 const common = require('../common');
 const assert = require('assert');

test/parallel/test-events-add-abort-listener.mjs

@@ -1,3 +1,5 @@
+// Flags: --experimental-explicit-resource-management
+
 import * as common from '../common/index.mjs';
 import * as events from 'node:events';
 import * as assert from 'node:assert';

test/parallel/test-runner-mock-timers.js

@@ -1,3 +1,5 @@
+// Flags: --experimental-explicit-resource-management
+
 'use strict';
 process.env.NODE_TEST_KNOWN_GLOBALS = 0;
 const common = require('../common');

test/parallel/test-timers-dispose.js

@@ -1,3 +1,5 @@
+// Flags: --experimental-explicit-resource-management
+
 'use strict';
 const common = require('../common');
 const assert = require('assert');

test/sequential/test-inspector-open-dispose.mjs

@@ -1,3 +1,5 @@
+// Flags: --experimental-explicit-resource-management
+
 import * as common from '../common/index.mjs';
 import assert from 'node:assert';
 import net from 'node:net';