@memlab/core 1.1.4 → 1.1.7

package/dist/__tests__/parser/HeapParser.test.js

@@ -36,7 +36,7 @@ test('Capture inserted object', () => __awaiter(void 0, void 0, void 0, function
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const injected = new TestObject();
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithClassName('TestObject')).toBe(true);
 }), timeout);
 test('Does not capture transcient object', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -49,6 +49,6 @@ test('Does not capture transcient object', () => __awaiter(void 0, void 0, void
     let injected = new TestObject();
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     injected = null;
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithClassName('TestObject')).toBe(false);
 }), timeout);

package/dist/__tests__/parser/NodeHeap.test.js

@@ -30,7 +30,7 @@ const timeout = 5 * 60 * 1000;
 test('Capture current node heap snapshot', () => __awaiter(void 0, void 0, void 0, function* () {
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = { 'memlab-test-heap-property': 'memlab-test-heap-value' };
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithPropertyName('memlab-test-heap-property')).toBe(true);
 }), timeout);
 test('Nullified Object should not exist in heap', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -39,7 +39,7 @@ test('Nullified Object should not exist in heap', () => __awaiter(void 0, void 0
     };
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     object = null;
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithPropertyName('memlab-test-heap-property')).toBe(false);
 }), timeout);
 test('Strongly referenced object should exist in heap', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -59,7 +59,7 @@ test('Strongly referenced object should exist in heap', () => __awaiter(void 0,
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = buildTest();
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithClassName('TestClass1')).toBe(true);
     expect(heap.hasObjectWithClassName('TestClass2')).toBe(true);
 }), timeout);
@@ -80,7 +80,7 @@ test('Weakly referenced object should not exist in heap', () => __awaiter(void 0
     }
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const object = buildTest();
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithClassName('TestClass3')).toBe(true);
     expect(heap.hasObjectWithClassName('TestClass4')).toBe(false);
 }), timeout);
@@ -90,7 +90,7 @@ test('Check annotated objects', () => __awaiter(void 0, void 0, void 0, function
     (0, NodeHeap_1.tagObject)(o1, 'memlab-mark-1');
     (0, NodeHeap_1.tagObject)(o2, 'memlab-mark-2');
     o2 = null;
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
     expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
 }), timeout);

package/dist/__tests__/parser/StringNode.test.js

@@ -41,7 +41,7 @@ test('String heap object APIs work', () => __awaiter(void 0, void 0, void 0, fun
     injected.complexConcatString += 'value_';
     injected.complexConcatString += 123;
     injected.complexConcatString += '_suffix';
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     const testObject = heap.getAnyObjectWithClassName('TestObject');
     expect(testObject).not.toBe(null);
     // testObject.originalString === 'test'

package/dist/__tests__/parser/traverse/HeapNodeTraverse.test.js

@@ -74,7 +74,7 @@ test('Check getReference and getReferenceNode', () => __awaiter(void 0, void 0,
         });
         return detected;
     };
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(checker(heap)).toBe(true);
 }), timeout);
 test('Check getReferrers and getReferrerNodes', () => __awaiter(void 0, void 0, void 0, function* () {
@@ -135,6 +135,6 @@ test('Check getReferrers and getReferrerNodes', () => __awaiter(void 0, void 0,
         }
         return true;
     };
-    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
+    const heap = yield (0, NodeHeap_1.takeNodeMinimalHeap)();
     expect(checker(heap)).toBe(true);
 }), timeout);

package/dist/index.d.ts

@@ -7,7 +7,10 @@
  * @emails oncall+ws_labs
  * @format
  */
+/** @internal */
+export declare function registerPackage(): Promise<void>;
 export * from './lib/Types';
+export * from './lib/NodeHeap';
 /** @internal */
 export { default as config } from './lib/Config';
 /** @internal */
@@ -42,5 +45,6 @@ export { default as leakClusterLogger } from './logger/LeakClusterLogger';
 export { default as NormalizedTrace } from './trace-cluster/TraceBucket';
 /** @internal */
 export { default as EvaluationMetric } from './trace-cluster/EvalutationMetric';
-export * from './lib/NodeHeap';
+/** @internal */
+export * from './lib/PackageInfoLoader';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -22,12 +22,31 @@ var __createBinding = (this && this.__createBinding) || (Object.create ? (functi
 var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
+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.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = void 0;
+exports.EvaluationMetric = exports.NormalizedTrace = exports.leakClusterLogger = exports.ProcessManager = exports.modes = exports.constant = exports.analysis = exports.browserInfo = exports.serializer = exports.fileManager = exports.utils = exports.BaseOption = exports.info = exports.config = exports.registerPackage = void 0;
+const path_1 = __importDefault(require("path"));
+const PackageInfoLoader_1 = require("./lib/PackageInfoLoader");
+/** @internal */
+function registerPackage() {
+    return __awaiter(this, void 0, void 0, function* () {
+        return PackageInfoLoader_1.PackageInfoLoader.registerPackage(path_1.default.join(__dirname, '..'));
+    });
+}
+exports.registerPackage = registerPackage;
 __exportStar(require("./lib/Types"), exports);
+__exportStar(require("./lib/NodeHeap"), exports);
 /** @internal */
 var Config_1 = require("./lib/Config");
 Object.defineProperty(exports, "config", { enumerable: true, get: function () { return __importDefault(Config_1).default; } });
@@ -76,4 +95,5 @@ Object.defineProperty(exports, "NormalizedTrace", { enumerable: true, get: funct
 /** @internal */
 var EvalutationMetric_1 = require("./trace-cluster/EvalutationMetric");
 Object.defineProperty(exports, "EvaluationMetric", { enumerable: true, get: function () { return __importDefault(EvalutationMetric_1).default; } });
-__exportStar(require("./lib/NodeHeap"), exports);
+/** @internal */
+__exportStar(require("./lib/PackageInfoLoader"), exports);

package/dist/lib/Config.d.ts

@@ -8,7 +8,8 @@
  * @format
  */
 import type { LaunchOptions, Permission } from 'puppeteer';
-import type { AnyFunction, AnyValue, IClusterStrategy, IRunningMode, IScenario, Nullable, Optional, QuickExperiment, ILeakFilter } from './Types';
+import type { AnyFunction, AnyValue, IClusterStrategy, IRunningMode, IScenario, Nullable, Optional, QuickExperiment, ILeakFilter, IPackageInfo } from './Types';
+import { IHeapConfig } from '..';
 interface BrowserLaunchArgumentOptions {
     headless?: boolean;
     userDataDir?: string;
@@ -44,14 +45,18 @@ export declare enum ErrorHandling {
 }
 /** @internal */
 export declare class MemLabConfig {
-    snapshotHasDetachedness: boolean;
-    specifiedEngine: boolean;
-    verbose: boolean;
-    jsEngine: string;
     _reportLeaksInTimers: boolean;
     _deviceManualOverridden: boolean;
     _timerNodes: string[];
     _timerEdges: string[];
+    _isFullRun: boolean;
+    _scenario: Optional<IScenario>;
+    _isHeadfulBrowser: boolean;
+    _browser: string;
+    snapshotHasDetachedness: boolean;
+    specifiedEngine: boolean;
+    verbose: boolean;
+    jsEngine: string;
     targetApp: string;
     targetTab: string;
     analysisMode: string;
@@ -91,10 +96,10 @@ export declare class MemLabConfig {
     dataBuilderDataDir: string;
     unclassifiedClusterDir: string;
     externalCookiesFile: Optional<string>;
+    heapConfig: Optional<IHeapConfig>;
     puppeteerConfig: LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions;
     openDevtoolsConsole: boolean;
     emulateDevice: Nullable<Device>;
-    _browser: string;
     addEnableGK: Set<string>;
     addDisableGK: Set<string>;
     qes: QuickExperiment[];
@@ -169,15 +174,17 @@ export declare class MemLabConfig {
     oversizeObjectAsLeak: boolean;
     oversizeThreshold: number;
     clusterRetainedSizeThreshold: number;
-    _isFullRun: boolean;
-    _scenario: Optional<IScenario>;
-    _isHeadfulBrowser: boolean;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
     muteConsole: boolean;
+    includeObjectInfoInTraceReturnChain: boolean;
     logUnclassifiedClusters: boolean;
     errorHandling: ErrorHandling;
     clusterStrategy: Optional<IClusterStrategy>;
+    packageInfo: IPackageInfo[];
+    isMLClustering: boolean;
+    mlClusteringLinkageMaxDistance: number;
+    mlMaxDF: number;
     constructor(options?: ConfigOption);
     private initInternalConfigs;
     private init;

package/dist/lib/Config.js

@@ -65,6 +65,8 @@ class MemLabConfig {
         // by default we want to use Xvfb if the Env supports it
         this.useXVFB = true;
         this.specifiedEngine = false;
+        // set by the heap-analysis package if HeapConfig is used
+        this.heapConfig = null;
         // set puppeteer configuration
         this.puppeteerConfig = {
             headless: !this._isHeadfulBrowser,
@@ -97,6 +99,8 @@ class MemLabConfig {
         this.jsEngine = Constant_1.default.defaultEngine;
         // the default browser (Chromium)
         this._browser = 'chrome';
+        // a list of package information
+        this.packageInfo = [];
         // a set of additional GKs to be enabled
         this.addEnableGK = new Set();
         // a set of additional GKs to be disabled
@@ -117,8 +121,19 @@ class MemLabConfig {
         this.muteConsole = false;
         // log all leak traces, each as an unclassified cluster
         this.logUnclassifiedClusters = false;
+        // If true, the detailed JSON file of each representative
+        // trace (for visualization) will include detailed object
+        // info for each Fiber node on the return chain.
+        // This may bloat the trace size from 100KB to 50MB.
+        this.includeObjectInfoInTraceReturnChain = false;
         // by default halt the program when utils.haltOrThrow is calleds
         this.errorHandling = ErrorHandling.Halt;
+        // by default use clustering based on heurastics
+        this.isMLClustering = false;
+        // linkage max distance for caclulating distances among clusters
+        this.mlClusteringLinkageMaxDistance = 0.7;
+        // TF/IDF maximum document frequency
+        this.mlMaxDF = 1;
     }
     // initialize configurable parameters
     init(options = {}) {

package/dist/lib/FileManager.js

@@ -41,8 +41,10 @@ class FileManager {
         return path_1.default.join(this.getTmpDir(), 'memlab');
     }
     generateTmpHeapDir() {
-        const dirPath = path_1.default.join(this.getTmpDir(), Utils_1.default.getUniqueID());
-        fs_extra_1.default.mkdirSync(dirPath);
+        const dirPath = path_1.default.join(this.getTmpDir(), 'memlab-' + Utils_1.default.getUniqueID());
+        if (!fs_extra_1.default.existsSync(dirPath)) {
+            fs_extra_1.default.mkdirSync(dirPath);
+        }
         return dirPath;
     }
     getWorkDir(options = {}) {

package/dist/lib/HeapAnalyzer.js

@@ -33,6 +33,7 @@ const Console_1 = __importDefault(require("./Console"));
 const Serializer_1 = __importDefault(require("./Serializer"));
 const Utils_1 = __importDefault(require("./Utils"));
 const LeakObjectFilter_1 = require("./leak-filters/LeakObjectFilter");
+const MLTraceSimilarityStrategy_1 = __importDefault(require("../trace-cluster/strategies/MLTraceSimilarityStrategy"));
 class MemoryAnalyst {
     checkLeak() {
         return __awaiter(this, void 0, void 0, function* () {
@@ -249,9 +250,17 @@ class MemoryAnalyst {
             let snapshotLeakedHeapNodeIdSet = new Set();
             let nodeIdsInSnapshots = [];
             let snapshot;
+            // if specified a heap file
             if (options.file) {
                 const opt = { buildNodeIdIndex: true, verbose: true };
                 snapshot = yield Utils_1.default.getSnapshotFromFile(options.file, opt);
+                // if running in interactive heap analysis mode
+            }
+            else if (Config_1.default.heapConfig &&
+                Config_1.default.heapConfig.isCliInteractiveMode &&
+                Config_1.default.heapConfig.currentHeap) {
+                snapshot = Config_1.default.heapConfig.currentHeap;
+                // otherwise diff heap snapshots
             }
             else {
                 Utils_1.default.checkSnapshots();
@@ -367,14 +376,17 @@ class MemoryAnalyst {
     // initialize the path finder
     preparePathFinder(snapshot) {
         const finder = new TraceFinder_1.default();
-        // shortest path for all nodes
-        finder.annotateShortestPaths(snapshot);
-        // dominator and retained size
-        finder.calculateAllNodesRetainedSizes(snapshot);
-        // mark detached Fiber nodes
-        Utils_1.default.markAllDetachedFiberNode(snapshot);
-        // mark alternate Fiber nodes
-        Utils_1.default.markAlternateFiberNode(snapshot);
+        if (!snapshot.isProcessed) {
+            // shortest path for all nodes
+            finder.annotateShortestPaths(snapshot);
+            // dominator and retained size
+            finder.calculateAllNodesRetainedSizes(snapshot);
+            // mark detached Fiber nodes
+            Utils_1.default.markAllDetachedFiberNode(snapshot);
+            // mark alternate Fiber nodes
+            Utils_1.default.markAlternateFiberNode(snapshot);
+            snapshot.isProcessed = true;
+        }
         return finder;
     }
     // summarize the page interaction and dump to the leak text summary file
@@ -630,7 +642,11 @@ class MemoryAnalyst {
                 Console_1.default.midLevel(`${numOfLeakedObjects} leaked objects`);
             }
             // cluster traces from the current run
-            const clusters = TraceBucket_1.default.clusterPaths(paths, snapshot, this.aggregateDominatorMetrics);
+            const clusters = TraceBucket_1.default.clusterPaths(paths, snapshot, this.aggregateDominatorMetrics, {
+                strategy: Config_1.default.isMLClustering
+                    ? new MLTraceSimilarityStrategy_1.default()
+                    : undefined,
+            });
             yield this.serializeClusterUpdate(clusters);
             if (Config_1.default.logUnclassifiedClusters) {
                 // cluster traces from the current run

package/dist/lib/NodeHeap.d.ts

@@ -22,7 +22,7 @@ import type { IHeapSnapshot } from './Types';
  * * **Examples**:
  * ```typescript
  * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
- * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ * import {config, takeNodeMinimalHeap, tagObject} from '@memlab/core';
  *
  * test('memory test', async () => {
  *   config.muteConsole = true;
@@ -36,7 +36,7 @@ import type { IHeapSnapshot } from './Types';
  *
  *   o2 = null;
  *
- *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *   const heap: IHeapSnapshot = await takeNodeMinimalHeap();
  *
  *   // expect object with marker "memlab-mark-1" exists
  *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
@@ -48,6 +48,26 @@ import type { IHeapSnapshot } from './Types';
  * ```
  */
 export declare function tagObject<T extends object>(o: T, tag: string): T;
+/**
+ * Take a heap snapshot of the current program state and save it as a
+ * `.heapsnapshot` file under a randomly generated folder inside the system's
+ * temp folder.
+ *
+ * **Note**: All `.heapsnapshot` files could also be loaded by Chrome DevTools.
+ * @returns the absolute file path to the saved `.heapsnapshot` file.
+ *
+ * * **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);
+ * })();
+ * ```
+ */
 export declare function dumpNodeHeapSnapshot(): string;
 /**
  * Take a heap snapshot of the current program state
@@ -57,19 +77,42 @@ export declare function dumpNodeHeapSnapshot(): string;
  *
  * @returns heap representation without heap analysis meta data.
  *
- * If you need to get the heap snapshot with heap analysis meta data
- * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
- * for example:
+ * @deprecated
+ * @internal
+ *
+ * If you need to get the heap snapshot with heap analysis meta data, please
+ * use {@link takeNodeFullHeap}.
+ * For example:
  * ```typescript
  * import type {IHeapSnapshot} from '@memlab/core';
- * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile} from '@memlab/heap-analysis';
+ * import {takeNodeFullHeap} from '@memlab/heap-analysis';
  *
  * (async function () {
- *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *   const heap: IHeapSnapshot = await takeNodeFullHeap();
  * })();
  * ```
  */
 export declare function getNodeInnocentHeap(): Promise<IHeapSnapshot>;
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. Notice that
+ * this API does not calculate some heap analysis meta data
+ * for heap analysis. But this also means faster heap parsing.
+ *
+ * @returns heap representation without heap analysis meta data.
+ *
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import {takeNodeMinimalHeap} from '@memlab/core';
+ *
+ * (async function () {
+ *   const heap: IHeapSnapshot = await takeNodeMinimalHeap();
+ * })();
+ * ```
+ *
+ * If you need to get the heap snapshot with heap analysis meta data, please
+ * use {@link getFullHeapFromFile}.
+ */
+export declare function takeNodeMinimalHeap(): Promise<IHeapSnapshot>;
 //# sourceMappingURL=NodeHeap.d.ts.map

package/dist/lib/NodeHeap.js

@@ -21,18 +21,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.tagObject = void 0;
+exports.takeNodeMinimalHeap = exports.getNodeInnocentHeap = exports.dumpNodeHeapSnapshot = exports.tagObject = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const v8_1 = __importDefault(require("v8"));
 const FileManager_1 = __importDefault(require("./FileManager"));
 const Utils_1 = __importDefault(require("./Utils"));
-class MemLabTaggedStore {
-    constructor() {
-        this.taggedObjects = Object.create(null);
-    }
-}
-const store = new MemLabTaggedStore();
+const MemLabTagStore_1 = __importDefault(require("./heap-data/MemLabTagStore"));
 /**
  * Tags a string marker to an object instance, which can later be checked by
  * {@link hasObjectWithTag}. This API does not modify the object instance in
@@ -47,7 +42,7 @@ const store = new MemLabTaggedStore();
  * * **Examples**:
  * ```typescript
  * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
- * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ * import {config, takeNodeMinimalHeap, tagObject} from '@memlab/core';
  *
  * test('memory test', async () => {
  *   config.muteConsole = true;
@@ -61,7 +56,7 @@ const store = new MemLabTaggedStore();
  *
  *   o2 = null;
  *
- *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *   const heap: IHeapSnapshot = await takeNodeMinimalHeap();
  *
  *   // expect object with marker "memlab-mark-1" exists
  *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
@@ -73,15 +68,36 @@ const store = new MemLabTaggedStore();
  * ```
  */
 function tagObject(o, tag) {
-    if (!store.taggedObjects[tag]) {
-        store.taggedObjects[tag] = new WeakSet();
-    }
-    store.taggedObjects[tag].add(o);
+    MemLabTagStore_1.default.tagObject(o, tag);
     return o;
 }
 exports.tagObject = tagObject;
+/**
+ * Take a heap snapshot of the current program state and save it as a
+ * `.heapsnapshot` file under a randomly generated folder inside the system's
+ * temp folder.
+ *
+ * **Note**: All `.heapsnapshot` files could also be loaded by Chrome DevTools.
+ * @returns the absolute file path to the saved `.heapsnapshot` file.
+ *
+ * * **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);
+ * })();
+ * ```
+ */
 function dumpNodeHeapSnapshot() {
-    const file = path_1.default.join(FileManager_1.default.generateTmpHeapDir(), `nodejs.heapsnapshot`);
+    const randomID = `Math.random()`.replace('0.', '');
+    const file = path_1.default.join(FileManager_1.default.generateTmpHeapDir(), `nodejs-${randomID}.heapsnapshot`);
+    if (fs_extra_1.default.existsSync(file)) {
+        fs_extra_1.default.removeSync(file);
+    }
     v8_1.default.writeHeapSnapshot(file);
     return file;
 }
@@ -94,17 +110,18 @@ exports.dumpNodeHeapSnapshot = dumpNodeHeapSnapshot;
  *
  * @returns heap representation without heap analysis meta data.
  *
- * If you need to get the heap snapshot with heap analysis meta data
- * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
- * for example:
+ * @deprecated
+ * @internal
+ *
+ * If you need to get the heap snapshot with heap analysis meta data, please
+ * use {@link takeNodeFullHeap}.
+ * For example:
  * ```typescript
  * import type {IHeapSnapshot} from '@memlab/core';
- * import {dumpNodeHeapSnapshot} from '@memlab/core';
- * import {getHeapFromFile} from '@memlab/heap-analysis';
+ * import {takeNodeFullHeap} from '@memlab/heap-analysis';
  *
  * (async function () {
- *   const heapFile = dumpNodeHeapSnapshot();
- *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ *   const heap: IHeapSnapshot = await takeNodeFullHeap();
  * })();
  * ```
  */
@@ -121,3 +138,37 @@ function getNodeInnocentHeap() {
     });
 }
 exports.getNodeInnocentHeap = getNodeInnocentHeap;
+/**
+ * Take a heap snapshot of the current program state
+ * and parse it as {@link IHeapSnapshot}. Notice that
+ * this API does not calculate some heap analysis meta data
+ * for heap analysis. But this also means faster heap parsing.
+ *
+ * @returns heap representation without heap analysis meta data.
+ *
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import {takeNodeMinimalHeap} from '@memlab/core';
+ *
+ * (async function () {
+ *   const heap: IHeapSnapshot = await takeNodeMinimalHeap();
+ * })();
+ * ```
+ *
+ * If you need to get the heap snapshot with heap analysis meta data, please
+ * use {@link getFullHeapFromFile}.
+ */
+function takeNodeMinimalHeap() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const file = dumpNodeHeapSnapshot();
+        const snapshot = yield Utils_1.default.getSnapshotFromFile(file, {
+            buildNodeIdIndex: true,
+        });
+        fs_extra_1.default.unlink(file, () => {
+            // do nothing
+        });
+        return snapshot;
+    });
+}
+exports.takeNodeMinimalHeap = takeNodeMinimalHeap;

package/dist/lib/PackageInfoLoader.d.ts

@@ -0,0 +1,7 @@
+/** @internal */
+export declare class PackageInfoLoader {
+    private static registeredPackages;
+    private static loadFrom;
+    static registerPackage(packageDirectory: string): Promise<void>;
+}
+//# sourceMappingURL=PackageInfoLoader.d.ts.map

package/dist/lib/PackageInfoLoader.js

@@ -0,0 +1,66 @@
+"use strict";
+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.PackageInfoLoader = void 0;
+/**
+ * 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
+ */
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const Config_1 = __importDefault(require("./Config"));
+const Utils_1 = __importDefault(require("./Utils"));
+/** @internal */
+class PackageInfoLoader {
+    static loadFrom(packageDirectory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            let exists = yield fs_extra_1.default.pathExists(packageDirectory);
+            if (!exists) {
+                throw Utils_1.default.haltOrThrow(`package directory doesn't exist: ${packageDirectory}`);
+            }
+            let packageJSONFile = path_1.default.join(packageDirectory, 'package-oss.json');
+            exists = yield fs_extra_1.default.pathExists(packageJSONFile);
+            if (!exists) {
+                packageJSONFile = path_1.default.join(packageDirectory, 'package.json');
+            }
+            exists = yield fs_extra_1.default.pathExists(packageJSONFile);
+            if (!exists) {
+                throw Utils_1.default.haltOrThrow(`package.json doesn't exist: ${packageJSONFile}`);
+            }
+            try {
+                const metaData = yield fs_extra_1.default.readJSON(packageJSONFile, 'UTF-8');
+                return Object.assign(Object.assign({}, metaData), { packageLocation: packageDirectory });
+            }
+            catch (ex) {
+                throw Utils_1.default.haltOrThrow(Utils_1.default.getError(ex));
+            }
+        });
+    }
+    static registerPackage(packageDirectory) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!PackageInfoLoader.registeredPackages.has(packageDirectory)) {
+                PackageInfoLoader.registeredPackages.add(packageDirectory);
+                const packageInfo = yield PackageInfoLoader.loadFrom(packageDirectory);
+                Config_1.default.packageInfo.push(packageInfo);
+            }
+        });
+    }
+}
+exports.PackageInfoLoader = PackageInfoLoader;
+PackageInfoLoader.registeredPackages = new Set();