feat(core): more heap API to query with heap object ids

Summary: This diff adds more APIs to query the heap based on heap object ids.

Reviewed By: tulga1970

Differential Revision: D51866934

fbshipit-source-id: 1568d35838b21a0a2158cf26a66f427d219e29b7

packages/core/src/lib/Types.ts

@@ -1158,6 +1158,58 @@ export interface IHeapSnapshot {
    * ```
    */
   getNodeById(id: number): Nullable<IHeapNode>;
+  /**
+   * Given an array of ids of heap nodes (JS objects in heap), use this API
+   * to get an array of those heap nodes.
+   * @param ids id array of the heap nodes (JS objects in heap) you
+   * would like to query
+   * @returns an array of those heap nodes. The return array will preserve the
+   * order of the input array. If an id is not found in the heap, the
+   * corresponding element in the return array will be `null`.
+   *
+   * * **Examples**:
+   * ```typescript
+   * import type {IHeapSnapshot} from '@memlab/core';
+   * import {dumpNodeHeapSnapshot} from '@memlab/core';
+   * import {getFullHeapFromFile} from '@memlab/heap-analysis';
+   *
+   * (async function () {
+   *   const heapFile = dumpNodeHeapSnapshot();
+   *   const heap: IHeapSnapshot = await getFullHeapFromFile(heapFile);
+   *
+   *   // suppose 1000 is not a valid id in the heap
+   *   const nodes = heap.getNodesByIds([1, 2, 1000, 3]);
+   *   nodes // should be [node1, node2, null, node3]
+   * })();
+   * ```
+   */
+  getNodesByIds(ids: number[]): Array<Nullable<IHeapNode>>;
+  /**
+   * Given a set of ids of heap nodes (JS objects in heap), use this API
+   * to get a set of those heap nodes.
+   * @param ids id set of the heap nodes (JS objects in heap) you
+   * would like to query
+   * @returns a set of those heap nodes. The set will only include
+   * nodes that are found in the heap. If none of the input ids are found,
+   * this API will return an empty set.
+   *
+   * * **Examples**:
+   * ```typescript
+   * import type {IHeapSnapshot} from '@memlab/core';
+   * import {dumpNodeHeapSnapshot} from '@memlab/core';
+   * import {getFullHeapFromFile} from '@memlab/heap-analysis';
+   *
+   * (async function () {
+   *   const heapFile = dumpNodeHeapSnapshot();
+   *   const heap: IHeapSnapshot = await getFullHeapFromFile(heapFile);
+   *
+   *   // suppose 1000 is not a valid id in the heap
+   *   const set = heap.getNodesByIdSet(new Set([1, 2, 1000, 3]));
+   *   set // should be Set([node1, node2, node3])
+   * })();
+   * ```
+   */
+  getNodesByIdSet(ids: Set<number>): Set<IHeapNode>;
   /**
    * Search for the heap and check if there is any JS object instance with
    * a specified constructor name.

packages/core/src/lib/heap-data/HeapSnapshot.ts

@@ -212,6 +212,31 @@ export default class HeapSnapshot implements IHeapSnapshot {
     return new HeapNode(this, idx);
   }
 
+  getNodesByIds(ids: number[]): Array<Nullable<HeapNode>> {
+    const ret: Array<Nullable<HeapNode>> = [];
+    ids.forEach(id => {
+      if (!(id in this._nodeId2NodeIdx)) {
+        ret.push(null);
+        return;
+      }
+      const idx = this._nodeId2NodeIdx[id];
+      ret.push(new HeapNode(this, idx));
+    });
+    return ret;
+  }
+
+  getNodesByIdSet(ids: Set<number>): Set<HeapNode> {
+    const ret = new Set<HeapNode>();
+    ids.forEach(id => {
+      if (!(id in this._nodeId2NodeIdx)) {
+        return;
+      }
+      const idx = this._nodeId2NodeIdx[id];
+      ret.add(new HeapNode(this, idx));
+    });
+    return ret;
+  }
+
   clearShortestPathInfo(): void {
     this._nodeIdxHasPathEdge = new Uint8Array(this._nodeCount);
   }

website/docs/api/interfaces/core_src.IHeapEdge.md

@@ -45,7 +45,7 @@ import {getFullHeapFromFile} from '@memlab/heap-analysis';
 index of this JS reference inside the `edge.snapshot.edges` pseudo array
 
  * **Source**:
-    * core/src/lib/Types.ts:1411
+    * core/src/lib/Types.ts:1463
 
 ___
 
@@ -55,7 +55,7 @@ returns an [IHeapNode](core_src.IHeapNode.md) instance representing the hosting
 JS heap object where this reference starts
 
  * **Source**:
-    * core/src/lib/Types.ts:1432
+    * core/src/lib/Types.ts:1484
 
 ___
 
@@ -67,7 +67,7 @@ otherwise this is a reference with a string name (`edge.name_or_index`
 will return a string)
 
  * **Source**:
-    * core/src/lib/Types.ts:1418
+    * core/src/lib/Types.ts:1470
 
 ___
 
@@ -77,7 +77,7 @@ name of the JS reference. If this is a reference to an array element
 or internal table element, it is an numeric index
 
  * **Source**:
-    * core/src/lib/Types.ts:1367
+    * core/src/lib/Types.ts:1419
 
 ___
 
@@ -86,7 +86,7 @@ ___
 get the [IHeapSnapshot](core_src.IHeapSnapshot.md) containing this JS reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1407
+    * core/src/lib/Types.ts:1459
 
 ___
 
@@ -96,7 +96,7 @@ returns an [IHeapNode](core_src.IHeapNode.md) instance representing the JS heap
 pointed to by this reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1427
+    * core/src/lib/Types.ts:1479
 
 ___
 
@@ -105,7 +105,7 @@ ___
 the index of the JS heap object pointed to by this reference
 
  * **Source**:
-    * core/src/lib/Types.ts:1422
+    * core/src/lib/Types.ts:1474
 
 ___
 
@@ -115,7 +115,7 @@ type of the JS reference, all types:
 `context`, `element`, `property`, `internal`, `hidden`, `shortcut`, `weak`
 
  * **Source**:
-    * core/src/lib/Types.ts:1372
+    * core/src/lib/Types.ts:1424
 
 ## Methods
 
@@ -133,4 +133,4 @@ captured by the hosting object.
     * `...args`: `any`[]
  * **Returns**: `string`
  * **Source**:
-    * core/src/lib/Types.ts:1442
+    * core/src/lib/Types.ts:1494

website/docs/api/interfaces/core_src.IHeapEdges.md

@@ -41,7 +41,7 @@ The total number of edges in heap graph (or JS references in heap
 snapshot).
 
  * **Source**:
-    * core/src/lib/Types.ts:1479
+    * core/src/lib/Types.ts:1531
 
 ## Methods
 
@@ -54,7 +54,7 @@ to each element in ascending order of element index.
     * `callback`: (`edge`: [`IHeapEdge`](core_src.IHeapEdge.md), `index`: `number`) => `boolean` \| `void` | 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.
  * **Returns**: `void`
  * **Source**:
-    * core/src/lib/Types.ts:1495
+    * core/src/lib/Types.ts:1547
 
 ___
 
@@ -68,4 +68,4 @@ get an [IHeapEdge](core_src.IHeapEdge.md) element at the specified index
 at the specified index, otherwise it returns `null`.
 
  * **Source**:
-    * core/src/lib/Types.ts:1487
+    * core/src/lib/Types.ts:1539

website/docs/api/interfaces/core_src.IHeapLocation.md

@@ -43,7 +43,7 @@ import {getFullHeapFromFile} from '@memlab/heap-analysis';
 get the column number
 
  * **Source**:
-    * core/src/lib/Types.ts:1348
+    * core/src/lib/Types.ts:1400
 
 ___
 
@@ -52,7 +52,7 @@ ___
 get the line number
 
  * **Source**:
-    * core/src/lib/Types.ts:1344
+    * core/src/lib/Types.ts:1396
 
 ___
 
@@ -61,7 +61,7 @@ ___
 get the heap object this location this location represents
 
  * **Source**:
-    * core/src/lib/Types.ts:1336
+    * core/src/lib/Types.ts:1388
 
 ___
 
@@ -70,7 +70,7 @@ ___
 get the script ID of the source file
 
  * **Source**:
-    * core/src/lib/Types.ts:1340
+    * core/src/lib/Types.ts:1392
 
 ___
 
@@ -79,7 +79,7 @@ ___
 get the [IHeapSnapshot](core_src.IHeapSnapshot.md) containing this location instance
 
  * **Source**:
-    * core/src/lib/Types.ts:1332
+    * core/src/lib/Types.ts:1384
 
 ## Methods
 
@@ -97,4 +97,4 @@ captured by the hosting object.
     * `...args`: `any`[]
  * **Returns**: `string`
  * **Source**:
-    * core/src/lib/Types.ts:1358
+    * core/src/lib/Types.ts:1410