Node.js v8 module | API Reference | Bun

The 'node:v8' module exposes APIs for heap snapshots and memory profiling. In Node.js these are V8-specific; Bun provides compatible implementations using JavaScriptCore.

Methods include v8.getHeapSnapshot(), v8.writeHeapSnapshot(), and v8.takeHeapSnapshot().

`writeHeapSnapshot` and `getHeapSnapshot` are implemented. `serialize` and `deserialize` use JavaScriptCore's wire format, not V8's. Most other V8-specific methods are not implemented. For profiling, consider using `bun:jsc`.

The v8.startupSnapshot interface can be used to add serialization and deserialization hooks for custom startup snapshots.

node --snapshot-blob snapshot.blob --build-snapshot entry.js

# This launches a process with the snapshot

node --snapshot-blob snapshot.blob

In the example above, entry.js can use methods from the v8.startupSnapshot interface to specify how to save information for custom objects in the snapshot during serialization and how the information can be used to synchronize these objects during deserialization of the snapshot. For example, if the entry.js contains the following script:

'use strict';

import fs from 'node:fs';
import zlib from 'node:zlib';
import path from 'node:path';
import assert from 'node:assert';

import v8 from 'node:v8';

class BookShelf {
storage = new Map();

// Reading a series of files from directory and store them into storage.
constructor(directory, books) {
for (const book of books) {
this.storage.set(book, fs.readFileSync(path.join(directory, book)));
}
}

static compressAll(shelf) {
for (const [ book, content ] of shelf.storage) {
shelf.storage.set(book, zlib.gzipSync(content));
}
}

static decompressAll(shelf) {
for (const [ book, content ] of shelf.storage) {
shelf.storage.set(book, zlib.gunzipSync(content));
}
}
}

// __dirname here is where the snapshot script is placed
// during snapshot building time.
const shelf = new BookShelf(__dirname, [
'book1.en_US.txt',
'book1.es_ES.txt',
'book2.zh_CN.txt',
]);

assert(v8.startupSnapshot.isBuildingSnapshot());
// On snapshot serialization, compress the books to reduce size.
v8.startupSnapshot.addSerializeCallback(BookShelf.compressAll, shelf);
// On snapshot deserialization, decompress the books.
v8.startupSnapshot.addDeserializeCallback(BookShelf.decompressAll, shelf);
v8.startupSnapshot.setDeserializeMainFunction((shelf) => {
// process.env and process.argv are refreshed during snapshot
// deserialization.
const lang = process.env.BOOK_LANG || 'en_US';
const book = process.argv[1];
const name = `${book}.${lang}.txt`;
console.log(shelf.storage.get(name));
}, shelf);

The resulted binary will get print the data deserialized from the snapshot during start up, using the refreshed process.env and process.argv of the launched process:

BOOK_LANG=es_ES node --snapshot-blob snapshot.blob book1

# Prints content of book1.es_ES.txt deserialized from the snapshot.

Currently the application deserialized from a user-land snapshot cannot be snapshotted again, so these APIs are only available to applications that are not deserialized from a user-land snapshot.

Add a callback that will be called when the Node.js instance is deserialized from a snapshot. The callback and the data (if provided) will be serialized into the snapshot, they can be used to re-initialize the state of the application or to re-acquire resources that the application needs when the application is restarted from the snapshot.

Add a callback that will be called when the Node.js instance is about to get serialized into a snapshot and exit. This can be used to release resources that should not or cannot be serialized or to convert user data into a form more suitable for serialization.

Returns true if the Node.js instance is run to build a snapshot.

This sets the entry point of the Node.js application when it is deserialized from a snapshot. This can be called only once in the snapshot building script. If called, the deserialized application no longer needs an additional entry point script to start up and will simply invoke the callback along with the deserialized data (if provided), otherwise an entry point script still needs to be provided to the deserialized application.

A subclass of Deserializer corresponding to the format written by DefaultSerializer.

Reads the underlying wire format version. Likely mostly to be useful to legacy code reading old wire format versions. May not be called before .readHeader().

Read a JS number value. For use inside of a custom deserializer._readHostObject().

Reads and validates a header (including the format version). May, for example, reject an invalid or unsupported wire format. In that case, an Error is thrown.

Read raw bytes from the deserializer's internal buffer. The length parameter must correspond to the length of the buffer that was passed to serializer.writeRawBytes(). For use inside of a custom deserializer._readHostObject().

Read a raw 32-bit unsigned integer and return it. For use inside of a custom deserializer._readHostObject().

Read a raw 64-bit unsigned integer and return it as an array [hi, lo] with two 32-bit unsigned integer entries. For use inside of a custom deserializer._readHostObject().

Deserializes a JavaScript value from the buffer and returns it.

Marks an ArrayBuffer as having its contents transferred out of band. Pass the corresponding ArrayBuffer in the serializing context to serializer.transferArrayBuffer() (or return the id from serializer._getSharedArrayBufferId() in the case of SharedArrayBuffers).

A subclass of Serializer that serializes TypedArray(in particular Buffer) and DataView objects as host objects, and only stores the part of their underlying ArrayBuffers that they are referring to.

Returns the stored internal buffer. This serializer should not be used once the buffer is released. Calling this method results in undefined behavior if a previous write has failed.

Marks an ArrayBuffer as having its contents transferred out of band. Pass the corresponding ArrayBuffer in the deserializing context to deserializer.transferArrayBuffer().

Write a JS number value. For use inside of a custom serializer._writeHostObject().

Writes out a header, which includes the serialization format version.

Write raw bytes into the serializer's internal buffer. The deserializer will require a way to compute the length of the buffer. For use inside of a custom serializer._writeHostObject().

Write a raw 32-bit unsigned integer. For use inside of a custom serializer._writeHostObject().

Write a raw 64-bit unsigned integer, split into high and low 32-bit parts. For use inside of a custom serializer._writeHostObject().

Serializes a JavaScript value and adds the serialized representation to the internal buffer.

This throws an error if value cannot be serialized.

Reads the underlying wire format version. Likely mostly to be useful to legacy code reading old wire format versions. May not be called before .readHeader().

Read a JS number value. For use inside of a custom deserializer._readHostObject().

Reads and validates a header (including the format version). May, for example, reject an invalid or unsupported wire format. In that case, an Error is thrown.

Read a raw 32-bit unsigned integer and return it. For use inside of a custom deserializer._readHostObject().

Read a raw 64-bit unsigned integer and return it as an array [hi, lo] with two 32-bit unsigned integer entries. For use inside of a custom deserializer._readHostObject().

Deserializes a JavaScript value from the buffer and returns it.

This API collects GC data in current thread.

Stop collecting GC data, and discard the profile.

Stop collecting GC data and return an object. The content of object is as follows.

{
"version": 1,
"startTime": 1674059033862,
"statistics": [
{
"gcType": "Scavenge",
"beforeGC": {
"heapStatistics": {
"totalHeapSize": 5005312,
"totalHeapSizeExecutable": 524288,
"totalPhysicalSize": 5226496,
"totalAvailableSize": 4341325216,
"totalGlobalHandlesSize": 8192,
"usedGlobalHandlesSize": 2112,
"usedHeapSize": 4883840,
"heapSizeLimit": 4345298944,
"mallocedMemory": 254128,
"externalMemory": 225138,
"peakMallocedMemory": 181760
},
"heapSpaceStatistics": [
{
"spaceName": "read_only_space",
"spaceSize": 0,
"spaceUsedSize": 0,
"spaceAvailableSize": 0,
"physicalSpaceSize": 0
}
]
},
"cost": 1574.14,
"afterGC": {
"heapStatistics": {
"totalHeapSize": 6053888,
"totalHeapSizeExecutable": 524288,
"totalPhysicalSize": 5500928,
"totalAvailableSize": 4341101384,
"totalGlobalHandlesSize": 8192,
"usedGlobalHandlesSize": 2112,
"usedHeapSize": 4059096,
"heapSizeLimit": 4345298944,
"mallocedMemory": 254128,
"externalMemory": 225138,
"peakMallocedMemory": 181760
},
"heapSpaceStatistics": [
{
"spaceName": "read_only_space",
"spaceSize": 0,
"spaceUsedSize": 0,
"spaceAvailableSize": 0,
"physicalSpaceSize": 0
}
]
}
}
],
"endTime": 1674059036865
}

Here's an example.

import { GCProfiler } from 'node:v8';
const profiler = new GCProfiler();
profiler.start();
setTimeout(() => {
console.log(profiler.stop());
}, 1000);