add params as options object

IlyasShabi · IlyasShabi · commit f39064bc59b1 · 2026-03-16T20:24:37.000+01:00
diff --git a/doc/api/v8.md b/doc/api/v8.md
@@ -1788,41 +1788,23 @@ const profile = handle.stop();
 console.log(profile);
 ```
 
-## `v8.heapProfilerConstants`
+## `v8.startHeapProfile([options])`
 
 <!-- YAML
 added: REPLACEME
 -->
 
-* {Object}
-
-A frozen object containing constants used with [`v8.startHeapProfile()`][].
-
-The following constants are available:
-
-| Constant                                         | Description                                         |
-| ------------------------------------------------ | --------------------------------------------------- |
-| `SAMPLING_NO_FLAGS`                              | No flags.                                           |
-| `SAMPLING_FORCE_GC`                              | Force garbage collection before taking the profile. |
-| `SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC` | Include objects collected by major GC.              |
-| `SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC` | Include objects collected by minor GC.              |
-
-These constants can be combined using bitwise OR to pass as the `flags`
-parameter.
-
-## `v8.startHeapProfile([sampleInterval[, stackDepth[, flags]]])`
-
-<!-- YAML
-added: REPLACEME
--->
-
-* `sampleInterval` {number} The average sampling interval in bytes.
-  **Default:** `524288` (512 KiB).
-* `stackDepth` {integer} The maximum stack depth for samples.
-  **Default:** `16`.
-* `flags` {integer} Flags to control sampling behavior. Use constants from
-  [`v8.heapProfilerConstants`][]. Multiple flags can be combined with bitwise
-  OR. **Default:** `v8.heapProfilerConstants.SAMPLING_NO_FLAGS`.
+* `options` {Object}
+  * `sampleInterval` {number} The average sampling interval in bytes.
+    **Default:** `524288` (512 KiB).
+  * `stackDepth` {integer} The maximum stack depth for samples.
+    **Default:** `16`.
+  * `forceGC` {boolean} Force garbage collection before taking the profile.
+    **Default:** `false`.
+  * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected
+    by major GC. **Default:** `false`.
+  * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected
+    by minor GC. **Default:** `false`.
 * Returns: {SyncHeapProfileHandle}
 
 Starting a heap profile then return a `SyncHeapProfileHandle` object.
@@ -1848,28 +1830,26 @@ With custom parameters:
 
 ```cjs
 const v8 = require('node:v8');
-const { heapProfilerConstants } = v8;
-
-const handle = v8.startHeapProfile(
-  1024,
-  8,
-  heapProfilerConstants.SAMPLING_FORCE_GC |
-    heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC,
-);
+
+const handle = v8.startHeapProfile({
+  sampleInterval: 1024,
+  stackDepth: 8,
+  forceGC: true,
+  includeObjectsCollectedByMajorGC: true,
+});
 const profile = handle.stop();
 console.log(profile);
 ```
 
 ```mjs
 import v8 from 'node:v8';
-const { heapProfilerConstants } = v8;
-
-const handle = v8.startHeapProfile(
-  1024,
-  8,
-  heapProfilerConstants.SAMPLING_FORCE_GC |
-    heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC,
-);
+
+const handle = v8.startHeapProfile({
+  sampleInterval: 1024,
+  stackDepth: 8,
+  forceGC: true,
+  includeObjectsCollectedByMajorGC: true,
+});
 const profile = handle.stop();
 console.log(profile);
 ```
@@ -1908,8 +1888,6 @@ console.log(profile);
 [`serializer.transferArrayBuffer()`]: #serializertransferarraybufferid-arraybuffer
 [`serializer.writeRawBytes()`]: #serializerwriterawbytesbuffer
 [`settled` callback]: #settledpromise
-[`v8.heapProfilerConstants`]: #v8heapprofilerconstants
-[`v8.startHeapProfile()`]: #v8startheapprofilesampleinterval-stackdepth-flags
 [`v8.stopCoverage()`]: #v8stopcoverage
 [`v8.takeCoverage()`]: #v8takecoverage
 [`vm.Script`]: vm.md#new-vmscriptcode-options
diff --git a/doc/api/worker_threads.md b/doc/api/worker_threads.md
@@ -2005,21 +2005,25 @@ w.on('online', async () => {
 });
 ```
 
-### `worker.startHeapProfile([sampleInterval[, stackDepth[, flags]]])`
+### `worker.startHeapProfile([options])`
 
 <!-- YAML
 added:
   - v24.9.0
   - v22.20.0
 -->
 
-* `sampleInterval` {number} The average sampling interval in bytes.
-  **Default:** `524288` (512 KiB).
-* `stackDepth` {integer} The maximum stack depth for samples.
-  **Default:** `16`.
-* `flags` {integer} Flags to control sampling behavior. Use constants from
-  [`v8.heapProfilerConstants`][]. Multiple flags can be combined with bitwise
-  OR. **Default:** `v8.heapProfilerConstants.SAMPLING_NO_FLAGS`.
+* `options` {Object}
+  * `sampleInterval` {number} The average sampling interval in bytes.
+    **Default:** `524288` (512 KiB).
+  * `stackDepth` {integer} The maximum stack depth for samples.
+    **Default:** `16`.
+  * `forceGC` {boolean} Force garbage collection before taking the profile.
+    **Default:** `false`.
+  * `includeObjectsCollectedByMajorGC` {boolean} Include objects collected
+    by major GC. **Default:** `false`.
+  * `includeObjectsCollectedByMinorGC` {boolean} Include objects collected
+    by minor GC. **Default:** `false`.
 * Returns: {Promise}
 
 Starting a Heap profile then return a Promise that fulfills with an error
@@ -2303,7 +2307,6 @@ thread spawned will spawn another until the application crashes.
 [`trace_events`]: tracing.md
 [`v8.getHeapSnapshot()`]: v8.md#v8getheapsnapshotoptions
 [`v8.getHeapStatistics()`]: v8.md#v8getheapstatistics
-[`v8.heapProfilerConstants`]: v8.md#v8heapprofilerconstants
 [`vm`]: vm.md
 [`worker.SHARE_ENV`]: #worker_threadsshare_env
 [`worker.on('message')`]: #event-message_1
diff --git a/lib/internal/v8/heap_profile.js b/lib/internal/v8/heap_profile.js
@@ -1,12 +1,10 @@
 'use strict';
 
 const {
-  ObjectFreeze,
-} = primordials;
-
-const {
+  validateBoolean,
   validateInteger,
   validateInt32,
+  validateObject,
 } = require('internal/validators');
 
 const {
@@ -16,34 +14,36 @@ const {
   kSamplingIncludeObjectsCollectedByMinorGC,
 } = internalBinding('v8');
 
-const heapProfilerConstants = {
-  __proto__: null,
-  SAMPLING_NO_FLAGS: kSamplingNoFlags,
-  SAMPLING_FORCE_GC: kSamplingForceGC,
-  SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC:
-    kSamplingIncludeObjectsCollectedByMajorGC,
-  SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC:
-    kSamplingIncludeObjectsCollectedByMinorGC,
-};
-ObjectFreeze(heapProfilerConstants);
+function normalizeHeapProfileOptions(options = {}) {
+  validateObject(options, 'options');
+  const {
+    sampleInterval = 512 * 1024,
+    stackDepth = 16,
+    forceGC = false,
+    includeObjectsCollectedByMajorGC = false,
+    includeObjectsCollectedByMinorGC = false,
+  } = options;
+
+  validateInteger(sampleInterval, 'options.sampleInterval', 1);
+  validateInt32(stackDepth, 'options.stackDepth', 0);
+  validateBoolean(forceGC, 'options.forceGC');
+  validateBoolean(includeObjectsCollectedByMajorGC,
+                  'options.includeObjectsCollectedByMajorGC');
+  validateBoolean(includeObjectsCollectedByMinorGC,
+                  'options.includeObjectsCollectedByMinorGC');
 
-const kMaxSamplingFlags =
-  heapProfilerConstants.SAMPLING_FORCE_GC |
-  heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MAJOR_GC |
-  heapProfilerConstants.SAMPLING_INCLUDE_OBJECTS_COLLECTED_BY_MINOR_GC;
+  let flags = kSamplingNoFlags;
+  if (forceGC) flags |= kSamplingForceGC;
+  if (includeObjectsCollectedByMajorGC) {
+    flags |= kSamplingIncludeObjectsCollectedByMajorGC;
+  }
+  if (includeObjectsCollectedByMinorGC) {
+    flags |= kSamplingIncludeObjectsCollectedByMinorGC;
+  }
 
-function normalizeHeapProfileOptions(
-  sampleInterval = 512 * 1024,
-  stackDepth = 16,
-  flags = heapProfilerConstants.SAMPLING_NO_FLAGS,
-) {
-  validateInteger(sampleInterval, 'sampleInterval', 1);
-  validateInt32(stackDepth, 'stackDepth', 0);
-  validateInt32(flags, 'flags', 0, kMaxSamplingFlags);
   return { sampleInterval, stackDepth, flags };
 }
 
 module.exports = {
-  heapProfilerConstants,
   normalizeHeapProfileOptions,
 };
diff --git a/lib/internal/worker.js b/lib/internal/worker.js
@@ -590,9 +590,18 @@ class Worker extends EventEmitter {
     });
   }
 
-  startHeapProfile(sampleInterval, stackDepth, flags) {
-    ({ sampleInterval, stackDepth, flags } =
-      normalizeHeapProfileOptions(sampleInterval, stackDepth, flags));
+  /**
+   * @param {object} [options]
+   * @param {number} [options.sampleInterval]
+   * @param {number} [options.stackDepth]
+   * @param {boolean} [options.forceGC]
+   * @param {boolean} [options.includeObjectsCollectedByMajorGC]
+   * @param {boolean} [options.includeObjectsCollectedByMinorGC]
+   * @returns {Promise}
+   */
+  startHeapProfile(options) {
+    const { sampleInterval, stackDepth, flags } =
+      normalizeHeapProfileOptions(options);
     const startTaker = this[kHandle]?.startHeapProfile(
       sampleInterval, stackDepth, flags);
     return new Promise((resolve, reject) => {
diff --git a/lib/v8.js b/lib/v8.js
@@ -26,7 +26,6 @@ const {
   Int32Array,
   Int8Array,
   JSONParse,
-  ObjectDefineProperty,
   ObjectPrototypeToString,
   SymbolDispose,
   Uint16Array,
@@ -52,7 +51,6 @@ const {
   namespace: startupSnapshot,
 } = require('internal/v8/startup_snapshot');
 const {
-  heapProfilerConstants,
   normalizeHeapProfileOptions,
 } = require('internal/v8/heap_profile');
 
@@ -225,14 +223,17 @@ function startCpuProfile() {
 
 /**
  * Starting Heap Profile.
- * @param {number} [sampleInterval]
- * @param {number} [stackDepth]
- * @param {number} [flags]
+ * @param {object} [options]
+ * @param {number} [options.sampleInterval]
+ * @param {number} [options.stackDepth]
+ * @param {boolean} [options.forceGC]
+ * @param {boolean} [options.includeObjectsCollectedByMajorGC]
+ * @param {boolean} [options.includeObjectsCollectedByMinorGC]
  * @returns {SyncHeapProfileHandle}
  */
-function startHeapProfile(sampleInterval, stackDepth, flags) {
-  ({ sampleInterval, stackDepth, flags } =
-    normalizeHeapProfileOptions(sampleInterval, stackDepth, flags));
+function startHeapProfile(options) {
+  const { sampleInterval, stackDepth, flags } =
+    normalizeHeapProfileOptions(options);
   _startHeapProfile(sampleInterval, stackDepth, flags);
   return new SyncHeapProfileHandle();
 }
@@ -557,10 +558,3 @@ module.exports = {
   startCpuProfile,
   startHeapProfile,
 };
-
-ObjectDefineProperty(module.exports, 'heapProfilerConstants', {
-  __proto__: null,
-  configurable: false,
-  enumerable: true,
-  value: heapProfilerConstants,
-});
diff --git a/src/util.cc b/src/util.cc
@@ -816,7 +816,7 @@ v8::Maybe<int> GetValidFileMode(Environment* env,
   return v8::Just(mode);
 }
 
-static void buildHeapProfileNode(Isolate* isolate,
+static void BuildHeapProfileNode(Isolate* isolate,
                                  const AllocationProfile::Node* node,
                                  JSONWriter* writer) {
   size_t selfSize = 0;
@@ -838,7 +838,7 @@ static void buildHeapProfileNode(Isolate* isolate,
   writer->json_arraystart("children");
   for (const auto* child : node->children) {
     writer->json_start();
-    buildHeapProfileNode(isolate, child, writer);
+    BuildHeapProfileNode(isolate, child, writer);
     writer->json_end();
   }
   writer->json_arrayend();
@@ -866,7 +866,7 @@ bool SerializeHeapProfile(Isolate* isolate, std::ostringstream& out_stream) {
   writer.json_arrayend();
 
   writer.json_objectstart("head");
-  buildHeapProfileNode(isolate, profile->GetRootNode(), &writer);
+  BuildHeapProfileNode(isolate, profile->GetRootNode(), &writer);
   writer.json_objectend();
 
   writer.json_end();
diff --git a/test/parallel/test-v8-heap-profile.js b/test/parallel/test-v8-heap-profile.js
diff --git a/test/parallel/test-worker-heap-profile.js b/test/parallel/test-worker-heap-profile.js
