@memlab/heap-analysis 1.0.3 → 1.0.6

package/README.md

@@ -3,5 +3,6 @@
 This is the memlab heap analysis library. It contains all memlab built-in heap analysis and
 provides a plugin interface for adding new heap analysis that can be easily added to memlab API and memlab CLI.
 
-## Full documentation
-https://facebookincubator.github.io/memlab
+## Online Resources
+* [Official Website and Demo](https://facebookincubator.github.io/memlab)
+* [Documentation](https://facebookincubator.github.io/memlab/docs/intro)

package/dist/BaseAnalysis.js

@@ -62,7 +62,7 @@ class Analysis {
     run(options = PluginUtils_1.default.defaultAnalysisArgs) {
         return __awaiter(this, void 0, void 0, function* () {
             loadScenarioConfig();
-            return yield this.process(options);
+            yield this.process(options);
         });
     }
     /**

package/dist/HeapConfig.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+import type { IHeapSnapshot, Optional, IHeapConfig } from '@memlab/core';
+declare class HeapConfig implements IHeapConfig {
+    isCliInteractiveMode: boolean;
+    currentHeapFile: Optional<string>;
+    currentHeap: Optional<IHeapSnapshot>;
+    private constructor();
+    private static instance;
+    static getInstance(): HeapConfig;
+}
+declare const heapConfig: HeapConfig;
+export default heapConfig;
+//# sourceMappingURL=HeapConfig.d.ts.map

package/dist/HeapConfig.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+ws_labs
+ * @format
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@memlab/core");
+class HeapConfig {
+    constructor() {
+        this.isCliInteractiveMode = false;
+        this.currentHeap = null;
+        this.currentHeapFile = null;
+    }
+    static getInstance() {
+        if (!HeapConfig.instance) {
+            HeapConfig.instance = new HeapConfig();
+        }
+        return HeapConfig.instance;
+    }
+}
+HeapConfig.instance = null;
+const heapConfig = HeapConfig.getInstance();
+core_1.config.heapConfig = heapConfig;
+exports.default = heapConfig;

package/dist/PluginUtils.d.ts

@@ -166,14 +166,36 @@ declare function loadHeapSnapshot(options: HeapAnalysisOptions): Promise<IHeapSn
  * * **Examples**:
  * ```typescript
  * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile} from '@memlab/heap-analysis';
+ * import {getFullHeapFromFile} from '@memlab/heap-analysis';
  *
  * (async function (){
  *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap = await getHeapFromFile(heapFile);
+ *   const heap = await getFullHeapFromFile(heapFile);
  * })();
  * ```
  */
+declare function getFullHeapFromFile(file: string): Promise<IHeapSnapshot>;
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. This
+ * API also calculates some heap analysis meta data
+ * for heap analysis. But this also means slower heap parsing
+ * comparing with {@link takeNodeMinimalHeap}.
+ *
+ * @returns heap representation with heap analysis meta data.
+ *
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {takeNodeFullHeap} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heap: IHeapSnapshot = await takeNodeFullHeap();
+ * })();
+ * ```
+ */
+declare function takeNodeFullHeap(): Promise<IHeapSnapshot>;
+/** @deprecated */
 declare function getHeapFromFile(file: string): Promise<IHeapSnapshot>;
 /**
  * When a heap analysis is taking multiple heap snapshots as input for memory
@@ -261,7 +283,7 @@ declare function aggregateDominatorMetrics(ids: Set<number>, snapshot: IHeapSnap
  * * * **Examples**:
  * ```typescript
  * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile, getDominatorNodes} from '@memlab/heap-analysis';
+ * import {getFullHeapFromFile, getDominatorNodes} from '@memlab/heap-analysis';
  *
  * class TestObject {}
  *
@@ -271,7 +293,7 @@ declare function aggregateDominatorMetrics(ids: Set<number>, snapshot: IHeapSnap
  *
  *   // dump the heap of this running JavaScript program
  *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap = await getHeapFromFile(heapFile);
+ *   const heap = await getFullHeapFromFile(heapFile);
  *
  *   // find the heap node for TestObject
  *   let nodes = [];
@@ -306,9 +328,11 @@ declare const _default: {
     isNodeWorthInspecting: typeof isNodeWorthInspecting;
     loadHeapSnapshot: typeof loadHeapSnapshot;
     getHeapFromFile: typeof getHeapFromFile;
+    getFullHeapFromFile: typeof getFullHeapFromFile;
     printNodeListInTerminal: typeof printNodeListInTerminal;
     printReferencesInTerminal: typeof printReferencesInTerminal;
     snapshotMapReduce: typeof snapshotMapReduce;
+    takeNodeFullHeap: typeof takeNodeFullHeap;
 };
 export default _default;
 //# sourceMappingURL=PluginUtils.d.ts.map

package/dist/PluginUtils.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@memlab/core");
 const chalk_1 = __importDefault(require("chalk"));
 const core_2 = require("@memlab/core");
+const HeapConfig_1 = __importDefault(require("./HeapConfig"));
 const nodeNameBlockList = new Set([
     '(Startup object cache)',
     '(Global handles)',
@@ -231,9 +232,6 @@ function getSnapshotFileForAnalysis(options) {
     if (args.snapshot) {
         return args.snapshot;
     }
-    if (core_1.config.externalSnapshotFilePaths.length > 0) {
-        return core_1.config.externalSnapshotFilePaths[core_1.config.externalSnapshotFilePaths.length - 1];
-    }
     return core_2.utils.getSingleSnapshotFileForAnalysis();
 }
 /**
@@ -330,8 +328,19 @@ function getSnapshotDirForAnalysis(options) {
  */
 function loadHeapSnapshot(options) {
     return __awaiter(this, void 0, void 0, function* () {
-        const file = getSnapshotFileForAnalysis(options);
-        return loadProcessedSnapshot({ file });
+        if (HeapConfig_1.default.isCliInteractiveMode) {
+            if (!HeapConfig_1.default.currentHeap) {
+                const file = getSnapshotFileForAnalysis(options);
+                const heap = yield loadProcessedSnapshot({ file });
+                HeapConfig_1.default.currentHeapFile = file;
+                HeapConfig_1.default.currentHeap = heap;
+            }
+            return HeapConfig_1.default.currentHeap;
+        }
+        else {
+            const file = getSnapshotFileForAnalysis(options);
+            return loadProcessedSnapshot({ file });
+        }
     });
 }
 /**
@@ -343,14 +352,47 @@ function loadHeapSnapshot(options) {
  * * **Examples**:
  * ```typescript
  * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile} from '@memlab/heap-analysis';
+ * import {getFullHeapFromFile} from '@memlab/heap-analysis';
  *
  * (async function (){
  *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap = await getHeapFromFile(heapFile);
+ *   const heap = await getFullHeapFromFile(heapFile);
  * })();
  * ```
  */
+function getFullHeapFromFile(file) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return yield loadProcessedSnapshot({ file });
+    });
+}
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. This
+ * API also calculates some heap analysis meta data
+ * for heap analysis. But this also means slower heap parsing
+ * comparing with {@link takeNodeMinimalHeap}.
+ *
+ * @returns heap representation with heap analysis meta data.
+ *
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {takeNodeFullHeap} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heap: IHeapSnapshot = await takeNodeFullHeap();
+ * })();
+ * ```
+ */
+function takeNodeFullHeap() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const heap = yield (0, core_1.takeNodeMinimalHeap)();
+        core_2.analysis.preparePathFinder(heap);
+        core_2.info.flush();
+        return heap;
+    });
+}
+/** @deprecated */
 function getHeapFromFile(file) {
     return __awaiter(this, void 0, void 0, function* () {
         return yield loadProcessedSnapshot({ file });
@@ -480,7 +522,7 @@ function aggregateDominatorMetrics(ids, snapshot, checkNodeCb, nodeMetricsCb) {
  * * * **Examples**:
  * ```typescript
  * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile, getDominatorNodes} from '@memlab/heap-analysis';
+ * import {getFullHeapFromFile, getDominatorNodes} from '@memlab/heap-analysis';
  *
  * class TestObject {}
  *
@@ -490,7 +532,7 @@ function aggregateDominatorMetrics(ids, snapshot, checkNodeCb, nodeMetricsCb) {
  *
  *   // dump the heap of this running JavaScript program
  *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap = await getHeapFromFile(heapFile);
+ *   const heap = await getFullHeapFromFile(heapFile);
  *
  *   // find the heap node for TestObject
  *   let nodes = [];
@@ -543,7 +585,9 @@ exports.default = {
     isNodeWorthInspecting,
     loadHeapSnapshot,
     getHeapFromFile,
+    getFullHeapFromFile,
     printNodeListInTerminal,
     printReferencesInTerminal,
     snapshotMapReduce,
+    takeNodeFullHeap,
 };

package/dist/__tests__/HeapAnalysis.test.js

@@ -22,6 +22,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@memlab/core");
+const __1 = require("..");
 const HeapAnalysisLoader_1 = __importDefault(require("../HeapAnalysisLoader"));
 beforeEach(() => {
     core_1.config.isTest = true;
@@ -30,3 +31,19 @@ test('Heap analysis modules can be loaded', () => __awaiter(void 0, void 0, void
     const heapAnalysisMap = HeapAnalysisLoader_1.default.loadAllAnalysis();
     expect(heapAnalysisMap.size).toBeGreaterThan(0);
 }));
+test('takeNodeFullHeap works as expected', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    class TestClass {
+        constructor() {
+            this.name = 'test';
+            this.age = 183;
+        }
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const _v = new TestClass();
+    const heap = yield (0, __1.takeNodeFullHeap)();
+    const node = heap.getAnyObjectWithClassName('TestClass');
+    expect((node === null || node === void 0 ? void 0 : node.dominatorNode) != null).toBe(true);
+    const size = (_a = node === null || node === void 0 ? void 0 : node.retainedSize) !== null && _a !== void 0 ? _a : 0;
+    expect(size > 0).toBe(true);
+}));

package/dist/__tests__/package.test.js

@@ -57,9 +57,9 @@ test('analyzeSnapshotFromFile works as expected', () => __awaiter(void 0, void 0
     yield analysis.analyzeSnapshotFromFile(heapFile);
     expect(called).toBe(true);
 }));
-test('getHeapFromFile works as expected', () => __awaiter(void 0, void 0, void 0, function* () {
+test('getFullHeapFromFile works as expected', () => __awaiter(void 0, void 0, void 0, function* () {
     const heapFile = (0, core_1.dumpNodeHeapSnapshot)();
-    const heap = yield (0, index_1.getHeapFromFile)(heapFile);
+    const heap = yield (0, index_1.getFullHeapFromFile)(heapFile);
     expect(heap.nodes.length > 0).toBe(true);
 }));
 test('getDominatorNodes works as expected', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -71,7 +71,7 @@ test('getDominatorNodes works as expected', () => __awaiter(void 0, void 0, void
     const t2 = new TestObject();
     // dump the heap of this running JavaScript program
     const heapFile = (0, core_1.dumpNodeHeapSnapshot)();
-    const heap = yield (0, index_1.getHeapFromFile)(heapFile);
+    const heap = yield (0, index_1.getFullHeapFromFile)(heapFile);
     // find the heap node for TestObject
     const nodes = [];
     heap.nodes.forEach(node => {

package/dist/index.d.ts

@@ -7,7 +7,11 @@
  * @emails oncall+ws_labs
  * @format
  */
-export declare const getDominatorNodes: (ids: Set<number>, snapshot: import("../../core/src").IHeapSnapshot) => Set<number>, getHeapFromFile: (file: string) => Promise<import("../../core/src").IHeapSnapshot>, getSnapshotDirForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => import("../../core/src").Nullable<string>, getSnapshotFileForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => string, loadHeapSnapshot: (options: import("./PluginUtils").HeapAnalysisOptions) => Promise<import("../../core/src").IHeapSnapshot>, snapshotMapReduce: <T1, T2>(mapCallback: (snapshot: import("../../core/src").IHeapSnapshot, i: number, file: string) => T1, reduceCallback: (results: T1[]) => T2, options: import("./PluginUtils").HeapAnalysisOptions) => Promise<T2>;
+/** @internal */
+export declare function registerPackage(): Promise<void>;
+export declare const getDominatorNodes: (ids: Set<number>, snapshot: import("@memlab/core").IHeapSnapshot) => Set<number>, 
+/** @deprecated */
+getHeapFromFile: (file: string) => Promise<import("@memlab/core").IHeapSnapshot>, getFullHeapFromFile: (file: string) => Promise<import("@memlab/core").IHeapSnapshot>, getSnapshotDirForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => import("@memlab/core").Nullable<string>, getSnapshotFileForAnalysis: (options: import("./PluginUtils").HeapAnalysisOptions) => string, loadHeapSnapshot: (options: import("./PluginUtils").HeapAnalysisOptions) => Promise<import("@memlab/core").IHeapSnapshot>, snapshotMapReduce: <T1, T2>(mapCallback: (snapshot: import("@memlab/core").IHeapSnapshot, i: number, file: string) => T1, reduceCallback: (results: T1[]) => T2, options: import("./PluginUtils").HeapAnalysisOptions) => Promise<T2>, takeNodeFullHeap: () => Promise<import("@memlab/core").IHeapSnapshot>;
 export type { HeapAnalysisOptions } from './PluginUtils';
 export { default as BaseAnalysis } from './BaseAnalysis';
 export { default as DetachedDOMElementAnalysis } from './plugins/DetachedDOMElementAnalysis';
@@ -24,4 +28,6 @@ export { default as StringAnalysis } from './plugins/StringAnalysis';
 export { default as PluginUtils } from './PluginUtils';
 /** @internal */
 export { default as heapAnalysisLoader } from './HeapAnalysisLoader';
+/** @internal */
+export { default as heapConfig } from './HeapConfig';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,13 +8,33 @@
  * @emails oncall+ws_labs
  * @format
  */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.heapAnalysisLoader = exports.PluginUtils = exports.StringAnalysis = exports.ObjectUnboundGrowthAnalysis = exports.ObjectShapeAnalysis = exports.ObjectFanoutAnalysis = exports.ShapeUnboundGrowthAnalysis = exports.ObjectSizeAnalysis = exports.ObjectShallowAnalysis = exports.CollectionsHoldingStaleAnalysis = exports.GlobalVariableAnalysis = exports.DetachedDOMElementAnalysis = exports.BaseAnalysis = exports.snapshotMapReduce = exports.loadHeapSnapshot = exports.getSnapshotFileForAnalysis = exports.getSnapshotDirForAnalysis = exports.getHeapFromFile = exports.getDominatorNodes = void 0;
+exports.heapConfig = exports.heapAnalysisLoader = exports.PluginUtils = exports.StringAnalysis = exports.ObjectUnboundGrowthAnalysis = exports.ObjectShapeAnalysis = exports.ObjectFanoutAnalysis = exports.ShapeUnboundGrowthAnalysis = exports.ObjectSizeAnalysis = exports.ObjectShallowAnalysis = exports.CollectionsHoldingStaleAnalysis = exports.GlobalVariableAnalysis = exports.DetachedDOMElementAnalysis = exports.BaseAnalysis = exports.takeNodeFullHeap = exports.snapshotMapReduce = exports.loadHeapSnapshot = exports.getSnapshotFileForAnalysis = exports.getSnapshotDirForAnalysis = exports.getFullHeapFromFile = exports.getHeapFromFile = exports.getDominatorNodes = exports.registerPackage = void 0;
+const path_1 = __importDefault(require("path"));
+const core_1 = require("@memlab/core");
+/** @internal */
+function registerPackage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return core_1.PackageInfoLoader.registerPackage(path_1.default.join(__dirname, '..'));
+    });
+}
+exports.registerPackage = registerPackage;
 const PluginUtils_1 = __importDefault(require("./PluginUtils"));
-exports.getDominatorNodes = PluginUtils_1.default.getDominatorNodes, exports.getHeapFromFile = PluginUtils_1.default.getHeapFromFile, exports.getSnapshotDirForAnalysis = PluginUtils_1.default.getSnapshotDirForAnalysis, exports.getSnapshotFileForAnalysis = PluginUtils_1.default.getSnapshotFileForAnalysis, exports.loadHeapSnapshot = PluginUtils_1.default.loadHeapSnapshot, exports.snapshotMapReduce = PluginUtils_1.default.snapshotMapReduce;
+exports.getDominatorNodes = PluginUtils_1.default.getDominatorNodes, 
+/** @deprecated */
+exports.getHeapFromFile = PluginUtils_1.default.getHeapFromFile, exports.getFullHeapFromFile = PluginUtils_1.default.getFullHeapFromFile, exports.getSnapshotDirForAnalysis = PluginUtils_1.default.getSnapshotDirForAnalysis, exports.getSnapshotFileForAnalysis = PluginUtils_1.default.getSnapshotFileForAnalysis, exports.loadHeapSnapshot = PluginUtils_1.default.loadHeapSnapshot, exports.snapshotMapReduce = PluginUtils_1.default.snapshotMapReduce, exports.takeNodeFullHeap = PluginUtils_1.default.takeNodeFullHeap;
 var BaseAnalysis_1 = require("./BaseAnalysis");
 Object.defineProperty(exports, "BaseAnalysis", { enumerable: true, get: function () { return __importDefault(BaseAnalysis_1).default; } });
 var DetachedDOMElementAnalysis_1 = require("./plugins/DetachedDOMElementAnalysis");
@@ -43,3 +63,6 @@ Object.defineProperty(exports, "PluginUtils", { enumerable: true, get: function
 /** @internal */
 var HeapAnalysisLoader_1 = require("./HeapAnalysisLoader");
 Object.defineProperty(exports, "heapAnalysisLoader", { enumerable: true, get: function () { return __importDefault(HeapAnalysisLoader_1).default; } });
+/** @internal */
+var HeapConfig_1 = require("./HeapConfig");
+Object.defineProperty(exports, "heapConfig", { enumerable: true, get: function () { return __importDefault(HeapConfig_1).default; } });

package/dist/plugins/StringAnalysis.js

@@ -60,7 +60,7 @@ class StringAnalysis extends BaseAnalysis_1.default {
      * @internal
      */
     getDescription() {
-        return 'Analyze string in heap';
+        return 'Find duplicated string instances in heap';
     }
     /** @internal */
     getOptions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/heap-analysis",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "license": "MIT",
   "description": "heap analysis plugins for memlab",
   "author": "Liang Gong <lgong@fb.com>",
@@ -19,8 +19,8 @@
     "dist"
   ],
   "dependencies": {
-    "@memlab/core": "^1.0.0",
-    "@memlab/e2e": "^1.0.0",
+    "@memlab/core": "^1.1.6",
+    "@memlab/e2e": "^1.0.7",
     "ansi": "^0.3.1",
     "babar": "^0.2.0",
     "chalk": "^4.0.0",