From c27bdefc858c08ee575674b6e6a45d53f651957c Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 8 Sep 2026 21:04:38 +0000 Subject: [PATCH] lib: put node:bench behind an --experimental-bench flag Signed-off-by: James M Snell Assisted-by: Opencode --- benchmark/_node-bench.js | 1 + doc/api/bench.md | 11 +- doc/api/cli.md | 18 ++- doc/node-config-schema.json | 107 ++++++++++++++++++ doc/node.1 | 11 +- lib/internal/bench_runner/cli.js | 9 +- lib/internal/bootstrap/realm.js | 2 + lib/internal/process/pre_execution.js | 11 ++ src/node_builtins.cc | 20 ++-- src/node_options.cc | 17 +++ src/node_options.h | 2 + test/fixtures/bench-runner/node.config.json | 3 + .../test-module-hooks-builtin-require.js | 1 + .../test-module-hooks-load-builtin-require.js | 1 + test/parallel/test-bench-auto-run.js | 3 +- test/parallel/test-bench-cli-arguments.js | 4 +- test/parallel/test-bench-cli-backpressure.js | 4 +- test/parallel/test-bench-cli-lifecycle.js | 4 +- test/parallel/test-bench-cli-reporters.js | 4 +- test/parallel/test-bench-cli.js | 19 +++- test/parallel/test-bench-clock-precision.js | 2 +- test/parallel/test-bench-context-control.js | 2 +- test/parallel/test-bench-context-errors.js | 2 +- test/parallel/test-bench-create-runner.js | 2 +- test/parallel/test-bench-custom-reporter.js | 2 +- .../test-bench-diagnostic-channels.js | 2 +- test/parallel/test-bench-diagnostics.js | 2 +- test/parallel/test-bench-errors.js | 2 +- test/parallel/test-bench-filtering.js | 2 +- test/parallel/test-bench-harness-errors.js | 2 +- test/parallel/test-bench-hook-errors.js | 2 +- test/parallel/test-bench-module.mjs | 2 +- test/parallel/test-bench-reporters.js | 2 +- test/parallel/test-bench-run-file.js | 5 +- test/parallel/test-bench-run-options.js | 2 +- test/parallel/test-bench-run.js | 2 +- test/parallel/test-bench-stream.js | 2 +- test/parallel/test-bench-validation.js | 2 +- .../test-bench-yield-between-samples.js | 2 +- .../test-module-builtin-experimental.js | 2 + test/parallel/test-module-isBuiltin.js | 6 +- 41 files changed, 252 insertions(+), 49 deletions(-) diff --git a/benchmark/_node-bench.js b/benchmark/_node-bench.js index 6c8d1acffdfa..ecf383e3bc30 100644 --- a/benchmark/_node-bench.js +++ b/benchmark/_node-bench.js @@ -53,6 +53,7 @@ function runBenchmark(binary, file, options) { const args = [ ...options.nodeArgs, '--no-warnings', + '--experimental-bench', '--bench', '--bench-reporter=json', '--bench-samples=1', diff --git a/doc/api/bench.md b/doc/api/bench.md index b25503830f2c..2f936caf2c72 100644 --- a/doc/api/bench.md +++ b/doc/api/bench.md @@ -12,7 +12,8 @@ added: REPLACEME The `node:bench` module supports defining and running JavaScript benchmarks in the current process, and running one benchmark file in a fresh child process. -To access it: +The module is only available when Node.js is started with the +`--experimental-bench` flag and can only be imported with the `node:` scheme: ```mjs import { bench, suite } from 'node:bench'; @@ -22,8 +23,6 @@ import { bench, suite } from 'node:bench'; const { bench, suite } = require('node:bench'); ``` -This module is only available under the `node:` scheme. - ## Example benchmark Save the following as `benchmark.mjs`: @@ -57,7 +56,7 @@ suite('URL', () => { Run the benchmark from the command line: ```console -node --bench benchmark.mjs +node --experimental-bench --bench benchmark.mjs ``` Benchmarks are executed serially in declaration order. Declared benchmarks are @@ -183,8 +182,8 @@ declarations and a second call to `run()` is an error. The `--bench` flag runs one or more explicit benchmark files or glob patterns: ```console -node --bench benchmark.mjs -node --bench --bench-reporter=json 'benchmarks/**/*.js' +node --experimental-bench --bench benchmark.mjs +node --experimental-bench --bench --bench-reporter=json 'benchmarks/**/*.js' ``` Files are sorted and executed serially. The default diff --git a/doc/api/cli.md b/doc/api/cli.md index 41f9d6534f81..3e3f2e4416f6 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -484,10 +484,13 @@ Starts the Node.js command-line benchmark runner. At least one explicit file or glob pattern is required: ```console -node --bench benchmark.mjs -node --bench 'benchmarks/**/*.js' +node --experimental-bench --bench benchmark.mjs +node --experimental-bench --bench 'benchmarks/**/*.js' ``` +The `--experimental-bench` flag is required to use this flag or any other +`--bench-*` option. + Quote glob patterns to prevent expansion by the shell. Matching files are sorted and executed serially. By default, each file runs in a separate child process. Benchmark files declare benchmarks using `node:bench`; they must not @@ -1217,6 +1220,16 @@ changes: Enable experimental import support for `.node` addons. +### `--experimental-bench` + + + +> Stability: 1 - Experimental + +Enable the experimental `node:bench` module and command-line benchmark runner. + ### `--experimental-config-file=path`, `--experimental-config-file`