Skip to content

node:v8: expose heap statistics shape #3138

Description

@andrewtdiz

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:

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(), and getHeapSpaceStatistics() 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

  1. andrewtdiz commented on May 30, 2026

    @andrewtdiz
    ContributorAuthor

    I am taking this as part of a node:v8 diagnostics and serialization PR cut with #3137 and #3294.

    Intended scope: expose the public node:v8 namespace for serialize / deserialize, diagnostic heap-stat shape helpers, and the Serializer/Deserializer class API using one V8 parity fixture and shared runtime dispatch path.

  2. andrewtdiz commented on May 30, 2026

    @andrewtdiz
    ContributorAuthor

    Opened PR #3428 to address this in the shared node:v8 diagnostics/serialization surface: #3428

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions