@memlab/core 1.1.2 → 1.1.3

package/README.md

@@ -2,5 +2,6 @@
 
 This is the memlab core library. It contains V8/Hermes heap snapshot parser, core algorithms, leak trace clustering, utilities, and config.
 
-## Full documentation
-https://facebookincubator.github.io/memlab
+## Online Resources
+* [Official Website and Demo](https://facebookincubator.github.io/memlab)
+* [Documentation](https://facebookincubator.github.io/memlab/docs/intro)

package/dist/lib/Config.d.ts

@@ -171,6 +171,7 @@ export declare class MemLabConfig {
     clusterRetainedSizeThreshold: number;
     _isFullRun: boolean;
     _scenario: Optional<IScenario>;
+    _isHeadfulBrowser: boolean;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
     muteConsole: boolean;
@@ -192,6 +193,8 @@ export declare class MemLabConfig {
     get isFullRun(): boolean;
     set browser(v: string);
     get browser(): string;
+    set isHeadfulBrowser(isHeadful: boolean);
+    get isHeadfulBrowser(): boolean;
     get browserBinaryPath(): string;
     set reportLeaksInTimers(flag: boolean);
     get reportLeaksInTimers(): boolean;

package/dist/lib/Config.js

@@ -54,6 +54,7 @@ class MemLabConfig {
         this._deviceManualOverridden = false;
         this._timerNodes = ['Pending activities'];
         this._timerEdges = [];
+        this._isHeadfulBrowser = false;
         this.targetApp = Constant_1.default.unset;
         this.targetTab = Constant_1.default.unset;
         this.analysisMode = Constant_1.default.unset;
@@ -66,6 +67,7 @@ class MemLabConfig {
         this.specifiedEngine = false;
         // set puppeteer configuration
         this.puppeteerConfig = {
+            headless: !this._isHeadfulBrowser,
             devtools: this.openDevtoolsConsole,
             // IMPORTANT: test ContinuousTest before change this config
             ignoreHTTPSErrors: true,
@@ -358,6 +360,17 @@ class MemLabConfig {
     get browser() {
         return this._browser || 'google-chrome';
     }
+    set isHeadfulBrowser(isHeadful) {
+        this._isHeadfulBrowser = isHeadful;
+        this.puppeteerConfig.headless = !isHeadful;
+        if (isHeadful) {
+            // if running in headful mode
+            this.disableXvfb();
+        }
+    }
+    get isHeadfulBrowser() {
+        return this._isHeadfulBrowser;
+    }
     get browserBinaryPath() {
         return path_1.default.join(this.browserDir, this.browser);
     }

package/dist/lib/Constant.js

@@ -13,8 +13,8 @@ const InternalValueSetter_1 = require("./InternalValueSetter");
 const constants = {
     isFB: false,
     isFRL: false,
-    defaultEngine: 'v8',
-    supportedEngines: ['v8', 'hermes'],
+    defaultEngine: 'V8',
+    supportedEngines: ['V8', 'hermes'],
     supportedBrowsers: Object.create(null),
     internalDir: 'fb-internal',
     monoRepoDir: '',

package/dist/lib/HeapParser.js

@@ -102,7 +102,7 @@ function identifyAndSetEngine(snapshot) {
         return; // skip if engine type is manually set
     }
     Console_1.default.overwrite('identifying snapshot engine...');
-    let engine = 'v8';
+    let engine = 'V8';
     snapshot.nodes.forEach((node) => {
         if (node.type === 'object' && node.name.startsWith('Object(')) {
             engine = 'hermes';

package/dist/lib/Serializer.js

@@ -182,6 +182,9 @@ function JSONifyFiberNodeReturnTrace(node, args, options) {
             continue;
         }
         const parent = node.snapshot.nodes.get(index);
+        if (!parent) {
+            continue;
+        }
         const parentInfo = getNodeNameInJSON(parent, args);
         key = `${key}:  --return (property)--->  ${parentInfo}`;
         const info = JSONifyFiberNodeShallow(parent);
@@ -593,7 +596,7 @@ function summarizeNode(node, options = {}) {
     let nodeImpact = '';
     if (nodeRetainSize) {
         nodeImpact = options.color
-            ? chalk_1.default.grey('[') + chalk_1.default.blue(nodeRetainSize) + chalk_1.default.grey(']')
+            ? chalk_1.default.grey('[') + chalk_1.default.blue.bold(nodeRetainSize) + chalk_1.default.grey(']')
             : `[${nodeRetainSize}]`;
     }
     const name = summarizeNodeName(node, options);

package/dist/lib/Types.d.ts

@@ -96,7 +96,7 @@ export interface IE2EScenarioSynthesizer {
     getOrigin(): Nullable<string>;
     getDomain(): string;
     getDomainPrefixes(): string[];
-    getCookieFile(visitPlan: IE2EScenarioVisitPlan): string | null;
+    getCookieFile(visitPlan: IE2EScenarioVisitPlan): Nullable<string>;
     getAvailableSteps(): IE2EStepBasic[];
     getNodeNameBlocklist(): string[];
     getEdgeNameBlocklist(): string[];
@@ -143,16 +143,49 @@ export declare type QuickExperiment = {
     group: string;
 };
 /**
- * The type for defining custom leak-filtering logic.
- * * **Examples**:
- * ```typescript
- * const scenario = {
+ * The `ILeakFilter` interface allows you to define a leak detector and
+ * customize the leak filtering logic in memlab (instead of using the
+ * built-in leak filters).
  *
- * };
+ * Use the leak filter definition in command line interface to filter
+ * leaks detected from browser interactions
+ * ```bash
+ * memlab run --scenario <SCENARIO FILE> --leak-filter <PATH TO leak-filter.js>
+ * ```
+ *
+ * If you have already run `memlab run` or `memlab snapshot` which saved
+ * heap snapshot and other meta data on disk, use the following command
+ * to filter leaks based on those saved heap snapshots (query the default
+ * data location by `memlab get-default-work-dir`).
  *
- * let map = Object.create(null);
+ * ```bash
+ * memlab find-leaks --leak-filter <PATH TO leak-filter.js>
+ * ```
+ * Here is an example TypeScript file defining a leak filter.
+ * The command line interface only accepts compiled JavaScript file.
+ * You can also define the leak filter in JavaScript (without the
+ * type annotations.
+ *
+ * ```typescript
+ * import {IHeapNode, IHeapSnapshot, HeapNodeIdSet, utils} from '@memlab/core';
+ *
+ * function initMap(snapshot: IHeapSnapshot): Record<string, number> {
+ *   const map = Object.create(null);
+ *   snapshot.nodes.forEach(node => {
+ *     if (node.type !== 'string') {
+ *       return;
+ *     }
+ *     const str = utils.getStringNodeValue(node);
+ *     if (str in map) {
+ *       ++map[str];
+ *     } else {
+ *       map[str] = 1;
+ *     }
+ *   });
+ *   return map;
+ * }
  * const beforeLeakFilter = (snapshot: IHeapSnapshot, _leakedNodeIds: HeapNodeIdSet): void => {
- *   map = initializeMapUsingSnapshot(snapshot);
+ *   map = initMap(snapshot);
  * };
  *
  * // duplicated string with size > 1KB as memory leak
@@ -168,7 +201,81 @@ export declare type QuickExperiment = {
  * ```
  */
 export interface ILeakFilter {
+    /**
+     * Lifecycle function callback that is invoked initially once before
+     * the subsequent `leakFilter` function calls. This callback could
+     * be used to initialize some data stores or any one-off
+     * preprocessings.
+     *
+     * * **Parameters**:
+     *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
+     *     all browser interactions are done.
+     *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
+     *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
+     *     allocated by the `action` call but not released after the `back` call
+     *     in browser.
+     *
+     * * **Examples**:
+     * ```typescript
+     * module.exports = {
+     *   beforeLeakFilter: (snapshot, leakedNodeIds) {
+     *     // initialize some data stores
+     *   },
+     *   leakFilter(node, snapshot, leakedNodeIds) {
+     *     // use the data stores
+     *   },
+     * };
+     * ```
+     */
     beforeLeakFilter?: InitLeakFilterCallback;
+    /**
+     * This callback defines how you want to filter out the
+     * leaked objects. The callback is called for every node (JS heap
+     * object in browser) allocated by the `action` callback, but not
+     * released after the `back` callback. Those objects could be caches
+     * that are retained in memory on purpose, or they are memory leaks.
+     *
+     * This optional callback allows you to define your own algorithm
+     * to cherry pick memory leaks for specific JS program under test.
+     *
+     * If this optional callback is not defined, memlab will use its
+     * built-in leak filter, which considers detached DOM elements
+     * and unmounted Fiber nodes (detached from React Fiber tree) as
+     * memory leaks.
+     *
+     * * **Parameters**:
+     *   * node: `IHeapNode` | one of the heap object allocated but not released.
+     *   * snapshot: `IHeapSnapshot` | the final heap snapshot taken after
+     *     all browser interactions are done.
+     *     Check out {@link IHeapSnapshot} for more APIs that queries the heap snapshot.
+     *   * leakedNodeIds: `Set<number>` | the set of ids of all JS heap objects
+     *     allocated by the `action` call but not released after the `back` call
+     *     in browser.
+     *
+     * * **Returns**: the boolean value indicating whether the given node in
+     *   the snapshot should be considered as leaked.
+     *
+     *
+     * ```javascript
+     * // save as leak-filter.js
+     * module.exports = {
+     *   leakFilter(node, snapshot, leakedNodeIds) {
+     *     // any unreleased node (JS heap object) with 1MB+
+     *     // retained size is considered a memory leak
+     *     return node.retainedSize > 1000000;
+     *   },
+     * };
+     * ```
+     *
+     * Use the leak filter definition in command line interface:
+     * ```bash
+     * memlab find-leaks --leak-filter <PATH TO leak-filter.js>
+     * ```
+     *
+     * ```bash
+     * memlab run --scenario <SCENARIO FILE> --leak-filter <PATH TO leak-filter.js>
+     * ```
+     */
     leakFilter: LeakFilterCallback;
 }
 /**
@@ -217,6 +324,9 @@ export declare type InteractionsCallback = (page: Page, args?: OperationArgs) =>
  *   url: () => 'https://www.npmjs.com/',
  *   action: async () => ... ,
  *   back: async () => ... ,
+ *   cookies: () => ... , // optional
+ *   repeat: () => ... , // optional
+ *   ...
  * };
  * ```
  *
@@ -230,6 +340,9 @@ export declare type InteractionsCallback = (page: Page, args?: OperationArgs) =>
  *     url: () => 'https://www.facebook.com',
  *     action: async () => ... ,
  *     back: async () => ... ,
+ *     cookies: () => ... , // optional
+ *     repeat: () => ... , // optional
+ *     ...
  *   };
  *   const leaks = await run({scenario});
  * })();
@@ -243,17 +356,21 @@ export interface IScenario {
     /**
      * If the page you are running memlab against requires authentication or
      * specific cookie(s) to be set, you can pass them as
-     * a list of <name, value> pairs.
+     * a list of `<name, value, domain>` tuples.
+     *
+     * **Note**: please make sure that you provide the correct `domain` field for
+     * the cookies tuples.
+     *
      * @returns cookie list
      * * **Examples**:
      * ```typescript
      * const scenario = {
      *   url: () => 'https://www.facebook.com/',
      *   cookies: () => [
-     *     {"name":"cm_j","value":"none"},
-     *     {"name":"datr","value":"yJvIY..."},
-     *     {"name":"c_user","value":"8917..."},
-     *     {"name":"xs","value":"95:9WQ..."},
+     *     {name:'cm_j', value: 'none', domain: '.facebook.com'},
+     *     {name:'datr', value: 'yJvIY...', domain: '.facebook.com'},
+     *     {name:'c_user', value: '8917...', domain: '.facebook.com'},
+     *     {name:'xs', value: '95:9WQ...', domain: '.facebook.com'},
      *     // ...
      *   ],
      * };
@@ -354,7 +471,7 @@ export interface IScenario {
     repeat?: () => number;
     /**
      * Optional callback function that checks if the web page is loaded
-     * after for initial page loading and subsequent browser interactions.
+     * for the initial page load and subsequent browser interactions.
      *
      * If this callback is not provided, memlab by default
      * considers a navigation to be finished when there are no network
@@ -390,7 +507,7 @@ export interface IScenario {
     /**
      * Lifecycle function callback that is invoked initially once before
      * the subsequent `leakFilter` function calls. This callback could
-     * be used to initialize some data stores or to do some one-off
+     * be used to initialize some data stores or to any one-off
      * preprocessings.
      *
      * * **Parameters**:
@@ -415,7 +532,7 @@ export interface IScenario {
      */
     beforeLeakFilter?: InitLeakFilterCallback;
     /**
-     * This callback that defines how you want to filter out the
+     * This callback defines how you want to filter out the
      * leaked objects. The callback is called for every node (JS heap
      * object in browser) allocated by the `action` callback, but not
      * released after the `back` callback. Those objects could be caches
@@ -606,6 +723,12 @@ export declare type RunMetaInfo = {
     type: string;
     browserInfo: IBrowserInfo;
 };
+/**
+ * A heap snapshot is generally a graph where graph nodes are JS heap objects
+ * and graph edges are JS references among JS heap objects. For more details
+ * on the structure of nodes and edges in the heap graph, check out
+ * {@link IHeapNode} and {@link IHeapEdge}.
+ */
 export interface IHeapSnapshot {
     /** @internal */
     snapshot: RawHeapSnapshot;
@@ -779,6 +902,10 @@ export interface IHeapSnapshot {
     /**
      * Search for the heap and check if there is any JS object instance with
      * a marker tagged by {@link tagObject}.
+     *
+     * The `tagObject` API does not modify the object instance in any way
+     * (e.g., no additional or hidden properties added to the tagged object).
+     *
      * @param tag marker name on the object instances tagged by {@link tagObject}
      * @returns returns `true` if there is at least one such object in the heap
      *
@@ -813,75 +940,601 @@ export interface IHeapSnapshot {
     /** @internal */
     clearShortestPathInfo(): void;
 }
+/**
+ * An `IHeapLocation` instance contains a source location information
+ * associated with a JS heap object.
+ * 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 `IHeapLocation` instance
+ *
+ * * **Examples**: V8 or hermes heap snapshot can be parsed by the
+ * {@link getHeapFromFile} API.
+ *
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapNode, IHeapLocation} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *
+ *   // iterate over each node (heap object)
+ *   heap.nodes.forEach((node: IHeapNode, i: number) => {
+ *     const location: Nullable<IHeapLocation> = node.location;
+ *     if (location) {
+ *       // use the location API here
+ *       location.line;
+ *       // ...
+ *     }
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapLocation {
+    /**
+     * get the {@link IHeapSnapshot} containing this location instance
+     */
     snapshot: IHeapSnapshot;
+    /**
+     * get the script ID of the source file
+     */
     script_id: number;
+    /**
+     * get the line number
+     */
     line: number;
+    /**
+     * get the column number
+     */
     column: number;
 }
+/** @internal */
 export interface IHeapEdgeBasic {
+    /**
+     * name of the JS reference. If this is a reference to an array element
+     * or internal table element, it is an numeric index
+     */
     name_or_index: number | string;
+    /**
+     * type of the JS reference, all types:
+     * `context`, `element`, `property`, `internal`, `hidden`, `shortcut`, `weak`
+     */
     type: string;
 }
+/**
+ * An `IHeapEdge` instance represents a JS reference 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 `IHeapEdge` instance
+ *
+ * * **Examples**: V8 or hermes heap snapshot can be parsed by the
+ * {@link getHeapFromFile} API.
+ *
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapEdge} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *
+ *   // iterate over each edge (JS reference in heap)
+ *   heap.edges.forEach((edge: IHeapEdge, i: number) => {
+ *     // use the heap edge APIs here
+ *     const nameOrIndex = edge.name_or_index;
+ *     // ...
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapEdge extends IHeapEdgeBasic {
+    /**
+     * get the {@link IHeapSnapshot} containing this JS reference
+     */
     snapshot: IHeapSnapshot;
+    /**
+     * index of this JS reference inside the `edge.snapshot.edges` pseudo array
+     */
     edgeIndex: number;
+    /**
+     * if `true`, means this is a reference to an array element
+     * or internal table element (`edge.name_or_index` will return a number),
+     * otherwise this is a reference with a string name (`edge.name_or_index`
+     * will return a string)
+     */
     is_index: boolean;
+    /**
+     * the index of the JS heap object pointed to by this reference
+     */
     to_node: number;
+    /**
+     * returns an {@link IHeapNode} instance representing the JS heap object
+     * pointed to by this reference
+     */
     toNode: IHeapNode;
+    /**
+     * returns an {@link IHeapNode} instance representing the hosting
+     * JS heap object where this reference starts
+     */
     fromNode: IHeapNode;
 }
+/**
+ * A pseudo array containing all heap graph edges (references to heap objects
+ * in heap). A JS heap could contain millions of references, so memlab uses
+ * a pseudo array as the collection of all the heap edges. The pseudo
+ * array provides API to query and traverse all heap references.
+ *
+ * @readonly modifying this pseudo array is not recommended
+ *
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapEdges} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *
+ *   const edges: IHeapEdges = heap.edges;
+ *   edges.length;
+ *   edges.get(0);
+ *   edges.forEach((edge, i) => {
+ *     if (stopIteration) {
+ *       return false;
+ *     }
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapEdges {
+    /**
+     * The total number of edges in heap graph (or JS references in heap
+     * snapshot).
+     */
     length: number;
-    get(index: number): IHeapEdge;
+    /**
+     * get an {@link IHeapEdge} element at the specified index
+     * @param index the index of an element in the pseudo array, the index ranges
+     * from 0 to array length - 1. Notice that this is not the heap node id.
+     * @returns When 0 <= `index` < array.length, this API returns the element
+     * at the specified index, otherwise it returns `null`.
+     */
+    get(index: number): Nullable<IHeapEdge>;
+    /**
+     * Iterate over all array elements and apply the callback
+     * to each element in ascending order of element index.
+     * @param callback the callback does not need to return any value, if
+     * the callback returns `false` when iterating on element at index `i`,
+     * then all elements after `i` won't be iterated.
+     */
     forEach(callback: (edge: IHeapEdge, index: number) => void | boolean): void;
 }
+/** @internal */
 export interface IHeapNodeBasic {
+    /**
+     * 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`
+     */
     type: 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.
+     */
     name: string;
+    /**
+     * unique id of the heap object
+     */
     id: number;
 }
 export declare type EdgeIterationCallback = (edge: IHeapEdge) => Optional<{
     stop: boolean;
 }>;
+/**
+ * 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
+ * {@link getHeapFromFile} API.
+ *
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapNode} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(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;
+ *     // ...
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapNode extends IHeapNodeBasic {
+    /**
+     * get the {@link IHeapSnapshot} containing this heap object
+     */
     snapshot: IHeapSnapshot;
+    /**
+     * * 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`
+     */
     is_detached: boolean;
+    /** @internal */
     detachState: number;
+    /** @internal */
     markAsDetached(): void;
+    /** @internal */
     attributes: 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](https://developer.chrome.com/docs/devtools/memory-problems/memory-101/#object_sizes).
+     */
     self_size: number;
+    /**
+     * The total number of outgoing JS references (including engine-internal,
+     * native, and JS references).
+     */
     edge_count: number;
+    /** @internal */
     trace_node_id: number;
+    /**
+     * Get a JS array containing all outgoing JS references from this heap object
+     * (including engine-internal, native, and JS references).
+     */
     references: IHeapEdge[];
+    /**
+     * Get a JS array containing all incoming JS references pointing to this heap
+     * object (including engine-internal, native, and JS references).
+     */
     referrers: IHeapEdge[];
+    /**
+     * The incoming edge which leads to the parent node
+     * on the shortest path to GC root.
+     */
     pathEdge: IHeapEdge | null;
+    /**
+     * index of this heap object inside the `node.snapshot.nodes` pseudo array
+     */
     nodeIndex: 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](https://developer.chrome.com/docs/devtools/memory-problems/memory-101/#object_sizes).
+     */
     retainedSize: number;
-    dominatorNode: IHeapNode | null;
-    location: IHeapLocation | null;
+    /**
+     * 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](https://developer.chrome.com/docs/devtools/memory-problems/memory-101/#dominators).
+     */
+    dominatorNode: Nullable<IHeapNode>;
+    /**
+     * source location information of this heap object (if it is recorded by
+     * the heap snapshot).
+     */
+    location: Nullable<IHeapLocation>;
+    /** @internal */
     highlight?: boolean;
+    /**
+     * check if this a string node (normal string node, concatenated string node
+     * or sliced string node)
+     */
     isString: boolean;
+    /**
+     * convert to an {@link IHeapStringNode} object if this node is a string node.
+     * The {@link IHeapStringNode} object supports querying the string content
+     * inside the string node.
+     */
     toStringNode(): Nullable<IHeapStringNode>;
+    /**
+     * executes a provided callback once for each JavaScript reference in the
+     * hosting node (or outgoing edges from the node)
+     * @param callback the callback for each outgoing JavaScript reference
+     * @returns this API returns void
+     *
+     * * **Examples**:
+     * ```typescript
+     * 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};
+     * });
+     * ```
+     */
     forEachReference(callback: EdgeIterationCallback): void;
+    /**
+     * executes a provided callback once for each JavaScript reference pointing
+     * to the hosting node (or incoming edges to the node)
+     * @param callback the callback for each incoming JavaScript reference
+     * @returns this API returns void
+     *
+     * * **Examples**:
+     * ```typescript
+     * 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};
+     * });
+     * ```
+     */
     forEachReferrer(callback: EdgeIterationCallback): void;
-    findReference: (predicate: Predicator<IHeapEdge>) => Nullable<IHeapEdge>;
+    /**
+     * 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`
+     * @param predicate the callback for each outgoing JavaScript reference
+     * @returns the first outgoing edge for which the predicate returns `true`,
+     * otherwise returns `null` if no such edge is found.
+     *
+     * * **Examples**:
+     * ```typescript
+     * const reference = node.findAnyReference((edge: IHeapEdge) => {
+     *   // find the outgoing reference with name "ref"
+     *   return edge.name_or_index === 'ref';
+     * });
+     * ```
+     */
+    findAnyReference: (predicate: Predicator<IHeapEdge>) => Nullable<IHeapEdge>;
+    /**
+     * 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`
+     * @param predicate the callback for each incoming JavaScript reference
+     * @returns the first incoming edge for which the predicate returns `true`,
+     * otherwise returns `null` if no such edge is found.
+     *
+     * * **Examples**:
+     * ```typescript
+     * const referrer = node.findAnyReferrer((edge: IHeapEdge) => {
+     *   // find the incoming reference with name "ref"
+     *   return edge.name_or_index === 'ref';
+     * });
+     * ```
+     */
     findAnyReferrer: (predicate: Predicator<IHeapEdge>) => Nullable<IHeapEdge>;
+    /**
+     * executes a provided predicate callback once for each JavaScript reference
+     * pointing to the hosting node (or incoming edges to the node)
+     * @param predicate the callback for each incoming JavaScript reference
+     * @returns 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**:
+     * ```typescript
+     * const referrers = node.findReferrers((edge: IHeapEdge) => {
+     *   // find all the incoming references with name "ref"
+     *   return edge.name_or_index === 'ref';
+     * });
+     * ```
+     */
     findReferrers: (predicate: Predicator<IHeapEdge>) => IHeapEdge[];
+    /**
+     * Given a JS reference's name and type, this API finds an outgoing JS
+     * reference from the hosting node.
+     * @param edgeName the name of the outgoing JavaScript reference
+     * @param edgeType optional parameter specifying the type of the outgoing
+     * JavaScript reference
+     * @returns the outgoing edge that meets the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // find the internal reference to node's hidden class
+     * const reference = node.getReference('map', 'hidden');
+     * ```
+     */
     getReference: (edgeName: string | number, edgeType?: string) => Nullable<IHeapEdge>;
+    /**
+     * 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.
+     * @param edgeName the name of the outgoing JavaScript reference
+     * @param edgeType optional parameter specifying the type of the outgoing
+     * JavaScript reference
+     * @returns the node pointed to by the outgoing reference that meets
+     * the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // find the node's hidden class
+     * const hiddenClassNode = node.getReferenceNode('map', 'hidden');
+     * // this is equivalent to
+     * const hiddenClassNode2 = node.getReference('map', 'hidden')?.toNode;
+     * ```
+     */
     getReferenceNode: (edgeName: string | number, edgeType?: string) => Nullable<IHeapNode>;
+    /**
+     * Given a JS reference's name and type, this API finds an incoming JS
+     * reference pointing to the hosting node.
+     * @param edgeName the name of the incoming JavaScript reference
+     * @param edgeType optional parameter specifying the type of the incoming
+     * JavaScript reference
+     * @returns the incoming edge that meets the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // find one of the JS reference named "ref" pointing to node
+     * const reference = node.getAnyReferrer('ref', 'property');
+     * ```
+     */
     getAnyReferrer: (edgeName: string | number, edgeType?: string) => Nullable<IHeapEdge>;
+    /**
+     * 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.
+     * @param edgeName the name of the incoming JavaScript reference
+     * @param edgeType optional parameter specifying the type of the incoming
+     * JavaScript reference
+     * @returns the node containing the incoming JS reference that meets
+     * the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // 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;
+     * ```
+     */
     getAnyReferrerNode: (edgeName: string | number, edgeType?: string) => Nullable<IHeapNode>;
+    /**
+     * Given a JS reference's name and type, this API finds all the incoming JS
+     * reference pointing to the hosting node.
+     * @param edgeName the name of the incoming JavaScript reference
+     * @param edgeType optional parameter specifying the type of the incoming
+     * JavaScript reference
+     * @returns an array containing all the incoming edges that
+     * meet the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // find all of of the JS reference named "ref" pointing to node
+     * const referrers = node.getReferrers('ref', 'property');
+     * ```
+     */
     getReferrers: (edgeName: string | number, edgeType?: string) => IHeapEdge[];
+    /**
+     * 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.
+     * @param edgeName the name of the incoming JavaScript reference
+     * @param edgeType optional parameter specifying the type of the incoming
+     * JavaScript reference
+     * @returns an array containing the hosting nodes, with each node corresponds
+     * to each incoming JS reference that meets the specification
+     *
+     * * **Examples**:
+     * ```typescript
+     * // 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);
+     * ```
+     */
     getReferrerNodes: (edgeName: string | number, edgeType?: string) => IHeapNode[];
 }
+/**
+ * An `IHeapStringNode` instance represents a JS string 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 `IHeapStringNode` instance
+ *
+ * * **Examples**: V8 or hermes heap snapshot can be parsed by the
+ * {@link getHeapFromFile} API.
+ *
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapNode, IHeapStringNode} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *
+ *   // iterate over each node (heap object)
+ *   heap.nodes.forEach((node: IHeapNode, i: number) => {
+ *     if (node.isString) {
+ *       const stringNode: IheapStringNode = node.toStringNode();
+ *       // get the string value
+ *       stringNode.stringValue;
+ *     }
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapStringNode extends IHeapNode {
+    /**
+     * get the string value of the JS string heap object associated with
+     * this `IHeapStringNode` instance in heap
+     */
     stringValue: string;
 }
+/**
+ * A pseudo array containing all heap graph nodes (JS objects
+ * in heap). A JS heap could contain millions of objects, so memlab uses
+ * a pseudo array as the collection of all the heap nodes. The pseudo
+ * array provides API to query and traverse all heap objects.
+ *
+ * @readonly modifying this pseudo array is not recommended
+ *
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, IHeapNodes} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *
+ *   const nodes: IHeapNodes = heap.nodes;
+ *   nodes.length;
+ *   nodes.get(0);
+ *   nodes.forEach((node, i) => {
+ *     if (stopIteration) {
+ *       return false;
+ *     }
+ *   });
+ * })();
+ * ```
+ */
 export interface IHeapNodes {
+    /**
+     * The total number of nodes in heap graph (or JS objects in heap
+     * snapshot).
+     */
     length: number;
-    get(index: number): IHeapNode;
+    /**
+     * get an {@link IHeapNode} element at the specified index
+     * @param index the index of an element in the pseudo array, the index ranges
+     * from 0 to array length - 1. Notice that this is not the heap node id.
+     * @returns When 0 <= `index` < array.length, this API returns the element
+     * at the specified index, otherwise it returns `null`.
+     */
+    get(index: number): Nullable<IHeapNode>;
+    /**
+     * Iterate over all array elements and apply the callback
+     * to each element in ascending order of element index.
+     * @param callback the callback does not need to return any value, if
+     * the callback returns `false` when iterating on element at index `i`,
+     * then all elements after `i` won't be iterated.
+     */
     forEach(callback: (node: IHeapNode, index: number) => void | boolean): void;
+    /** @internal */
     forEachTraceable(callback: (node: IHeapNode, index: number) => void | boolean): void;
 }
 /** @internal */

package/dist/lib/Utils.js

@@ -581,14 +581,14 @@ function getEdgeByNameAndType(node, edgeName, type) {
     if (!node) {
         return null;
     }
-    return node.findReference((edge) => edge.name_or_index === edgeName &&
+    return node.findAnyReference((edge) => edge.name_or_index === edgeName &&
         (type === undefined || edge.type === type));
 }
 function getEdgeStartsWithName(node, prefix) {
     if (!node) {
         return null;
     }
-    return node.findReference(edge => typeof edge.name_or_index === 'string' &&
+    return node.findAnyReference(edge => typeof edge.name_or_index === 'string' &&
         edge.name_or_index.startsWith(prefix));
 }
 function isStringNode(node) {

package/dist/lib/heap-data/HeapNode.d.ts

@@ -31,7 +31,7 @@ export default class HeapNode implements IHeapNode {
     get trace_node_id(): number;
     get references(): HeapEdge[];
     forEachReference(callback: EdgeIterationCallback): void;
-    findReference(predicate: Predicator<IHeapEdge>): Nullable<IHeapEdge>;
+    findAnyReference(predicate: Predicator<IHeapEdge>): Nullable<IHeapEdge>;
     findAnyReferrer(predicate: Predicator<IHeapEdge>): Nullable<IHeapEdge>;
     findReferrers(predicate: Predicator<IHeapEdge>): IHeapEdge[];
     get referrers(): HeapEdge[];

package/dist/lib/heap-data/HeapNode.js

@@ -131,7 +131,7 @@ class HeapNode {
             }
         }
     }
-    findReference(predicate) {
+    findAnyReference(predicate) {
         let found = null;
         this.forEachReference((edge) => {
             if (predicate(edge)) {

package/dist/lib/heap-data/HeapSnapshot.js

@@ -82,6 +82,9 @@ class HeapSnapshot {
         this.nodes = {
             length: self._nodeCount,
             get(idx) {
+                if (idx < 0 || idx >= self._nodeCount) {
+                    return null;
+                }
                 return new HeapNode_1.default(self, idx);
             },
             forEach(cb) {
@@ -109,6 +112,9 @@ class HeapSnapshot {
         this.edges = {
             length: self._edgeCount,
             get(idx) {
+                if (idx < 0 || idx >= self._edgeCount) {
+                    return null;
+                }
                 return new HeapEdge_1.default(self, idx);
             },
             forEach(cb) {
@@ -180,7 +186,7 @@ class HeapSnapshot {
             return false;
         }
         // check if the table has any weak reference to any object
-        const ref = table.findReference((edge) => edge.type === 'weak' && edge.toNode.name !== 'system / Oddball');
+        const ref = table.findAnyReference((edge) => edge.type === 'weak' && edge.toNode.name !== 'system / Oddball');
         return ref != null;
     }
     getNodeById(id) {

package/dist/paths/TraceFinder.js

@@ -159,7 +159,8 @@ class TraceFinder {
                     if (!Utils_1.default.isEssentialEdge(nodeIndex, edgeType, rootNodeIndex)) {
                         continue;
                     }
-                    const childNodeIndex = forwardEdges.get(edgeIndex).toNode.nodeIndex;
+                    const childNodeIndex = forwardEdges.get(edgeIndex)
+                        .toNode.nodeIndex;
                     if (visited[childNodeIndex]) {
                         continue;
                     }
@@ -278,7 +279,8 @@ class TraceFinder {
             if (!Utils_1.default.isEssentialEdge(ROOT_NODE_INDEX, edgeType, ROOT_NODE_INDEX)) {
                 continue;
             }
-            const childNodeIndex = forwardEdges.get(edgeIndex).toNode.nodeIndex;
+            const childNodeIndex = forwardEdges.get(edgeIndex).toNode
+                .nodeIndex;
             nodesWithOutdatedDominatorInfo[nodeIndex2PostOrderIndex[childNodeIndex]] = 1;
         }
         // now iterate through all nodes in the heap

package/dist/trace-cluster/TraceElement.d.ts

@@ -34,7 +34,7 @@ export declare class NodeRecord implements IHeapNode {
     get referrers(): IHeapEdge[];
     toStringNode(): IHeapStringNode;
     forEachReferrer(_callback: EdgeIterationCallback): void;
-    findReference(): Nullable<IHeapEdge>;
+    findAnyReference(): Nullable<IHeapEdge>;
     findAnyReferrer(): Nullable<IHeapEdge>;
     findReferrers(): IHeapEdge[];
     set pathEdge(r: IHeapEdge);

package/dist/trace-cluster/TraceElement.js

@@ -70,8 +70,8 @@ class NodeRecord {
     _callback) {
         throw new Error('NodeRecord.forEachReferrer is not implemented');
     }
-    findReference() {
-        throw new Error('NodeRecord.findReference is not implemented');
+    findAnyReference() {
+        throw new Error('NodeRecord.findAnyReference is not implemented');
     }
     findAnyReferrer() {
         throw new Error('NodeRecord.findAnyReferrer is not implemented');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/core",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "license": "MIT",
   "description": "memlab core libraries",
   "author": "Liang Gong <lgong@fb.com>",