v8: add v8.getCppHeapStatistics() method

Expose `CppHeap` data via
`cppgc::CppHeap::CollectStatistics()` in the v8 module.

doc/api/v8.md

@@ -271,6 +271,92 @@ buffers and external strings.
 }
 ```
 
+## `v8.getCppHeapStatistics([detailLevel])`
+
+Retrieves [CppHeap][] regarding memory consumption and
+utilization statistics using the V8 [`CollectStatistics()`][] function which
+may change from one V8 version to the
+next.
+
+* `detailLevel` {string|undefined}:  **Default:** `'detailed'`.
+  Specifies the level of detail in the returned statistics.
+  Accepted values are:
+  * `'brief'`:  Brief statistics contain only the top-level
+    allocated and used
+    memory statistics for the entire heap.
+  * `'detailed'`: Detailed statistics also contain a break
+    down per space and page, as well as freelist statistics
+    and object type histograms.
+
+It returns an object with a structure similar to the
+[`cppgc::HeapStatistics`][] object. See the [V8 documentation][`cppgc::HeapStatistics struct`]
+for more information about the properties of the object.
+
+```js
+// Detailed
+({
+  committed_size_bytes: 131072,
+  resident_size_bytes: 131072,
+  used_size_bytes: 152,
+  space_statistics: [
+    {
+      name: 'NormalPageSpace0',
+      committed_size_bytes: 0,
+      resident_size_bytes: 0,
+      used_size_bytes: 0,
+      page_stats: [{}],
+      free_list_stats: {},
+    },
+    {
+      name: 'NormalPageSpace1',
+      committed_size_bytes: 131072,
+      resident_size_bytes: 131072,
+      used_size_bytes: 152,
+      page_stats: [{}],
+      free_list_stats: {},
+    },
+    {
+      name: 'NormalPageSpace2',
+      committed_size_bytes: 0,
+      resident_size_bytes: 0,
+      used_size_bytes: 0,
+      page_stats: [{}],
+      free_list_stats: {},
+    },
+    {
+      name: 'NormalPageSpace3',
+      committed_size_bytes: 0,
+      resident_size_bytes: 0,
+      used_size_bytes: 0,
+      page_stats: [{}],
+      free_list_stats: {},
+    },
+    {
+      name: 'LargePageSpace',
+      committed_size_bytes: 0,
+      resident_size_bytes: 0,
+      used_size_bytes: 0,
+      page_stats: [{}],
+      free_list_stats: {},
+    },
+  ],
+  type_names: [],
+  detail_level: 'detailed',
+});
+```
+
+```js
+// Brief
+({
+  committed_size_bytes: 131072,
+  resident_size_bytes: 131072,
+  used_size_bytes: 128864,
+  space_statistics: [],
+  type_names: [],
+  detail_level: 'brief',
+});
+```
+
 ## `v8.queryObjects(ctor[, options])`
 
 <!-- YAML
@@ -1304,12 +1390,14 @@ setTimeout(() => {
 }, 1000);
 ```
 
+[CppHeap]: https://v8docs.nodesource.com/node-22.4/d9/dc4/classv8_1_1_cpp_heap.html
 [HTML structured clone algorithm]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm
 [Hook Callbacks]: #hook-callbacks
 [V8]: https://developers.google.com/v8/
 [`--heapsnapshot-near-heap-limit`]: cli.md#--heapsnapshot-near-heap-limitmax_count
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md
+[`CollectStatistics()`]: https://v8docs.nodesource.com/node-22.4/d9/dc4/classv8_1_1_cpp_heap.html#a3a5d09567758e608fffde50eeabc2feb
 [`DefaultDeserializer`]: #class-v8defaultdeserializer
 [`DefaultSerializer`]: #class-v8defaultserializer
 [`Deserializer`]: #class-v8deserializer
@@ -1323,6 +1411,8 @@ setTimeout(() => {
 [`async_hooks`]: async_hooks.md
 [`before` callback]: #beforepromise
 [`buffer.constants.MAX_LENGTH`]: buffer.md#bufferconstantsmax_length
+[`cppgc::HeapStatistics struct`]: https://v8docs.nodesource.com/node-22.4/df/d2f/structcppgc_1_1_heap_statistics.html
+[`cppgc::HeapStatistics`]: https://v8docs.nodesource.com/node-22.4/d7/d51/heap-statistics_8h_source.html
 [`deserializer._readHostObject()`]: #deserializer_readhostobject
 [`deserializer.transferArrayBuffer()`]: #deserializertransferarraybufferid-arraybuffer
 [`init` callback]: #initpromise-parent

lib/v8.js

@@ -37,7 +37,11 @@ const {
 } = primordials;
 
 const { Buffer } = require('buffer');
-const { validateString, validateUint32 } = require('internal/validators');
+const {
+  validateString,
+  validateUint32,
+  validateOneOf,
+} = require('internal/validators');
 const {
   Serializer,
   Deserializer,
@@ -145,6 +149,8 @@ const {
   heapStatisticsBuffer,
   heapCodeStatisticsBuffer,
   heapSpaceStatisticsBuffer,
+  getCppHeapStatistics: _getCppHeapStatistics,
+  detailLevel,
 } = binding;
 
 const kNumberOfHeapSpaces = kHeapSpaces.length;
@@ -259,6 +265,19 @@ function setHeapSnapshotNearHeapLimit(limit) {
   _setHeapSnapshotNearHeapLimit(limit);
 }
 
+const detailLevelDict = {
+  __proto__: null,
+  detailed: detailLevel.DETAILED,
+  brief: detailLevel.BRIEF,
+};
+
+function getCppHeapStatistics(type = 'detailed') {
+  validateOneOf(type, 'type', ['brief', 'detailed']);
+  const result = _getCppHeapStatistics(detailLevelDict[type]);
+  result.detail_level = type;
+  return result;
+}
+
 /* V8 serialization API */
 
 /* JS methods for the base objects */
@@ -430,6 +449,7 @@ module.exports = {
   getHeapStatistics,
   getHeapSpaceStatistics,
   getHeapCodeStatistics,
+  getCppHeapStatistics,
   setFlagsFromString,
   Serializer,
   Deserializer,