Skip to main content

Interface: IHeapNode

An IHeapNode instance represents a JS heap object in a heap snapshot. A heap snapshot is generally a graph where graph nodes are JS heap objects and graph edges are JS references among JS heap objects.

readonly it is not recommended to modify any IHeapNode instance

import type {IHeapSnapshot, IHeapNode} from '@memlab/core';
import {dumpNodeHeapSnapshot} from '@memlab/core';
import {getFullHeapFromFile} from '@memlab/heap-analysis';

(async function () {
const heapFile = dumpNodeHeapSnapshot();
const heap: IHeapSnapshot = await getFullHeapFromFile(heapFile);

// iterate over each node (heap object)
heap.nodes.forEach((node: IHeapNode, i: number) => {
// use the heap node APIs here
const id = node.id;
const type = node.type;
// ...
});
})();

Hierarchy

Properties

dominatorNode: Nullable<IHeapNode>

get the dominator node of this node. If the dominator node gets released there will be no path from GC to this node, and therefore this node can also be released. For more information on what a dominator node is, please check out this doc.


edge_count: number

The total number of outgoing JS references (including engine-internal, native, and JS references).


hasPathEdge: boolean

returns true if the heap node has been set an incoming edge which leads to the parent node on the shortest path to GC root.


id: number

unique id of the heap object


isString: boolean

check if this a string node (normal string node, concatenated string node or sliced string node)


is_detached: boolean

  • If the heap object is a DOM element and the DOM element is detached from the DOM tree, is_detached will be true;

  • If the heap object is a React Fiber node and the Fiber node is unmounted from the React Fiber tree, is_detached will be true; otherwise it will be false

  • Source:


location: Nullable<IHeapLocation>

source location information of this heap object (if it is recorded by the heap snapshot).


name: string

this is the name field associated with the heap object, for JS object instances (type object), name is the constructor's name of the object instance. for string, name is the string value.


nodeIndex: number

index of this heap object inside the node.snapshot.nodes pseudo array


numOfReferrers: number

Get the number of all incoming references pointing to this heap object (including engine-internal, native, and JS references).


pathEdge: null | IHeapEdge

The incoming edge which leads to the parent node on the shortest path to GC root.


references: IHeapEdge[]

Get a JS array containing all outgoing JS references from this heap object (including engine-internal, native, and JS references).


referrers: IHeapEdge[]

Get a JS array containing all incoming JS references pointing to this heap object (including engine-internal, native, and JS references).


retainedSize: number

The retained size of the heap object (i.e., the total size of memory that could be released if this object is released). For difference between retained size and shallow size, check out this doc.


self_size: number

The shallow size of the heap object (i.e., the size of memory that is held by the object itself.). For difference between shallow size and retained size, check out this doc.


snapshot: IHeapSnapshot

get the IHeapSnapshot containing this heap object


type: string

the type of the heap node object. All possible types: This is engine-specific, for example all types in V8: hidden, array, string, object, code, closure, regexp, number, native, synthetic, concatenated string, sliced string, symbol, bigint

Methods

findAnyReference(predicate)

executes a provided predicate callback once for each JavaScript reference in the hosting node (or outgoing edges from the node) until the predicate returns true

  • Parameters:

  • Returns: Nullable<IHeapEdge> | the first outgoing edge for which the predicate returns true, otherwise returns null if no such edge is found.

  • Examples:

const reference = node.findAnyReference((edge: IHeapEdge) => {
// find the outgoing reference with name "ref"
return edge.name_or_index === 'ref';
});

findAnyReferrer(predicate)

executes a provided predicate callback once for each JavaScript reference pointing to the hosting node (or incoming edges to the node) until the predicate returns true

  • Parameters:

  • Returns: Nullable<IHeapEdge> | the first incoming edge for which the predicate returns true, otherwise returns null if no such edge is found.

  • Examples:

const referrer = node.findAnyReferrer((edge: IHeapEdge) => {
// find the incoming reference with name "ref"
return edge.name_or_index === 'ref';
});

findAnyReferrerNode(predicate)

executes a provided predicate callback once for each JavaScript heap object (heap graph node) pointing to the hosting node (or nodes having edges to the hosting node) until the predicate returns true

  • Parameters:

  • Returns: Nullable<IHeapNode> | the first referring node for which the predicate returns true, otherwise returns null if no such node is found.

  • Examples:

const referrer = node.findAnyReferrerNode((node: IHeapNode) => {
// find the referring node with name "Parent"
return node.name === 'Parent';
});

findReferrerNodes(predicate)

executes a provided predicate callback once for each JavaScript heap object (heap graph node) pointing to the hosting node (or nodes having edges to the hosting node)

  • Parameters:

  • Returns: IHeapNode[] | an array containing all the referrer nodes for which the predicate returns true, otherwise returns an empty array if no such node is found.

  • Examples:

const referrerNodes = node.findReferrerNodes((node: IHeapNode) => {
// find all the referring nodes with name "Parent"
return node.name === 'Parent';
});

findReferrers(predicate)

executes a provided predicate callback once for each JavaScript reference pointing to the hosting node (or incoming edges to the node)

  • Parameters:

  • Returns: IHeapEdge[] | an array containing all the incoming edges for which the predicate returns true, otherwise returns an empty array if no such edge is found.

  • Examples:

const referrers = node.findReferrers((edge: IHeapEdge) => {
// find all the incoming references with name "ref"
return edge.name_or_index === 'ref';
});

forEachReference(callback)

executes a provided callback once for each JavaScript reference in the hosting node (or outgoing edges from the node)

  • Parameters:

  • Returns: void | this API returns void

  • Examples:

node.forEachReference((edge: IHeapEdge) => {
// process edge ...

// if no need to iterate over remaining edges after
// the current edge in the node.references list
return {stop: true};
});

forEachReferrer(callback)

executes a provided callback once for each JavaScript reference pointing to the hosting node (or incoming edges to the node)

  • Parameters:

  • Returns: void | this API returns void

  • Examples:

node.forEachReferrer((edge: IHeapEdge) => {
// process edge ...

// if no need to iterate over remaining edges after
// the current edge in the node.referrers list
return {stop: true};
});

getAnyReferrer(edgeName, edgeType?)

Given a JS reference's name and type, this API finds an incoming JS reference pointing to the hosting node.

  • Parameters:

    • edgeName: string | number | the name of the incoming JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the incoming JavaScript reference
  • Returns: Nullable<IHeapEdge> | the incoming edge that meets the specification

  • Examples:

// find one of the JS reference named "ref" pointing to node
const reference = node.getAnyReferrer('ref', 'property');

getAnyReferrerNode(edgeName, edgeType?)

Given a JS reference's name and type, this API finds one of the incoming JS references pointing to the hosting node, and returns the JS heap object containing the incoming reference.

  • Parameters:

    • edgeName: string | number | the name of the incoming JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the incoming JavaScript reference
  • Returns: Nullable<IHeapNode> | the node containing the incoming JS reference that meets the specification

  • Examples:

// find one of the JS heap object with a JS reference
// named "ref" pointing to node
const n1 = node.getAnyReferrerNode('ref', 'property');
// this is equivalent to
const n2 = node.getAnyReferrer('ref', 'property')?.fromNode;

getReference(edgeName, edgeType?)

Given a JS reference's name and type, this API finds an outgoing JS reference from the hosting node.

  • Parameters:

    • edgeName: string | number | the name of the outgoing JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the outgoing JavaScript reference
  • Returns: Nullable<IHeapEdge> | the outgoing edge that meets the specification

  • Examples:

// find the internal reference to node's hidden class
const reference = node.getReference('map', 'hidden');

getReferenceNode(edgeName, edgeType?)

Given a JS reference's name and type, this API finds the outgoing JS reference from the hosting node, and returns the JS heap object pointed to by the outgoing JS reference.

  • Parameters:

    • edgeName: string | number | the name of the outgoing JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the outgoing JavaScript reference
  • Returns: Nullable<IHeapNode> | the node pointed to by the outgoing reference that meets the specification

  • Examples:

// find the node's hidden class
const hiddenClassNode = node.getReferenceNode('map', 'hidden');
// this is equivalent to
const hiddenClassNode2 = node.getReference('map', 'hidden')?.toNode;

getReferrerNodes(edgeName, edgeType?)

Given a JS reference's name and type, this API finds all of the incoming JS references pointing to the hosting node, and returns an array containing the hosting node for each of the incoming JS references.

  • Parameters:

    • edgeName: string | number | the name of the incoming JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the incoming JavaScript reference
  • Returns: IHeapNode[] | an array containing the hosting nodes, with each node corresponds to each incoming JS reference that meets the specification

  • Examples:

// find all of the JS heap object with a JS reference
// named "ref" pointing to node
const nodes1 = node.getReferrerNodes('ref', 'property');
// this is equivalent to
const nodes2 = node.getReferrers('ref', 'property')
.map(edge => edge.fromNode);

getReferrers(edgeName, edgeType?)

Given a JS reference's name and type, this API finds all the incoming JS reference pointing to the hosting node.

  • Parameters:

    • edgeName: string | number | the name of the incoming JavaScript reference
    • edgeType?: string | optional parameter specifying the type of the incoming JavaScript reference
  • Returns: IHeapEdge[] | an array containing all the incoming edges that meet the specification

  • Examples:

// find all of of the JS reference named "ref" pointing to node
const referrers = node.getReferrers('ref', 'property');

toJSONString(...args)

convert to a concise readable string output (like calling JSON.stringify(node, ...args)).

Note: Please be aware that using JSON.stringify(node, ...args) is not recommended as it will generate a JSON representation of the host object that is too large to be easily readable due to its connections to other parts of the data structures within the heap snapshot.

This API does not completely serialize all the information captured by the hosting object.


toStringNode()

convert to an IHeapStringNode object if this node is a string node. The IHeapStringNode object supports querying the string content inside the string node.

  • Hierarchy
  • Properties
    • dominatorNode: Nullable<IHeapNode>
    • edge_count: number
    • hasPathEdge: boolean
    • id: number
    • isString: boolean
    • is_detached: boolean
    • location: Nullable<IHeapLocation>
    • name: string
    • nodeIndex: number
    • numOfReferrers: number
    • pathEdge: null | IHeapEdge
    • references: IHeapEdge[]
    • referrers: IHeapEdge[]
    • retainedSize: number
    • self_size: number
    • snapshot: IHeapSnapshot
    • type: string
  • Methods
    • findAnyReference(predicate)
    • findAnyReferrer(predicate)
    • findAnyReferrerNode(predicate)
    • findReferrerNodes(predicate)
    • findReferrers(predicate)
    • forEachReference(callback)
    • forEachReferrer(callback)
    • getAnyReferrer(edgeName, edgeType?)
    • getAnyReferrerNode(edgeName, edgeType?)
    • getReference(edgeName, edgeType?)
    • getReferenceNode(edgeName, edgeType?)
    • getReferrerNodes(edgeName, edgeType?)
    • getReferrers(edgeName, edgeType?)
    • toJSONString(...args)
    • toStringNode()