memlab 1.1.8-alpha → 1.1.11-alpha

package/README.md

@@ -12,22 +12,26 @@ Install the CLI
 npm install -g memlab
 ```
 
+### Find Memory Leaks
+
 To find memory leaks in Google Maps, you can create a scenario file defining how
 to interact with the Google Maps, let's name it `test-google-maps.js`:
 
 ```javascript
-// Visit Google Maps
+// initial page load url: Google Maps
 function url() {
   return 'https://www.google.com/maps/@37.386427,-122.0428214,11z';
 }
 
 // action where we want to detect memory leaks: click the Hotels button
 async function action(page) {
+  // puppeteer page API
   await page.click('button[aria-label="Hotels"]');
 }
 
 // action where we want to go back to the step before: click clear search
 async function back(page) {
+  // puppeteer page API
   await page.click('[aria-label="Clear search"]');
 }
 
@@ -35,12 +39,28 @@ module.exports = {action, back, url};
 ```
 
 Now run memlab with the scenario file, memlab will interact with
-the web page and show detected memory leaks:
+the web page and detect memory leaks with built-in leak detectors:
 
 ```bash
 memlab run --scenario test-google-maps.js
 ```
 
+If you want to use a self-defined leak detector, add a `filterLeak` callback
+in the scenario file. `filterLeak` will be called for every unreleased heap
+object (`node`) allocated by the target interaction.
+
+```javascript
+function filterLeak(node, heap) {
+  // ... your leak detector logic
+  // return true to mark the node as a memory leak
+};
+```
+
+`heap` is the graph representation of the final JavaScript heap snapshot.
+For more details, view the [doc site](https://facebookincubator.github.io/memlab).
+
+### Heap Analysis and Investigation
+
 View which object keeps growing in size during interaction in the previous run:
 ```bash
 memlab analyze unbound-object
@@ -52,7 +72,7 @@ Analyze pre-fetched v8/hermes `.heapsnapshot` files:
 memlab analyze unbound-object --snapshot-dir <DIR_OF_SNAPSHOT_FILES>
 ```
 
-Use `memlab analyze` to view all built-in memory analyses. For extension, view the [doc site](/tba).
+Use `memlab analyze` to view all built-in memory analyses. For extension, view the [doc site](https://facebookincubator.github.io/memlab).
 
 View retainer trace of a particular object:
 ```bash
@@ -63,7 +83,7 @@ Use `memlab help` to view all CLI commands.
 
 ## APIs
 
-Use the `memlab` package to start a E2E run in browser and detect memory leaks:
+Use the `memlab` npm package to start a E2E run in browser and detect memory leaks.
 
 ```javascript
 const memlab = require('memlab');

package/bin/{memlab-js → memlab}

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --expose-gc --max-old-space-size=4096
+#!/usr/bin/env node --expose-gc --max-old-space-size=4096
 
 /**
  * Copyright (c) Meta Platforms, Inc. and affiliates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memlab",
-  "version": "1.1.8-alpha",
+  "version": "1.1.11-alpha",
   "license": "MIT",
   "description": "memlab is a framework that analyzes memory and finds memory leaks in JavaScript applications.",
   "main": "dist/index.js",
@@ -8,7 +8,7 @@
     "dist"
   ],
   "bin": {
-    "memlab": "bin/memlab-js"
+    "memlab": "bin/memlab"
   },
   "publishConfig": {
     "access": "public"
@@ -50,6 +50,7 @@
     "typescript": "^4.6.3"
   },
   "scripts": {
+    "preinstall": "./bin/preinstall",
     "build-pkg": "tsc",
     "clean-pkg": "rm -rf ./dist && rm -rf ./node_modules && rm -f ./tsconfig.tsbuildinfo"
   },