@memlab/core 1.1.0 → 1.1.3

package/README.md

@@ -2,5 +2,6 @@
 
 This is the memlab core library. It contains V8/Hermes heap snapshot parser, core algorithms, leak trace clustering, utilities, and config.
 
-## 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/__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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     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.getCurrentNodeHeap)();
+    const heap = yield (0, NodeHeap_1.getNodeInnocentHeap)();
     expect(checker(heap)).toBe(true);
 }), timeout);

package/dist/lib/Config.d.ts

@@ -171,6 +171,7 @@ export declare class MemLabConfig {
     clusterRetainedSizeThreshold: number;
     _isFullRun: boolean;
     _scenario: Optional<IScenario>;
+    _isHeadfulBrowser: boolean;
     externalLeakFilter?: Optional<ILeakFilter>;
     monoRepoDir: string;
     muteConsole: boolean;
@@ -192,6 +193,8 @@ export declare class MemLabConfig {
     get isFullRun(): boolean;
     set browser(v: string);
     get browser(): string;
+    set isHeadfulBrowser(isHeadful: boolean);
+    get isHeadfulBrowser(): boolean;
     get browserBinaryPath(): string;
     set reportLeaksInTimers(flag: boolean);
     get reportLeaksInTimers(): boolean;

package/dist/lib/Config.js

@@ -54,6 +54,7 @@ class MemLabConfig {
         this._deviceManualOverridden = false;
         this._timerNodes = ['Pending activities'];
         this._timerEdges = [];
+        this._isHeadfulBrowser = false;
         this.targetApp = Constant_1.default.unset;
         this.targetTab = Constant_1.default.unset;
         this.analysisMode = Constant_1.default.unset;
@@ -66,6 +67,7 @@ class MemLabConfig {
         this.specifiedEngine = false;
         // set puppeteer configuration
         this.puppeteerConfig = {
+            headless: !this._isHeadfulBrowser,
             devtools: this.openDevtoolsConsole,
             // IMPORTANT: test ContinuousTest before change this config
             ignoreHTTPSErrors: true,
@@ -358,6 +360,17 @@ class MemLabConfig {
     get browser() {
         return this._browser || 'google-chrome';
     }
+    set isHeadfulBrowser(isHeadful) {
+        this._isHeadfulBrowser = isHeadful;
+        this.puppeteerConfig.headless = !isHeadful;
+        if (isHeadful) {
+            // if running in headful mode
+            this.disableXvfb();
+        }
+    }
+    get isHeadfulBrowser() {
+        return this._isHeadfulBrowser;
+    }
     get browserBinaryPath() {
         return path_1.default.join(this.browserDir, this.browser);
     }

package/dist/lib/Console.d.ts

@@ -61,6 +61,7 @@ declare class MemLabConsole {
     progress(cur: number, total: number, options?: {
         message?: string;
     }): void;
+    flush(): void;
 }
 declare const _default: MemLabConsole;
 export default _default;

package/dist/lib/Console.js

@@ -340,5 +340,8 @@ class MemLabConsole {
         const progress = `${message}: |${bar}| ${percent}/100`;
         this.overwrite(progress, { level: 'top' });
     }
+    flush() {
+        this.clearPrevOverwriteMsg();
+    }
 }
 exports.default = MemLabConsole.getInstance();

package/dist/lib/Constant.js

@@ -13,8 +13,8 @@ const InternalValueSetter_1 = require("./InternalValueSetter");
 const constants = {
     isFB: false,
     isFRL: false,
-    defaultEngine: 'v8',
-    supportedEngines: ['v8', 'hermes'],
+    defaultEngine: 'V8',
+    supportedEngines: ['V8', 'hermes'],
     supportedBrowsers: Object.create(null),
     internalDir: 'fb-internal',
     monoRepoDir: '',

package/dist/lib/FileManager.d.ts

@@ -43,6 +43,8 @@ export declare class FileManager {
     getAllFilesInDir(dir: string): string[];
     getDataOutDir(options?: FileOption): string;
     getCoreProjectBaseDir(): string;
+    getMonoRepoDir(): string;
+    getDocDir(): string;
     getReportOutDir(options?: FileOption): string;
     getPreviewReportDir(options?: FileOption): string;
     getLeakSummaryFile(options?: FileOption): string;

package/dist/lib/FileManager.js

@@ -133,6 +133,12 @@ class FileManager {
     getCoreProjectBaseDir() {
         return path_1.default.join(__dirname, '..', '..');
     }
+    getMonoRepoDir() {
+        return path_1.default.join(this.getCoreProjectBaseDir(), '..', '..');
+    }
+    getDocDir() {
+        return path_1.default.join(this.getMonoRepoDir(), 'website', 'docs');
+    }
     getReportOutDir(options = {}) {
         return path_1.default.join(this.getPersistDataDir(options), 'reports');
     }

package/dist/lib/HeapParser.js

@@ -102,7 +102,7 @@ function identifyAndSetEngine(snapshot) {
         return; // skip if engine type is manually set
     }
     Console_1.default.overwrite('identifying snapshot engine...');
-    let engine = 'v8';
+    let engine = 'V8';
     snapshot.nodes.forEach((node) => {
         if (node.type === 'object' && node.name.startsWith('Object(')) {
             engine = 'hermes';

package/dist/lib/NodeHeap.d.ts

@@ -7,10 +7,69 @@
  * @emails oncall+ws_labs
  * @format
  */
-import type { AnyValue, IHeapSnapshot } from './Types';
-declare type AnyObject = Record<AnyValue, AnyValue>;
-export declare function tagObject(o: AnyObject, tag: string): AnyObject;
+import type { IHeapSnapshot } from './Types';
+/**
+ * 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
+ * any way (e.g., no additional or hidden properties added to the tagged
+ * object).
+ *
+ * @param o specify the object instance you want to tag, you cannot tag a
+ * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+ * @param tag marker name to tag on the object instance
+ * @returns returns the tagged object instance (same reference as
+ * the input argument `o`)
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
+ * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ *
+ * test('memory test', async () => {
+ *   config.muteConsole = true;
+ *   const o1: AnyValue = {};
+ *   let o2: AnyValue = {};
+ *
+ *   // tag o1 with marker: "memlab-mark-1", does not modify o1 in any way
+ *   tagObject(o1, 'memlab-mark-1');
+ *   // tag o2 with marker: "memlab-mark-2", does not modify o2 in any way
+ *   tagObject(o2, 'memlab-mark-2');
+ *
+ *   o2 = null;
+ *
+ *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *
+ *   // expect object with marker "memlab-mark-1" exists
+ *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+ *
+ *   // expect object with marker "memlab-mark-2" can be GCed
+ *   expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+ *
+ * }, 30000);
+ * ```
+ */
+export declare function tagObject<T extends object>(o: T, tag: string): T;
 export declare function dumpNodeHeapSnapshot(): string;
-export declare function getCurrentNodeHeap(): Promise<IHeapSnapshot>;
-export {};
+/**
+ * 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.
+ *
+ * If you need to get the heap snapshot with heap analysis meta data
+ * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
+ * for example:
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ * })();
+ * ```
+ */
+export declare function getNodeInnocentHeap(): Promise<IHeapSnapshot>;
 //# sourceMappingURL=NodeHeap.d.ts.map

package/dist/lib/NodeHeap.js

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getCurrentNodeHeap = exports.dumpNodeHeapSnapshot = exports.tagObject = void 0;
+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"));
@@ -33,6 +33,45 @@ class MemLabTaggedStore {
     }
 }
 const store = new MemLabTaggedStore();
+/**
+ * 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
+ * any way (e.g., no additional or hidden properties added to the tagged
+ * object).
+ *
+ * @param o specify the object instance you want to tag, you cannot tag a
+ * [primitive](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+ * @param tag marker name to tag on the object instance
+ * @returns returns the tagged object instance (same reference as
+ * the input argument `o`)
+ * * **Examples**:
+ * ```typescript
+ * import type {IHeapSnapshot, AnyValue} from '@memlab/core';
+ * import {config, getNodeInnocentHeap, tagObject} from '@memlab/core';
+ *
+ * test('memory test', async () => {
+ *   config.muteConsole = true;
+ *   const o1: AnyValue = {};
+ *   let o2: AnyValue = {};
+ *
+ *   // tag o1 with marker: "memlab-mark-1", does not modify o1 in any way
+ *   tagObject(o1, 'memlab-mark-1');
+ *   // tag o2 with marker: "memlab-mark-2", does not modify o2 in any way
+ *   tagObject(o2, 'memlab-mark-2');
+ *
+ *   o2 = null;
+ *
+ *   const heap: IHeapSnapshot = await getNodeInnocentHeap();
+ *
+ *   // expect object with marker "memlab-mark-1" exists
+ *   expect(heap.hasObjectWithTag('memlab-mark-1')).toBe(true);
+ *
+ *   // expect object with marker "memlab-mark-2" can be GCed
+ *   expect(heap.hasObjectWithTag('memlab-mark-2')).toBe(false);
+ *
+ * }, 30000);
+ * ```
+ */
 function tagObject(o, tag) {
     if (!store.taggedObjects[tag]) {
         store.taggedObjects[tag] = new WeakSet();
@@ -47,7 +86,29 @@ function dumpNodeHeapSnapshot() {
     return file;
 }
 exports.dumpNodeHeapSnapshot = dumpNodeHeapSnapshot;
-function getCurrentNodeHeap() {
+/**
+ * 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.
+ *
+ * If you need to get the heap snapshot with heap analysis meta data
+ * use {@link dumpNodeHeapSnapshot} and {@link getHeapFromFile},
+ * for example:
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function () {
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap: IHeapSnapshot = await getHeapFromFile(heapFile);
+ * })();
+ * ```
+ */
+function getNodeInnocentHeap() {
     return __awaiter(this, void 0, void 0, function* () {
         const file = dumpNodeHeapSnapshot();
         const snapshot = yield Utils_1.default.getSnapshotFromFile(file, {
@@ -59,4 +120,4 @@ function getCurrentNodeHeap() {
         return snapshot;
     });
 }
-exports.getCurrentNodeHeap = getCurrentNodeHeap;
+exports.getNodeInnocentHeap = getNodeInnocentHeap;

package/dist/lib/Serializer.js

@@ -182,6 +182,9 @@ function JSONifyFiberNodeReturnTrace(node, args, options) {
             continue;
         }
         const parent = node.snapshot.nodes.get(index);
+        if (!parent) {
+            continue;
+        }
         const parentInfo = getNodeNameInJSON(parent, args);
         key = `${key}:  --return (property)--->  ${parentInfo}`;
         const info = JSONifyFiberNodeShallow(parent);
@@ -593,7 +596,7 @@ function summarizeNode(node, options = {}) {
     let nodeImpact = '';
     if (nodeRetainSize) {
         nodeImpact = options.color
-            ? chalk_1.default.grey('[') + chalk_1.default.blue(nodeRetainSize) + chalk_1.default.grey(']')
+            ? chalk_1.default.grey('[') + chalk_1.default.blue.bold(nodeRetainSize) + chalk_1.default.grey(']')
             : `[${nodeRetainSize}]`;
     }
     const name = summarizeNodeName(node, options);