@memlab/core 1.1.1 → 1.1.4

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[];
@@ -143,16 +144,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.
+ *
+ * ```typescript
+ * import {IHeapNode, IHeapSnapshot, HeapNodeIdSet, utils} from '@memlab/core';
  *
- * let map = Object.create(null);
+ * 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 +202,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 +325,9 @@ export declare type InteractionsCallback = (page: Page, args?: OperationArgs) =>
  *   url: () => 'https://www.npmjs.com/',
  *   action: async () => ... ,
  *   back: async () => ... ,
+ *   cookies: () => ... , // optional
+ *   repeat: () => ... , // optional
+ *   ...
  * };
  * ```
  *
@@ -230,6 +341,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 +357,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 +393,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 +423,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 +442,8 @@ export interface IScenario {
      *   },
      *   back: async (page) => ... ,
      * }
+     *
+     * module.exports = scenario;
      ```
      */
     action?: InteractionsCallback;
@@ -354,7 +484,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 +520,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 +545,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,86 +736,818 @@ 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;
+    /**
+     * 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}.
+     *
+     * 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
+     *
+     * ```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;
 }
+/**
+ * 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 */