@memlab/core 1.1.2 → 1.1.5

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/index.d.ts

@@ -7,6 +7,8 @@
  * @emails oncall+ws_labs
  * @format
  */
+/** @internal */
+export declare function registerPackage(): Promise<void>;
 export * from './lib/Types';
 /** @internal */
 export { default as config } from './lib/Config';
@@ -42,5 +44,7 @@ export { default as leakClusterLogger } from './logger/LeakClusterLogger';
 export { default as NormalizedTrace } from './trace-cluster/TraceBucket';
 /** @internal */
 export { default as EvaluationMetric } from './trace-cluster/EvalutationMetric';
+/** @internal */
+export * from './lib/PackageInfoLoader';
 export * from './lib/NodeHeap';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,11 +22,29 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = void 0;
+exports.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = exports.registerPackage = void 0;
+const path_1 = __importDefault(require("path"));
+const PackageInfoLoader_1 = require("./lib/PackageInfoLoader");
+/** @internal */
+function registerPackage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return PackageInfoLoader_1.PackageInfoLoader.registerPackage(path_1.default.join(__dirname, '..'));
+    });
+}
+exports.registerPackage = registerPackage;
 __exportStar(require("./lib/Types"), exports);
 /** @internal */
 var Config_1 = require("./lib/Config");
@@ -76,4 +94,6 @@ Object.defineProperty(exports, "NormalizedTrace", { enumerable: true, get: funct
 /** @internal */
 var EvalutationMetric_1 = require("./trace-cluster/EvalutationMetric");
 Object.defineProperty(exports, "EvaluationMetric", { enumerable: true, get: function () { return __importDefault(EvalutationMetric_1).default; } });
+/** @internal */
+__exportStar(require("./lib/PackageInfoLoader"), exports);
 __exportStar(require("./lib/NodeHeap"), exports);

package/dist/lib/Config.d.ts

@@ -8,7 +8,7 @@
  * @format
  */
 import type { LaunchOptions, Permission } from 'puppeteer';
-import type { AnyFunction, AnyValue, IClusterStrategy, IRunningMode, IScenario, Nullable, Optional, QuickExperiment, ILeakFilter } from './Types';
+import type { AnyFunction, AnyValue, IClusterStrategy, IRunningMode, IScenario, Nullable, Optional, QuickExperiment, ILeakFilter, IPackageInfo } from './Types';
 interface BrowserLaunchArgumentOptions {
     headless?: boolean;
     userDataDir?: string;
@@ -44,14 +44,19 @@ export declare enum ErrorHandling {
 }
 /** @internal */
 export declare class MemLabConfig {
-    snapshotHasDetachedness: boolean;
-    specifiedEngine: boolean;
-    verbose: boolean;
-    jsEngine: string;
     _reportLeaksInTimers: boolean;
     _deviceManualOverridden: boolean;
     _timerNodes: string[];
     _timerEdges: string[];
+    _isFullRun: boolean;
+    _scenario: Optional<IScenario>;
+    _isHeadfulBrowser: boolean;
+    _browser: string;
+    _packageInfo: IPackageInfo[];
+    snapshotHasDetachedness: boolean;
+    specifiedEngine: boolean;
+    verbose: boolean;
+    jsEngine: string;
     targetApp: string;
     targetTab: string;
     analysisMode: string;
@@ -94,7 +99,6 @@ export declare class MemLabConfig {
     puppeteerConfig: LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions;
     openDevtoolsConsole: boolean;
     emulateDevice: Nullable<Device>;
-    _browser: string;
     addEnableGK: Set<string>;
     addDisableGK: Set<string>;
     qes: QuickExperiment[];
@@ -169,8 +173,6 @@ export declare class MemLabConfig {
     oversizeObjectAsLeak: boolean;
     oversizeThreshold: number;
     clusterRetainedSizeThreshold: number;
-    _isFullRun: boolean;
-    _scenario: Optional<IScenario>;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
     muteConsole: boolean;
@@ -192,6 +194,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,
@@ -95,6 +97,8 @@ class MemLabConfig {
         this.jsEngine = Constant_1.default.defaultEngine;
         // the default browser (Chromium)
         this._browser = 'chrome';
+        // a list of package information
+        this._packageInfo = [];
         // a set of additional GKs to be enabled
         this.addEnableGK = new Set();
         // a set of additional GKs to be disabled
@@ -358,6 +362,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/PackageInfoLoader.d.ts

@@ -0,0 +1,7 @@
+/** @internal */
+export declare class PackageInfoLoader {
+    private static registeredPackages;
+    private static loadFrom;
+    static registerPackage(packageDirectory: string): Promise<void>;
+}
+//# sourceMappingURL=PackageInfoLoader.d.ts.map

package/dist/lib/PackageInfoLoader.js

@@ -0,0 +1,66 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageInfoLoader = void 0;
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const Config_1 = __importDefault(require("./Config"));
+const Utils_1 = __importDefault(require("./Utils"));
+/** @internal */
+class PackageInfoLoader {
+    static loadFrom(packageDirectory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let exists = yield fs_extra_1.default.pathExists(packageDirectory);
+            if (!exists) {
+                throw Utils_1.default.haltOrThrow(`package directory doesn't exist: ${packageDirectory}`);
+            }
+            let packageJSONFile = path_1.default.join(packageDirectory, 'package-oss.json');
+            exists = yield fs_extra_1.default.pathExists(packageJSONFile);
+            if (!exists) {
+                packageJSONFile = path_1.default.join(packageDirectory, 'package.json');
+            }
+            exists = yield fs_extra_1.default.pathExists(packageJSONFile);
+            if (!exists) {
+                throw Utils_1.default.haltOrThrow(`package.json doesn't exist: ${packageJSONFile}`);
+            }
+            try {
+                const metaData = yield fs_extra_1.default.readJSON(packageJSONFile, 'UTF-8');
+                return Object.assign(Object.assign({}, metaData), { packageLocation: packageDirectory });
+            }
+            catch (ex) {
+                throw Utils_1.default.haltOrThrow(Utils_1.default.getError(ex));
+            }
+        });
+    }
+    static registerPackage(packageDirectory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!PackageInfoLoader.registeredPackages.has(packageDirectory)) {
+                PackageInfoLoader.registeredPackages.add(packageDirectory);
+                const packageInfo = yield PackageInfoLoader.loadFrom(packageDirectory);
+                Config_1.default._packageInfo.push(packageInfo);
+            }
+        });
+    }
+}
+exports.PackageInfoLoader = PackageInfoLoader;
+PackageInfoLoader.registeredPackages = new Set();

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

@@ -89,6 +89,7 @@ export declare type CLIArgs = {
 export declare type Cookies = Array<{
     name: string;
     value: string;
+    domain?: string;
 }>;
 /** @internal */
 export interface IE2EScenarioSynthesizer {
@@ -96,7 +97,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[];
@@ -119,6 +120,12 @@ export interface E2EScenarioSynthesizerConstructor {
     new (config: Config): IE2EScenarioSynthesizer;
 }
 /** @internal */
+export interface IPackageInfo {
+    name: string;
+    version: string;
+    packageLocation?: string;
+}
+/** @internal */
 export interface IRunningMode {
     setConfig(config: Config): void;
     beforeRunning(visitPlan: IE2EScenarioVisitPlan): void;
@@ -143,16 +150,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`).
+ *
+ * ```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.
  *
- * let map = Object.create(null);
+ * ```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 +208,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 +331,9 @@ export declare type InteractionsCallback = (page: Page, args?: OperationArgs) =>
  *   url: () => 'https://www.npmjs.com/',
  *   action: async () => ... ,
  *   back: async () => ... ,
+ *   cookies: () => ... , // optional
+ *   repeat: () => ... , // optional
+ *   ...
  * };
  * ```
  *
@@ -230,6 +347,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,20 +363,30 @@ 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. If no `domain` field is specified, memlab will try
+     * to fill in a domain based on the `url` callback.
+     * For example, when the `domain` field is absent,
+     * memlab will auto fill in `.facebook.com` as domain base
+     * on the initial page load's url: `https://www.facebook.com/`.
+     *
      * @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'},
      *     // ...
      *   ],
      * };
+     *
+     * module.exports = scenario;
      * ```
      */
     cookies?: () => Cookies;
@@ -269,6 +399,8 @@ export interface IScenario {
      * const scenario = {
      *   url: () => 'https://www.npmjs.com/',
      * };
+     *
+     * module.exports = scenario;
      * ```
      * If a test scenario only specifies the `url` callback (without the `action`
      * callback), memlab will try to detect memory leaks from the initial page
@@ -297,6 +429,8 @@ export interface IScenario {
      *     await page.click('a[href="/back"]');
      *   },
      * }
+     *
+     * module.exports = scenario;
      * ```
      * Note: always clean up external puppeteer references to JS objects
      *       in the browser context.
@@ -314,6 +448,8 @@ export interface IScenario {
      *   },
      *   back: async (page) => ... ,
      * }
+     *
+     * module.exports = scenario;
      ```
      */
     action?: InteractionsCallback;
@@ -321,6 +457,10 @@ export interface IScenario {
      * `back` is the callback function that specifies how memlab should
      * back/revert the `action` callback. Think of it as an undo action.
      *
+     * * **Parameters**:
+     *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+     *     object, which provides APIs to interact with the web browser
+     *
      * * **Examples**:
      * ```typescript
      * const scenario = {
@@ -354,7 +494,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 +530,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 +555,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
@@ -545,6 +685,10 @@ export interface IDataBuilder {
 /**
  * Callback function to provide if the page is loaded.
  * @param page - puppeteer's [Page](https://pptr.dev/api/puppeteer.page/) object.
+ * @returns a boolean value, if it returns `true`, memlab will consider
+ * the navigation completes, if it returns `false`, memlab will keep calling
+ * this callback until it returns `true`. This is an async callback, you can
+ * also `await` and returns `true` until some async logic is resolved.
  */
 export declare type CheckPageLoadCallback = (page: Page) => Promise<boolean>;
 /** @internal */
@@ -606,6 +750,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 +929,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 +967,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.5",
   "license": "MIT",
   "description": "memlab core libraries",
   "author": "Liang Gong <lgong@fb.com>",