feat: add options to set depth and to skip unwanted node names

bin/puppeteer-heap-snapshot.ts

@@ -11,6 +11,10 @@ import { enableDebugLogging } from "../src/util";
 
 if (require.main === module) {
   const castProperties = (value: string): string[] => value.split(/\s*,\s*/);
+  const toNumberOrIfinity = (value: string): number => {
+    const maybeValidNumber = Number.parseInt(value);
+    return Number.isNaN(maybeValidNumber) ? Infinity : maybeValidNumber;
+  };
 
   program
     .option("--debug", "Enable debug mode (non-headless Chrome, debug logging)")
@@ -38,6 +42,17 @@ if (require.main === module) {
       "fetch/read a heap snapshot and output the matching objects in JSON"
     )
     .option("-u, --url <url>")
+    .option(
+      "-d, --depth <value>",
+      "recursion search depth",
+      toNumberOrIfinity,
+      Infinity
+    )
+    .option(
+      "-e, --exclude <...nodeNames>",
+      "name of nodes (case-sensitive) to be excluded from building graph",
+      castProperties
+    )
     .option("-f, --filepath <filepath>", "filepath", relativeFilepath)
     .requiredOption(
       "-p, --properties <...props>",
@@ -84,11 +99,15 @@ async function querySnapshotCommand({
   filepath,
   properties,
   ignoreProperties,
+  exclude,
+  depth,
 }: {
   url?: string;
   filepath?: string;
   properties: string[];
   ignoreProperties?: string[];
+  exclude?: string[];
+  depth?: number;
 }) {
   if (!url && !filepath) {
     throw new Error(`Please specify a URL or a snapshot filepath`);
@@ -100,8 +119,10 @@ async function querySnapshotCommand({
 
   log(
     JSON.stringify(
-      await findObjectsWithProperties(heapSnapshot, properties, {
+      findObjectsWithProperties(heapSnapshot, properties, {
         ignoreProperties,
+        maxDepth: depth,
+        unwantedNodeNames: exclude,
       }),
       null,
       2

package.json

@@ -15,7 +15,7 @@
   "scripts": {
     "prepack": "npm run build",
     "prepare": "husky install && npm run lint && npm run test",
-    "format": "prettier --write '**/*.ts' '!dist/**/*'",
+    "format": "prettier --write \"**/*.ts\" \"!dist/**/*\"",
     "lint": "eslint . --ext .ts",
     "test": "jest",
     "build:esm": "tsc --project tsconfig.esm.json",

src/build-object.ts

@@ -5,16 +5,36 @@ import {
   HeapSnapshotStructuredGraph,
   HeapSnapshotStructuredEdge,
 } from "./types";
-import { createStructuredGraph } from "./structured-graph";
+import {
+  createStructuredGraph,
+  createStructuredNode,
+} from "./structured-graph";
+
+type BuildObjectFromNodeIdOption = {
+  propertyFilter?: (propertyName: string) => boolean;
+  maxDepth?: number;
+  unwantedNodeNames?: readonly string[];
+};
 
 export function buildObjectFromNodeId(
   heapSnapshot: HeapSnapshot,
   nodeId: number,
-  propertyFilter: (propertyName: string) => boolean = () => true
+  options: BuildObjectFromNodeIdOption
 ): BuiltHeapValue {
   debug(`building node object for node ${nodeId}`);
 
-  const graph = createStructuredGraph(heapSnapshot, nodeId, {
+  const { propertyFilter = () => true, maxDepth, unwantedNodeNames } = options;
+
+  // Get structuredNode early to figure out if we should return quickly in case of unwanted node name
+  const structuredNode = createStructuredNode(heapSnapshot, nodeId);
+
+  if (unwantedNodeNames?.includes(structuredNode.name)) {
+    debug(`found node with unwanted name ${structuredNode.name}, skipping...`);
+    return;
+  }
+
+  const graph = createStructuredGraph(heapSnapshot, nodeId, structuredNode, {
+    maxDepth,
     edgeFilter: (edge: HeapSnapshotStructuredEdge) => {
       if (edge.type === "property") {
         return edge.name! !== "__proto__" && propertyFilter(edge.name!);
@@ -95,8 +115,8 @@ function compileGraphNodeObject(
     );
   } else if (isBoolean(graph)) {
     return (
-      graph.edges.find(({ graph }) => graph.node.type === "string").graph.node
-        .name === "true"
+      graph.edges.find(({ graph }) => graph?.node.type === "string")?.graph
+        ?.node.name === "true"
     );
   } else if (isNull(graph)) {
     return null;
@@ -110,14 +130,14 @@ function compileGraphNodeObject(
 function isBoolean(graph: HeapSnapshotStructuredGraph): boolean {
   return (
     graph.node.type === "hidden" &&
-    !!graph.edges.find(({ graph }) => graph.node.name === "boolean")
+    !!graph.edges.find(({ graph }) => graph?.node.name === "boolean")
   );
 }
 
 function isNull(graph: HeapSnapshotStructuredGraph): boolean {
   return (
     graph.node.type === "hidden" &&
-    !!graph.edges.find(({ graph }) => graph.node.name === "object") &&
-    !!graph.edges.find(({ graph }) => graph.node.name === "null")
+    !!graph.edges.find(({ graph }) => graph?.node.name === "object") &&
+    !!graph.edges.find(({ graph }) => graph?.node.name === "null")
   );
 }

src/query.ts

@@ -5,6 +5,8 @@ import { buildObjectFromNodeId } from "./build-object";
 
 type FindObjectOptions = {
   ignoreProperties?: readonly string[];
+  maxDepth?: number;
+  unwantedNodeNames?: readonly string[];
 };
 
 type FindObjectReturnValue<
@@ -34,16 +36,17 @@ export function findObjectsWithProperties<
     );
   }
 
-  return nodeIds.map((nodeId) => {
-    debug(`node ${nodeId} found`);
-    return buildObjectFromNodeId(
-      heapSnapshot,
-      nodeId,
-      options?.ignoreProperties
-        ? (prop) => !options.ignoreProperties!.includes(prop)
-        : undefined
-    );
-  }) as FindObjectReturnValue<Props, Options>[];
+  return nodeIds
+    .map((nodeId) => {
+      debug(`node ${nodeId} found`);
+      return buildObjectFromNodeId(heapSnapshot, nodeId, {
+        ...options,
+        propertyFilter: options?.ignoreProperties
+          ? (prop) => !options.ignoreProperties!.includes(prop)
+          : undefined,
+      });
+    })
+    .filter((v) => v !== undefined) as FindObjectReturnValue<Props, Options>[];
 }
 
 export function findObjectWithProperties<

src/structured-graph.ts

@@ -15,6 +15,7 @@ import {
 export function createStructuredGraph(
   heapSnapshot: HeapSnapshot,
   nodeId: number,
+  structuredNode: HeapSnapshotStructuredNode,
   {
     maxDepth = Infinity,
     edgeFilter = () => true,
@@ -24,7 +25,6 @@ export function createStructuredGraph(
   } = {},
   nodeIdStack: number[] = []
 ): HeapSnapshotStructuredGraph {
-  const structuredNode = createStructuredNode(heapSnapshot, nodeId);
   const structuredEdges = structuredNode.edgeIds
     .map((edgeId) => createStructuredEdge(heapSnapshot, edgeId))
     .filter(edgeFilter);
@@ -42,6 +42,7 @@ export function createStructuredGraph(
             ? createStructuredGraph(
                 heapSnapshot,
                 structuredEdge.nodeId,
+                createStructuredNode(heapSnapshot, structuredEdge.nodeId),
                 { maxDepth, edgeFilter },
                 [...nodeIdStack, nodeId]
               )
@@ -51,7 +52,7 @@ export function createStructuredGraph(
   };
 }
 
-function createStructuredNode(
+export function createStructuredNode(
   heapSnapshot: HeapSnapshot,
   nodeId: number
 ): HeapSnapshotStructuredNode {

src/types.ts

@@ -66,6 +66,7 @@ export type HeapSnapshot = Omit<SerializedHeapSnapshot, "nodes" | "edges"> & {
 
 export type BuiltHeapValue =
   | undefined
+  | null
   | string
   | number
   | RegExp