File an issue

node:v8

Node.js v8 module, resolvable via both ESM import and CommonJS require. Elide runs on GraalJS (not V8) — everything in this module is backed by the JVM equivalent.

Implemented operations

OperationImplementation
cachedDataVersionTag()Stable 32-bit integer derived from java.runtime.version + os.arch. Deterministic per binary.
getHeapStatistics()Backed by JVM MemoryMXBean.getHeapMemoryUsage().
getHeapSpaceStatistics()One entry per JVM heap memory pool (MemoryPoolMXBean with MemoryType.HEAP).
setFlagsFromString(flags)Validates the argument is a string; no-op — GraalJS does not honour V8 flags.
serialize(value)JSON-encoded UTF-8 bytes wrapped in a Uint8Array.
deserialize(buffer)Reverse of serialize: UTF-8 decode → JSON.parse.

getHeapStatistics shape

Returns an object with the same key-set as Node's V8:

{
  total_heap_size:             committed heap bytes (JVM),
  total_heap_size_executable:  committed non-heap (code) bytes,
  total_physical_size:         same as total_heap_size,
  total_available_size:        max - used heap,
  used_heap_size:              used heap bytes,
  heap_size_limit:             max heap bytes,

  // V8-internal counters that have no direct JVM equivalent;
  // zero-filled for shape compatibility:
  malloced_memory:             0,
  peak_malloced_memory:        0,
  does_zap_garbage:            0,
  number_of_native_contexts:   0,
  number_of_detached_contexts: 0,
  total_global_handles_size:   0,
  used_global_handles_size:    0,
  external_memory:             0
}

getHeapSpaceStatistics shape

Returns an array of per-pool entries:

[
  {
    space_name:            JVM memory pool name (e.g. "G1 Eden Space"),
    space_size:            committed bytes,
    space_used_size:       used bytes,
    space_available_size:  max - used (or 0 if max is undefined),
    physical_space_size:   committed bytes
  },
  ...
]

V8's pool names (new_space, old_space, code_space, …) do not map cleanly to the JVM's — the JVM pool name is surfaced verbatim.

Serialize / deserialize format

v8.serialize and v8.deserialize in Node use V8's internal structured-clone wire format. Elide uses JSON with UTF-8 encoding instead, because GraalJS does not expose V8's wire format. The returned Uint8Array and the shape of the API match Node's so common usage (serializing plain data objects, bytewise storage, round-tripping) works identically. Not supported in this encoding:
  • Map, Set — collapse to {} (JSON behaviour)
  • Date — emitted as ISO strings, not revived on parse
  • Typed arrays — emitted as plain arrays of numbers
  • Circular references — JSON.stringify throws, as in Node

If you need full Node compatibility for these types, wrap the value in a structured-clone-friendly shape before calling serialize.

Example

javascript
const v8 = require("node:v8");

v8.cachedDataVersionTag();                         // → stable integer
v8.getHeapStatistics().used_heap_size;             // → bytes in use
v8.getHeapSpaceStatistics().map(s => s.space_name);// → ["G1 Eden Space", ...]
v8.setFlagsFromString("--no-harmony");             // → undefined (no-op)

const bytes = v8.serialize({ hello: "world" });    // → Uint8Array
const back = v8.deserialize(bytes);                // → { hello: "world" }

See also

  • Node.js upstream: