@memlab/core 1.0.9 → 1.1.2

package/dist/__tests__/parser/HeapParser.test.js

@@ -36,7 +36,7 @@ test('Capture inserted object', () => __awaiter(void 0, void 0, void 0, function
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const injected = new TestObject();
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithClassName('TestObject')).toBe(true);
 }), timeout);
 test('Does not capture transcient object', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -49,6 +49,6 @@ test('Does not capture transcient object', () => __awaiter(void 0, void 0, void
     let injected = new TestObject();
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     injected = null;
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithClassName('TestObject')).toBe(false);
 }), timeout);

package/dist/__tests__/parser/NodeHeap.test.js

@@ -30,7 +30,7 @@ const timeout = 5 * 60 * 1000;
 test('Capture current node heap snapshot', () => __awaiter(void 0, void 0, void 0, function* () {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = { 'memlab-test-heap-property': 'memlab-test-heap-value' };
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithPropertyName('memlab-test-heap-property')).toBe(true);
 }), timeout);
 test('Nullified Object should not exist in heap', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -39,7 +39,7 @@ test('Nullified Object should not exist in heap', () => __awaiter(void 0, void 0
     };
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     object = null;
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithPropertyName('memlab-test-heap-property')).toBe(false);
 }), timeout);
 test('Strongly referenced object should exist in heap', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -59,7 +59,7 @@ test('Strongly referenced object should exist in heap', () => __awaiter(void 0,
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = buildTest();
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithClassName('TestClass1')).toBe(true);
     expect(heap.hasObjectWithClassName('TestClass2')).toBe(true);
 }), timeout);
@@ -80,7 +80,7 @@ test('Weakly referenced object should not exist in heap', () => __awaiter(void 0
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = buildTest();
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithClassName('TestClass3')).toBe(true);
     expect(heap.hasObjectWithClassName('TestClass4')).toBe(false);
 }), timeout);
@@ -90,7 +90,7 @@ test('Check annotated objects', () => __awaiter(void 0, void 0, void 0, function
     (0, NodeHeap_1.tagObject)(o1, 'memlab-mark-1');
     (0, NodeHeap_1.tagObject)(o2, 'memlab-mark-2');
     o2 = null;
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
     expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
 }), timeout);

package/dist/__tests__/parser/StringNode.test.js

@@ -41,7 +41,7 @@ test('String heap object APIs work', () => __awaiter(void 0, void 0, void 0, fun
     injected.complexConcatString += 'value_';
     injected.complexConcatString += 123;
     injected.complexConcatString += '_suffix';
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     const testObject = heap.getAnyObjectWithClassName('TestObject');
     expect(testObject).not.toBe(null);
     // testObject.originalString === 'test'

package/dist/__tests__/parser/traverse/HeapNodeTraverse.test.js

@@ -74,7 +74,7 @@ test('Check getReference and getReferenceNode', () => __awaiter(void 0, void 0,
         });
         return detected;
     };
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(checker(heap)).toBe(true);
 }), timeout);
 test('Check getReferrers and getReferrerNodes', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -135,6 +135,6 @@ test('Check getReferrers and getReferrerNodes', () => __awaiter(void 0, void 0,
         }
         return true;
     };
-    const heap = yield (0, NodeHeap_1.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(checker(heap)).toBe(true);
 }), timeout);

package/dist/lib/Config.d.ts

@@ -139,6 +139,7 @@ export declare class MemLabConfig {
     waitAfterOperation: number;
     waitAfterScrolling: number;
     waitAfterTyping: number;
+    waitForNetworkInDefaultScenario: number;
     stressTestRepeat: number;
     avoidLeakWithoutDetachedElements: boolean;
     hideBrowserLeak: boolean;

package/dist/lib/Config.js

@@ -192,6 +192,8 @@ class MemLabConfig {
         this.waitAfterScrolling = 5000;
         // extra delay after typing
         this.waitAfterTyping = 1000;
+        // page load checker: default wait for network idle in scenario test
+        this.waitForNetworkInDefaultScenario = 10000;
         // default repeat for stress testing
         this.stressTestRepeat = 5;
         // only show leaks with detached HTML elements

package/dist/lib/Console.d.ts

@@ -61,6 +61,7 @@ declare class MemLabConsole {
     progress(cur: number, total: number, options?: {
         message?: string;
     }): void;
+    flush(): void;
 }
 declare const _default: MemLabConsole;
 export default _default;

package/dist/lib/Console.js

@@ -340,5 +340,8 @@ class MemLabConsole {
         const progress = `${message}: |${bar}| ${percent}/100`;
         this.overwrite(progress, { level: 'top' });
     }
+    flush() {
+        this.clearPrevOverwriteMsg();
+    }
 }
 exports.default = MemLabConsole.getInstance();

package/dist/lib/FileManager.d.ts

@@ -43,6 +43,8 @@ export declare class FileManager {
     getAllFilesInDir(dir: string): string[];
     getDataOutDir(options?: FileOption): string;
     getCoreProjectBaseDir(): string;
+    getMonoRepoDir(): string;
+    getDocDir(): string;
     getReportOutDir(options?: FileOption): string;
     getPreviewReportDir(options?: FileOption): string;
     getLeakSummaryFile(options?: FileOption): string;

package/dist/lib/FileManager.js

@@ -133,6 +133,12 @@ class FileManager {
     getCoreProjectBaseDir() {
         return path_1.default.join(__dirname, '..', '..');
     }
+    getMonoRepoDir() {
+        return path_1.default.join(this.getCoreProjectBaseDir(), '..', '..');
+    }
+    getDocDir() {
+        return path_1.default.join(this.getMonoRepoDir(), 'website', 'docs');
+    }
     getReportOutDir(options = {}) {
         return path_1.default.join(this.getPersistDataDir(options), 'reports');
     }

package/dist/lib/NodeHeap.d.ts

@@ -7,10 +7,69 @@
  * @emails oncall+ws_labs
  * @format
  */
-import type { AnyValue, IHeapSnapshot } from './Types';
-declare type AnyObject = Record<AnyValue, AnyValue>;
-export declare function tagObject(o: AnyObject, tag: string): AnyObject;
+import type { IHeapSnapshot } from './Types';
+/**
+ * Tags a string marker to an object instance, which can later be checked by
+ * {@link hasObjectWithTag}. This API does not modify the object instance in
+ * any way (e.g., no additional or hidden properties added to the tagged
+ * object).
+ *
+ * @param o specify the object instance you want to tag, you cannot tag a
+ * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+ * @param tag marker name to tag on the object instance
+ * @returns returns the tagged object instance (same reference as
+ * the input argument `o`)
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
+ * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ *
+ * test('memory test', async () => {
+ *   config.muteConsole = true;
+ *   const o1: AnyValue = {};
+ *   let o2: AnyValue = {};
+ *
+ *   // tag o1 with marker: "memlab-mark-1", does not modify o1 in any way
+ *   tagObject(o1, 'memlab-mark-1');
+ *   // tag o2 with marker: "memlab-mark-2", does not modify o2 in any way
+ *   tagObject(o2, 'memlab-mark-2');
+ *
+ *   o2 = null;
+ *
+ *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *
+ *   // expect object with marker "memlab-mark-1" exists
+ *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+ *
+ *   // expect object with marker "memlab-mark-2" can be GCed
+ *   expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+ *
+ * }, 30000);
+ * ```
+ */
+export declare function tagObject<T extends object>(o: T, tag: string): T;
 export declare function dumpNodeHeapSnapshot(): string;
-export declare function getCurrentNodeHeap(): Promise<IHeapSnapshot>;
-export {};
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. Notice that
+ * this API does not calculate some heap analysis meta data
+ * for heap analysis. But this also means faster heap parsing.
+ *
+ * @returns heap representation without heap analysis meta data.
+ *
+ * If you need to get the heap snapshot with heap analysis meta data
+ * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
+ * for example:
+ * ```typescript
+ * import type {IHeapSnapshot} 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);
+ * })();
+ * ```
+ */
+export declare function getNodeInnocentHeap(): Promise<IHeapSnapshot>;
 //# sourceMappingURL=NodeHeap.d.ts.map

package/dist/lib/NodeHeap.js

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentNodeHeap = exports.dumpNodeHeapSnapshot = exports.tagObject = void 0;
+exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.tagObject = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const v8_1 = __importDefault(require("v8"));
@@ -33,6 +33,45 @@ class MemLabTaggedStore {
     }
 }
 const store = new MemLabTaggedStore();
+/**
+ * Tags a string marker to an object instance, which can later be checked by
+ * {@link hasObjectWithTag}. This API does not modify the object instance in
+ * any way (e.g., no additional or hidden properties added to the tagged
+ * object).
+ *
+ * @param o specify the object instance you want to tag, you cannot tag a
+ * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+ * @param tag marker name to tag on the object instance
+ * @returns returns the tagged object instance (same reference as
+ * the input argument `o`)
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
+ * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ *
+ * test('memory test', async () => {
+ *   config.muteConsole = true;
+ *   const o1: AnyValue = {};
+ *   let o2: AnyValue = {};
+ *
+ *   // tag o1 with marker: "memlab-mark-1", does not modify o1 in any way
+ *   tagObject(o1, 'memlab-mark-1');
+ *   // tag o2 with marker: "memlab-mark-2", does not modify o2 in any way
+ *   tagObject(o2, 'memlab-mark-2');
+ *
+ *   o2 = null;
+ *
+ *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *
+ *   // expect object with marker "memlab-mark-1" exists
+ *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+ *
+ *   // expect object with marker "memlab-mark-2" can be GCed
+ *   expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+ *
+ * }, 30000);
+ * ```
+ */
 function tagObject(o, tag) {
     if (!store.taggedObjects[tag]) {
         store.taggedObjects[tag] = new WeakSet();
@@ -47,7 +86,29 @@ function dumpNodeHeapSnapshot() {
     return file;
 }
 exports.dumpNodeHeapSnapshot = dumpNodeHeapSnapshot;
-function getCurrentNodeHeap() {
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. Notice that
+ * this API does not calculate some heap analysis meta data
+ * for heap analysis. But this also means faster heap parsing.
+ *
+ * @returns heap representation without heap analysis meta data.
+ *
+ * If you need to get the heap snapshot with heap analysis meta data
+ * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
+ * for example:
+ * ```typescript
+ * import type {IHeapSnapshot} 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);
+ * })();
+ * ```
+ */
+function getNodeInnocentHeap() {
     return __awaiter(this, void 0, void 0, function* () {
         const file = dumpNodeHeapSnapshot();
         const snapshot = yield Utils_1.default.getSnapshotFromFile(file, {
@@ -59,4 +120,4 @@ function getCurrentNodeHeap() {
         return snapshot;
     });
 }
-exports.getCurrentNodeHeap = getCurrentNodeHeap;
+exports.getNodeInnocentHeap = getNodeInnocentHeap;

package/dist/lib/Types.d.ts

@@ -10,6 +10,7 @@
 import { ParsedArgs } from 'minimist';
 import type { LaunchOptions, Page } from 'puppeteer';
 import type { ErrorHandling, MemLabConfig } from './Config';
+/** @internal */
 export declare type AnyValue = any;
 /** @internal */
 export declare type RecordValue = string | number | boolean | null | RecordValue[] | {
@@ -141,23 +142,319 @@ export declare type QuickExperiment = {
     experiment: string;
     group: string;
 };
+/**
+ * The type for defining custom leak-filtering logic.
+ * * **Examples**:
+ * ```typescript
+ * const scenario = {
+ *
+ * };
+ *
+ * let map = Object.create(null);
+ * const beforeLeakFilter = (snapshot: IHeapSnapshot, _leakedNodeIds: HeapNodeIdSet): void => {
+ *   map = initializeMapUsingSnapshot(snapshot);
+ * };
+ *
+ * // duplicated string with size > 1KB as memory leak
+ * const leakFilter = (node: IHeapNode): boolean => {
+ *   if (node.type !== 'string' || node.retainedSize < 1000) {
+ *     return false;
+ *   }
+ *   const str = utils.getStringNodeValue(node);
+ *   return map[str] > 1;
+ * };
+ *
+ * export default {beforeLeakFilter, leakFilter};
+ * ```
+ */
 export interface ILeakFilter {
     beforeLeakFilter?: InitLeakFilterCallback;
     leakFilter: LeakFilterCallback;
 }
+/**
+ * Lifecycle function callback that is invoked initially once before calling any
+ * leak filter function.
+ *
+ * @param snaphost - heap snapshot see {@link IHeapSnapshot}
+ * @param leakedNodeIds - the set of leaked object (node) ids.
+ */
 export declare type InitLeakFilterCallback = (snapshot: IHeapSnapshot, leakedNodeIds: HeapNodeIdSet) => void;
+/**
+ * Callback that can be used to define a logic to filter the
+ * leaked objects. The callback is only called for every node
+ * allocated but not released from the target interaction
+ * in the heap snapshot.
+ *
+ * @param node - the node that is kept alive in the memory in the heap snapshot
+ * @param snapshot - the snapshot of target interaction
+ * @param leakedNodeIds - the set of leaked node ids
+ *
+ * @returns the value indicating whether the given node in the snapshot
+ * should be considered as leaked.
+ * * **Examples**:
+ * ```javascript
+ * // any node in the heap snapshot that is greater than 1MB
+ * function leakFilter(node, _snapshot, _leakedNodeIds) {
+ *  return node.retainedSize > 1000000;
+ * };
+ * ```
+ */
 export declare type LeakFilterCallback = (node: IHeapNode, snapshot: IHeapSnapshot, leakedNodeIds: HeapNodeIdSet) => boolean;
+/**
+ * The callback defines browser interactions which are
+ * used by memlab to interact with the web app under test.
+ */
 export declare type InteractionsCallback = (page: Page, args?: OperationArgs) => Promise<void>;
+/**
+ * Test scenario specifies how you want a E2E test to interact with a web browser.
+ * The test scenario can be saved as a `.js` file and passed to the `memlab
+ * run --scenario` command:
+ * ```javascript
+ * // save as test.js and use in terminal:
+ * // $ memlab run --scenario test.js
+ *
+ * module.exports = {
+ *   url: () => 'https://www.npmjs.com/',
+ *   action: async () => ... ,
+ *   back: async () => ... ,
+ * };
+ * ```
+ *
+ * The test scenario instance can also be passed to the
+ * [`run` API](../modules/api_src#run) exported by `@memlab/api`.
+ * ```typescript
+ * const {run} = require('@memlab/api');
+ *
+ * (async function () {
+ *   const scenario = {
+ *     url: () => 'https://www.facebook.com',
+ *     action: async () => ... ,
+ *     back: async () => ... ,
+ *   };
+ *   const leaks = await run({scenario});
+ * })();
+ * ```
+ */
 export interface IScenario {
+    /** @internal */
     name?: () => string;
+    /** @internal */
     app?: () => string;
+    /**
+     * 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.
+     * @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..."},
+     *     // ...
+     *   ],
+     * };
+     * ```
+     */
     cookies?: () => Cookies;
+    /**
+     * String value of the initial url of the page.
+     *
+     * @returns the string value of the initial url
+     * * **Examples**:
+     * ```typescript
+     * const scenario = {
+     *   url: () => 'https://www.npmjs.com/',
+     * };
+     * ```
+     * If a test scenario only specifies the `url` callback (without the `action`
+     * callback), memlab will try to detect memory leaks from the initial page
+     * load. All objects allocated by the initial page load will be candidates
+     * for memory leak filtering.
+     */
     url: () => string;
+    /**
+     * `action` is the callback function that defines the interaction
+     * where you want to trigger memory leaks after the initial page load.
+     * All JS objects in browser allocated by the browser interactions triggered
+     * from the `action` callback will be candidates for memory leak filtering.
+     *
+     * * **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 = {
+     *   url: () => 'https://www.npmjs.com/',
+     *   action: async (page) => {
+     *     await page.click('a[href="/link"]');
+     *   },
+     *   back: async (page) => {
+     *     await page.click('a[href="/back"]');
+     *   },
+     * }
+     * ```
+     * Note: always clean up external puppeteer references to JS objects
+     *       in the browser context.
+     * ```typescript
+     * const scenario = {
+     *   url: () => 'https://www.npmjs.com/',
+     *   action: async (page) => {
+     *     const elements = await page.$x("//button[contains(., 'Text in Button')]");
+     *     const [button] = elements;
+     *     if (button) {
+     *       await button.click();
+     *     }
+     *     // dispose external references to JS objects in browser context
+     *     await promise.all(elements.map(e => e.dispose()));
+     *   },
+     *   back: async (page) => ... ,
+     * }
+     ```
+     */
     action?: InteractionsCallback;
+    /**
+     * `back` is the callback function that specifies how memlab should
+     * back/revert the `action` callback. Think of it as an undo action.
+     *
+     * * **Examples**:
+     * ```typescript
+     * const scenario = {
+     *   url: () => 'https://www.npmjs.com/',
+     *   action: async (page) => {
+     *     await page.click('a[href="/link"]');
+     *   },
+     *   back: async (page) => {
+     *     await page.click('a[href="/back"]');
+     *   },
+     * }
+     * ```
+     * Check out [this page](/docs/how-memlab-works) on why
+     * memlab needs to undo/revert the `action` callback.
+     */
     back?: InteractionsCallback;
+    /**
+     * Specifies how many **extra** `action` and `back` actions performed by memlab.
+     * * **Examples**:
+     * ```typescript
+     * module.exports = {
+     *   url: () => ... ,
+     *   action: async (page) => ... ,
+     *   back: async (page) => ... ,
+     *   // browser interaction: two additional [ action -> back ]
+     *   // init-load -> action -> back -> action -> back -> action -> back
+     *   repeat: () => 2,
+     * };
+     * ```
+     */
     repeat?: () => number;
+    /**
+     * Optional callback function that checks if the web page is loaded
+     * after for initial page loading and subsequent browser interactions.
+     *
+     * If this callback is not provided, memlab by default
+     * considers a navigation to be finished when there are no network
+     * connections for at least 500ms.
+     *
+     * * **Parameters**:
+     *   * page: `Page` | the puppeteer [`Page`](https://pptr.dev/api/puppeteer.page)
+     *     object, which provides APIs to interact with the web browser
+     * * **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.
+     * * **Examples**:
+     * ```typescript
+     * module.exports = {
+     *   url: () => ... ,
+     *   action: async (page) => ... ,
+     *   back: async (page) => ... ,
+     *   isPageLoaded: async (page) => {
+     *     await page.waitForNavigation({
+     *       // consider navigation to be finished when there are
+     *       // no more than 2 network connections for at least 500 ms.
+     *       waitUntil: 'networkidle2',
+     *       // Maximum navigation time in milliseconds
+     *       timeout: 5000,
+     *     });
+     *     return true;
+     *   },
+     * };
+     * ```
+     */
     isPageLoaded?: CheckPageLoadCallback;
+    /**
+     * 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
+     * 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 = {
+     *   url: () => ... ,
+     *   action: async (page) => ... ,
+     *   back: async (page) => ... ,
+     *   beforeLeakFilter: (snapshot, leakedNodeIds) {
+     *     // initialize some data stores
+     *   },
+     * };
+     * ```
+     */
     beforeLeakFilter?: InitLeakFilterCallback;
+    /**
+     * This callback that 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.
+     *
+     * * **Examples**:
+     * ```typescript
+     * module.exports = {
+     *   url: () => ... ,
+     *   action: async (page) => ... ,
+     *   back: async (page) => ... ,
+     *   leakFilter(node, snapshot, leakedNodeIds) {
+     *     // any unreleased node (JS heap object) with 1MB+
+     *     // retained size is considered a memory leak
+     *     return node.retainedSize > 1000000;
+     *   },
+     * };
+     * ```
+     */
     leakFilter?: LeakFilterCallback;
 }
 /** @internal */
@@ -245,7 +542,10 @@ export interface IDataBuilder {
     className: string;
     state: Record<string, AnyValue>;
 }
-/** @internal */
+/**
+ * Callback function to provide if the page is loaded.
+ * @param page - puppeteer's [Page](https://pptr.dev/api/puppeteer.page/) object.
+ */
 export declare type CheckPageLoadCallback = (page: Page) => Promise<boolean>;
 /** @internal */
 export interface IE2EScenarioVisitPlan {
@@ -307,15 +607,211 @@ export declare type RunMetaInfo = {
     browserInfo: IBrowserInfo;
 };
 export interface IHeapSnapshot {
+    /** @internal */
     snapshot: RawHeapSnapshot;
+    /**
+     * A pseudo array containing all heap graph nodes (JS objects in heap).
+     * A JS heap could contain millions of heap objects, so memlab uses
+     * a pseudo array as the collection of all the heap objects. The pseudo
+     * array provides API to query and traverse all heap objects.
+     *
+     * * **Examples**:
+     * ```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);
+     *
+     *   // get the total number of heap objects
+     *   heap.nodes.length;
+     *
+     *   heap.nodes.forEach((node: IHeapNode) => {
+     *     // traverse each heap object
+     *   });
+     * })();
+     * ```
+     */
     nodes: IHeapNodes;
+    /**
+     * 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.
+     *
+     * * **Examples**:
+     * ```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);
+     *
+     *   // get the total number of heap references
+     *   heap.edges.length;
+     *
+     *   heap.edges.forEach((edge: IHeapEdge) => {
+     *     // traverse each reference in the heap
+     *   });
+     * })();
+     * ```
+     */
     edges: IHeapEdges;
+    /**
+     * If you have the id of a heap node (JS object in heap), use this API
+     * to get an {@link IHeapNode} associated with the id.
+     * @param id id of the heap node (JS object in heap) you would like to query
+     * @returns the API returns `null` if no heap object has the specified id.
+     *
+     * * **Examples**:
+     * ```typescript
+     * import type {IHeapSnapshot} 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 node = heap.getNodeById(351);
+     *   node?.id; // should be 351
+     * })();
+     * ```
+     */
     getNodeById(id: number): Nullable<IHeapNode>;
-    clearShortestPathInfo(): void;
+    /**
+     * Search for the heap and check if there is any JS object instance with
+     * a specified constructor name.
+     * @param className The contructor name of the object instance
+     * @returns `true` if there is at least one such object in the heap
+     *
+     * * **Examples**: you can write a jest unit test with memory assertions:
+     * ```typescript
+     * // save as example.test.ts
+     * import type {IHeapSnapshot, Nullable} from '@memlab/core';
+     * import {config, getNodeInnocentHeap} from '@memlab/core';
+     *
+     * class TestObject {
+     *   public arr1 = [1, 2, 3];
+     *   public arr2 = ['1', '2', '3'];
+     * }
+     *
+     * test('memory test with heap assertion', async () => {
+     *   config.muteConsole = true; // no console output
+     *
+     *   let obj: Nullable<TestObject> = new TestObject();
+     *   // get a heap snapshot of the current program state
+     *   let heap: IHeapSnapshot = await getNodeInnocentHeap();
+     *
+     *   // call some function that may add references to obj
+     *   rabbitHole(obj)
+     *
+     *   expect(heap.hasObjectWithClassName('TestObject')).toBe(true);
+     *   obj = null;
+     *
+     *   heap = await getNodeInnocentHeap();
+     *   // if rabbitHole does not have any side effect that
+     *   // adds new references to obj, then obj can be GCed
+     *   expect(heap.hasObjectWithClassName('TestObject')).toBe(false);
+     *
+     * }, 30000);
+     * ```
+     */
     hasObjectWithClassName(className: string): boolean;
+    /**
+     * Search for the heap and get one of the JS object instances with
+     * a specified constructor name (if there is any).
+     * @param className The contructor name of the object instance
+     * @returns a handle pointing to any one of the object instances, returns
+     *          `null` if no such object exists in the heap.
+     *
+     * * **Examples**:
+     * ```typescript
+     * import type {IHeapSnapshot} from '@memlab/core';
+     * import {getNodeInnocentHeap} from '@memlab/core';
+     *
+     * class TestObject {
+     *   public arr1 = [1, 2, 3];
+     *   public arr2 = ['1', '2', '3'];
+     * }
+     *
+     * (async function () {
+     *   const obj = new TestObject();
+     *   // get a heap snapshot of the current program state
+     *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+     *
+     *   const node = heap.getAnyObjectWithClassName('TestObject');
+     *   console.log(node?.name); // should be 'TestObject'
+     * })();
+     * ```
+     */
     getAnyObjectWithClassName(className: string): Nullable<IHeapNode>;
+    /**
+     * Search for the heap and check if there is any JS object instance with
+     * a specified property name.
+     * @param nameOrIndex The property name (string) or element index (number)
+     * on the object instance
+     * @returns returns `true` if there is at least one such object in the heap
+     *
+     * * **Examples**:
+     * ```typescript
+     * import type {IHeapSnapshot} from '@memlab/core';
+     * import {dumpNodeHeapSnapshot} from '@memlab/core';
+     * import {getHeapFromFile} from '@memlab/heap-analysis';
+     *
+     * (async function () {
+     *   // eslint-disable-next-line @typescript-eslint/no-unused-vars
+     *   const object = {'memlab-test-heap-property': 'memlab-test-heap-value'};
+     *
+     *   const heapFile = dumpNodeHeapSnapshot();
+     *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+     *
+     *   // should be true
+     *   console.log(heap.hasObjectWithPropertyName('memlab-test-heap-property'));
+     * })();
+     * ```
+     */
     hasObjectWithPropertyName(nameOrIndex: string | number): boolean;
+    /**
+     * Search for the heap and check if there is any JS object instance with
+     * a marker tagged by {@link tagObject}.
+     * @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
+     *
+     * ```typescript
+     * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
+     * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+     *
+     * test('memory test', async () => {
+     *   config.muteConsole = true;
+     *   const o1: AnyValue = {};
+     *   let o2: AnyValue = {};
+     *
+     *   // tag o1 with marker: "memlab-mark-1", does not modify o1 in any way
+     *   tagObject(o1, 'memlab-mark-1');
+     *   // tag o2 with marker: "memlab-mark-2", does not modify o2 in any way
+     *   tagObject(o2, 'memlab-mark-2');
+     *
+     *   o2 = null;
+     *
+     *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+     *
+     *   // expect object with marker "memlab-mark-1" exists
+     *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+     *
+     *   // expect object with marker "memlab-mark-2" can be GCed
+     *   expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+     *
+     * }, 30000);
+     * ```
+     */
     hasObjectWithTag(tag: string): boolean;
+    /** @internal */
+    clearShortestPathInfo(): void;
 }
 export interface IHeapLocation {
     snapshot: IHeapSnapshot;

package/dist/lib/Types.js

@@ -8,4 +8,5 @@
  * @emails oncall+ws_labs
  * @format
  */
+/* eslint-disable @typescript-eslint/no-explicit-any */
 Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/Utils.js

@@ -542,6 +542,7 @@ function getSnapshotFromFile(filename, options) {
         catch (e) {
             handleSnapshotError(getError(e));
         }
+        Console_1.default.flush();
         return ret;
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/core",
-  "version": "1.0.9",
+  "version": "1.1.2",
   "license": "MIT",
   "description": "memlab core libraries",
   "author": "Liang Gong <lgong@fb.com>",
@@ -56,9 +56,9 @@
     "directory": "packages/core"
   },
   "scripts": {
-    "preinstall": "export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true",
     "build-pkg": "tsc",
     "test-pkg": "jest .",
+    "publish-patch": "npm version patch --force && npm publish",
     "clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
   },
   "bugs": {