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
- Examples: V8 or hermes heap snapshot can be parsed by the getFullHeapFromFile API.
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
IHeapNodeBasic↳
IHeapNode
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.
- Source:
edge_count: number
The total number of outgoing JS references (including engine-internal, native, and JS references).
- Source:
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.
- Source:
id: number
unique id of the heap object
- Source:
isString: boolean
check if this a string node (normal string node, concatenated string node or sliced string node)
- Source:
is_detached: boolean
If the heap object is a DOM element and the DOM element is detached from the DOM tree,
is_detachedwill betrue;If the heap object is a React Fiber node and the Fiber node is unmounted from the React Fiber tree,
is_detachedwill betrue; otherwise it will befalseSource:
location: Nullable<IHeapLocation>
source location information of this heap object (if it is recorded by the heap snapshot).
- Source:
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.
- Source:
nodeIndex: number
index of this heap object inside the node.snapshot.nodes pseudo array
- Source:
numOfReferrers: number
Get the number of all incoming references pointing to this heap object (including engine-internal, native, and JS references).
- Source:
pathEdge: null | IHeapEdge
The incoming edge which leads to the parent node on the shortest path to GC root.
- Source:
references: IHeapEdge[]
Get a JS array containing all outgoing JS references from this heap object (including engine-internal, native, and JS references).
- Source:
referrers: IHeapEdge[]
Get a JS array containing all incoming JS references pointing to this heap object (including engine-internal, native, and JS references).
- Source:
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.
- Source:
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.
- Source:
snapshot: IHeapSnapshot
get the IHeapSnapshot containing this heap object
- Source:
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
- Source:
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:
predicate:Predicator<IHeapEdge> | the callback for each outgoing JavaScript reference
Returns:
Nullable<IHeapEdge> | the first outgoing edge for which the predicate returnstrue, otherwise returnsnullif 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';
});
- Source:
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:
predicate:Predicator<IHeapEdge> | the callback for each incoming JavaScript reference
Returns:
Nullable<IHeapEdge> | the first incoming edge for which the predicate returnstrue, otherwise returnsnullif 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';
});
- Source:
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:
predicate:Predicator<IHeapNode> | the callback for each incoming JavaScript heap object
Returns:
Nullable<IHeapNode> | the first referring node for which the predicate returnstrue, otherwise returnsnullif no such node is found.Examples:
const referrer = node.findAnyReferrerNode((node: IHeapNode) => {
// find the referring node with name "Parent"
return node.name === 'Parent';
});
- Source:
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:
predicate:Predicator<IHeapNode> | the callback for each referrer nodes
Returns:
IHeapNode[] | an array containing all the referrer nodes for which the predicate returnstrue, 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';
});
- Source:
findReferrers(predicate)
executes a provided predicate callback once for each JavaScript reference pointing to the hosting node (or incoming edges to the node)
Parameters:
predicate:Predicator<IHeapEdge> | the callback for each incoming JavaScript reference
Returns:
IHeapEdge[] | an array containing all the incoming edges for which the predicate returnstrue, 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';
});
- Source:
forEachReference(callback)
executes a provided callback once for each JavaScript reference in the hosting node (or outgoing edges from the node)
Parameters:
callback:EdgeIterationCallback| the callback for each outgoing JavaScript reference
Returns:
void| this API returns voidExamples:
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};
});
- Source:
forEachReferrer(callback)
executes a provided callback once for each JavaScript reference pointing to the hosting node (or incoming edges to the node)
Parameters:
callback:EdgeIterationCallback| the callback for each incoming JavaScript reference
Returns:
void| this API returns voidExamples:
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};
});
- Source:
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 referenceedgeType?:string| optional parameter specifying the type of the incoming JavaScript reference
Returns:
Nullable<IHeapEdge> | the incoming edge that meets the specificationExamples:
// find one of the JS reference named "ref" pointing to node
const reference = node.getAnyReferrer('ref', 'property');
- Source:
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 referenceedgeType?:string| optional parameter specifying the type of the incoming JavaScript reference
Returns:
Nullable<IHeapNode> | the node containing the incoming JS reference that meets the specificationExamples:
// 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;
- Source:
getJSONifyableObject()
convert to a concise readable object that can be used for serialization
(like calling JSON.stringify(node, ...args)).
This API does not contain all the information captured by the hosting object.
- Returns:
AnyRecord - Source:
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 referenceedgeType?:string| optional parameter specifying the type of the outgoing JavaScript reference
Returns:
Nullable<IHeapEdge> | the outgoing edge that meets the specificationExamples:
// find the internal reference to node's hidden class
const reference = node.getReference('map', 'hidden');
- Source:
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 referenceedgeType?: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 specificationExamples:
// find the node's hidden class
const hiddenClassNode = node.getReferenceNode('map', 'hidden');
// this is equivalent to
const hiddenClassNode2 = node.getReference('map', 'hidden')?.toNode;
- Source:
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 referenceedgeType?: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 specificationExamples:
// 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);
- Source:
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 referenceedgeType?:string| optional parameter specifying the type of the incoming JavaScript reference
Returns:
IHeapEdge[] | an array containing all the incoming edges that meet the specificationExamples:
// find all of of the JS reference named "ref" pointing to node
const referrers = node.getReferrers('ref', 'property');
- Source:
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.
- Parameters:
...args:any[]
- Returns:
string - Source:
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.
- Returns:
Nullable<IHeapStringNode> - Source: