cli: Add --max-heap-size option

Author: tannal

doc/api/cli.md

@@ -3454,6 +3454,7 @@ V8 options that are allowed are:
 * `--expose-gc`
 * `--interpreted-frames-native-stack`
 * `--jitless`
+* `--max-heap-size`
 * `--max-old-space-size`
 * `--max-semi-space-size`
 * `--perf-basic-prof-only-functions`
@@ -3796,6 +3797,10 @@ documented here:
 
 ### `--jitless`
 
+### `--max-heap-size`
+
+Specifies the maximum heap size (in megabytes) for the process. This option is typically used to limit the amount of memory the process can use for its JavaScript heap, helping to prevent excessive memory usage or out-of-memory errors.
+
 <!-- Anchor to make sure old links find a target -->
 
 <a id="--max-old-space-sizesize-in-megabytes"></a>

src/node_options.cc

@@ -1070,6 +1070,7 @@ PerIsolateOptionsParser::PerIsolateOptionsParser(
             "help system profilers to translate JavaScript interpreted frames",
             V8Option{},
             kAllowedInEnvvar);
+  AddOption("--max-heap-size", "", V8Option{}, kAllowedInEnvvar);
   AddOption("--max-old-space-size", "", V8Option{}, kAllowedInEnvvar);
   AddOption("--max-semi-space-size", "", V8Option{}, kAllowedInEnvvar);
   AddOption("--perf-basic-prof", "", V8Option{}, kAllowedInEnvvar);

test/common/v8-max-heap-size-option.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const tmpdir = require('./tmpdir');
+
+const testScript = `
+  const v8 = require('v8');
+  const stats = v8.getHeapStatistics();
+  const maxHeapSizeMB = Math.round(stats.heap_size_limit / 1024 / 1024);
+  console.log(maxHeapSizeMB);
+`;
+
+tmpdir.refresh();
+const scriptPath = path.join(tmpdir.path, 'heap-limit-test.js');
+fs.writeFileSync(scriptPath, testScript);
+
+const child = spawnSync(
+  process.execPath,
+  [scriptPath],
+  {
+    encoding: 'utf8',
+    env: {
+      ...process.env,
+      NODE_OPTIONS: '--max-heap-size=750',
+    },
+  },
+);
+
+assert.strictEqual(
+  child.status,
+  0,
+  [
+    `Child process did not exit cleanly.`,
+    `  Exit code: ${child.status}`,
+    child.stderr ? `  Stderr: ${child.stderr.toString()}` : '',
+    child.stdout ? `  Stdout: ${child.stdout.toString()}` : '',
+  ].filter(Boolean).join('\n'),
+);
+const output = child.stdout.trim();
+const heapLimit = Number(output);
+
+assert.strictEqual(
+  heapLimit,
+  750,
+  `max heap size is ${heapLimit}MB, expected 750MB`,
+);