stream: gate stream/iter behind --experimental-stream-iter

Add the `--experimental-stream-iter`` CLI flag to gate access to the
`node:stream/iter` module. When the flag is not specified, attempting
to import the module will throw `ERR_UNKNOWN_BUILTIN_MODULE`.
The module is added to the `experimentalModuleList` in `realm.js` and
to the `cannot_be_required` set in `node_builtins.cc`. A setup function
in `pre_execution.js` enables access at runtime when the flag is
present. An experimental warning is emitted on first load.
The module is accessible both with and without the node: prefix
when the flag is enabled.

Author: jasnell

benchmark/fs/bench-filehandle-pull-vs-webstream.js

@@ -1,3 +1,4 @@
+// Flags: --experimental-stream-iter
 // Compare FileHandle.createReadStream() vs readableWebStream() vs pull()
 // reading a large file through two transforms: uppercase then gzip compress.
 'use strict';

doc/api/cli.md

@@ -1277,6 +1277,16 @@ added:
 
 Enable experimental support for storage inspection
 
+### `--experimental-stream-iter`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Enable the experimental [`node:stream/iter`][] module.
+
 ### `--experimental-test-coverage`
 
 <!-- YAML
@@ -3612,6 +3622,7 @@ one is included in the list below.
 * `--experimental-require-module`
 * `--experimental-shadow-realm`
 * `--experimental-specifier-resolution`
+* `--experimental-stream-iter`
 * `--experimental-test-isolation`
 * `--experimental-top-level-await`
 * `--experimental-vm-modules`
@@ -4251,6 +4262,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`import` specifier]: esm.md#import-specifiers
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
 [`node:sqlite`]: sqlite.md
+[`node:stream/iter`]: stream_iter.md
 [`process.setUncaughtExceptionCaptureCallback()`]: process.md#processsetuncaughtexceptioncapturecallbackfn
 [`tls.DEFAULT_MAX_VERSION`]: tls.md#tlsdefault_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.md#tlsdefault_min_version

doc/api/stream_iter.md

@@ -1,13 +1,17 @@
-# Stream (new)
+# Iterable Streams
 
 <!--introduced_in=REPLACEME-->
 
 > Stability: 1 - Experimental
 
 <!-- source_link=lib/stream/iter.js -->
 
-The `node:stream/iter` module provides a new streaming API built on iterables
-rather than the event-driven `Readable`/`Writable`/`Transform` class hierarchy.
+The `node:stream/iter` module provides a streaming API built on iterables
+rather than the event-driven `Readable`/`Writable`/`Transform` class hierarchy,
+or the Web Streams `ReadableStream`/`WritableStream`/`TransformStream` interfaces.
+
+This module is available only when the `--experimental-stream-iter` CLI flag
+is enabled.
 
 Streams are represented as `AsyncIterable<Uint8Array[]>` (async) or
 `Iterable<Uint8Array[]>` (sync). There are no base classes to extend -- any

doc/node.1

@@ -720,6 +720,11 @@ top-level awaits, and print their location to help users find them.
 .It Fl -experimental-quic
 Enable experimental support for the QUIC protocol.
 .
+.It Fl -experimental-stream-iter
+Enable the experimental
+.Sy node:stream/iter
+module.
+.
 .It Fl -experimental-sea-config
 Use this flag to generate a blob that can be injected into the Node.js
 binary to produce a single executable application. See the documentation

lib/internal/bootstrap/realm.js

@@ -131,7 +131,7 @@ const schemelessBlockList = new SafeSet([
   'test/reporters',
 ]);
 // Modules that will only be enabled at run time.
-const experimentalModuleList = new SafeSet(['sqlite', 'quic']);
+const experimentalModuleList = new SafeSet(['sqlite', 'quic', 'stream/iter']);
 
 // Set up process.binding() and process._linkedBinding().
 {

lib/internal/process/pre_execution.js

@@ -115,6 +115,7 @@ function prepareExecution(options) {
   setupNavigator();
   setupWarningHandler();
   setupSQLite();
+  setupStreamIter();
   setupQuic();
   setupWebStorage();
   setupWebsocket();
@@ -392,6 +393,15 @@ function initializeConfigFileSupport() {
   }
 }
 
+function setupStreamIter() {
+  if (!getOptionValue('--experimental-stream-iter')) {
+    return;
+  }
+
+  const { BuiltinModule } = require('internal/bootstrap/realm');
+  BuiltinModule.allowRequireByUsers('stream/iter');
+}
+
 function setupQuic() {
   if (!getOptionValue('--experimental-quic')) {
     return;

lib/stream/iter.js

@@ -1,12 +1,16 @@
 'use strict';
 
-// Public entry point for the new streams API.
+// Public entry point for the iterable streams API.
 // Usage: require('stream/iter') or require('node:stream/iter')
+// Requires: --experimental-stream-iter
 
 const {
   ObjectFreeze,
 } = primordials;
 
+const { emitExperimentalWarning } = require('internal/util');
+emitExperimentalWarning('stream/iter');
+
 // Protocol symbols
 const {
   toStreamable,

src/node_builtins.cc

@@ -141,6 +141,7 @@ BuiltinLoader::BuiltinCategories BuiltinLoader::GetBuiltinCategories() const {
 #endif             // !OPENSSL_NO_QUIC
         "quic",    // Experimental.
         "sqlite",  // Experimental.
+        "stream/iter",  // Experimental.
         "sys",     // Deprecated.
         "wasi",    // Experimental.
 #if !HAVE_SQLITE

src/node_options.cc

@@ -599,6 +599,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::experimental_sqlite,
             kAllowedInEnvvar,
             true);
+  AddOption("--experimental-stream-iter",
+            "experimental iterable streams API (node:stream/iter)",
+            &EnvironmentOptions::experimental_stream_iter,
+            kAllowedInEnvvar);
   AddOption("--experimental-quic",
 #ifndef OPENSSL_NO_QUIC
             "experimental QUIC support",

src/node_options.h

@@ -127,6 +127,7 @@ class EnvironmentOptions : public Options {
   bool experimental_fetch = true;
   bool experimental_websocket = true;
   bool experimental_sqlite = true;
+  bool experimental_stream_iter = false;
   bool webstorage = HAVE_SQLITE;
 #ifndef OPENSSL_NO_QUIC
   bool experimental_quic = false;