Repository navigation
node:v8: expose heap statistics shape #3138
Description
Summary
node:v8 should expose diagnostic heap/version stat helpers with Node-compatible object shapes: cachedDataVersionTag(), getHeapStatistics(), getHeapCodeStatistics(), and getHeapSpaceStatistics(). Perry currently has no public node:v8 namespace implementation for these diagnostic APIs.
Node Behavior
A minimal Node probe shows the expected diagnostic shapes:
const v8 = require("node:v8");
console.log(typeof v8.cachedDataVersionTag(), v8.cachedDataVersionTag());
console.log(Object.keys(v8.getHeapStatistics()).sort());
console.log(Object.keys(v8.getHeapCodeStatistics()).sort());
console.log(v8.getHeapSpaceStatistics()[0]);Observed on Node v25.9.0: cachedDataVersionTag() returns a number; getHeapStatistics() returns numeric fields such as total_heap_size, used_heap_size, heap_size_limit, external_memory, number_of_native_contexts, and total_allocated_bytes; getHeapCodeStatistics() returns numeric code/bytecode/script-source/profiler fields; getHeapSpaceStatistics() returns an array of objects with space_name, space_size, space_used_size, space_available_size, and physical_space_size. Extra arguments are ignored for these helpers.
Perry Behavior
docs/runtime-parity-gaps.md lists v8.cachedDataVersionTag(), v8.getHeapCodeStatistics(), v8.getHeapSpaceStatistics(), and v8.getHeapStatistics(); docs/runtime-parity.md marks them missing. Source search across crates/perry-api-manifest/src/entries.rs, crates/perry-runtime/src, crates/perry-codegen/src, and crates/perry-stdlib/src found no public node:v8 diagnostic-stat implementation. There is no dedicated V8 parity fixture in this checkout.
Suggested PR Cut
Batch this with related issues in:
#2492 - node:v8: diagnostics and serialization parity cut
Good batch candidates:
- node:v8: expose serialize and deserialize round trips #3137
- node:v8: expose Serializer and Deserializer class APIs #3294
Do not batch with:
- unrelated modules
- broad subsystem rewrites
- fixes needing different test harnesses
- promise hook APIs
- startup snapshot APIs
- heap snapshot stream/file output
- profiler handle APIs
Acceptance
- A parity/regression test proves
cachedDataVersionTag(),getHeapStatistics(),getHeapCodeStatistics(), andgetHeapSpaceStatistics()return Node-compatible object/array shapes with numeric values for covered keys. - Extra arguments are ignored for the covered helpers, matching Node.
- Values may reflect Perry internals rather than V8 internals, but field names and value types match Node for package feature detection.
- Related known-failure/docs/manifest entries are updated if touched.
Activity
andrewtdiz commentedon May 30, 2026
I am taking this as part of a
node:v8diagnostics and serialization PR cut with #3137 and #3294.Intended scope: expose the public
node:v8namespace forserialize/deserialize, diagnostic heap-stat shape helpers, and the Serializer/Deserializer class API using one V8 parity fixture and shared runtime dispatch path.andrewtdiz commentedon May 30, 2026
Opened PR #3428 to address this in the shared
node:v8diagnostics/serialization surface: #3428fix(node:v8): serialize/deserialize + getHeapStatistics + GCProfiler (#…