@memlab/core 1.1.5 → 1.1.9

package/dist/lib/NodeHeap.d.ts

@@ -4,8 +4,8 @@
  * 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
+ * @oncall ws_labs
  */
 import type { IHeapSnapshot } from './Types';
 /**
@@ -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

@@ -5,8 +5,8 @@
  * 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
+ * @oncall ws_labs
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -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.js

@@ -19,8 +19,8 @@ exports.PackageInfoLoader = void 0;
  * 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
+ * @oncall ws_labs
  */
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -57,7 +57,7 @@ class PackageInfoLoader {
             if (!PackageInfoLoader.registeredPackages.has(packageDirectory)) {
                 PackageInfoLoader.registeredPackages.add(packageDirectory);
                 const packageInfo = yield PackageInfoLoader.loadFrom(packageDirectory);
-                Config_1.default._packageInfo.push(packageInfo);
+                Config_1.default.packageInfo.push(packageInfo);
             }
         });
     }

package/dist/lib/ProcessManager.d.ts

@@ -4,8 +4,8 @@
  * 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
+ * @oncall ws_labs
  */
 import type { Command, Optional } from './Types';
 declare type Options = {

package/dist/lib/ProcessManager.js

@@ -5,8 +5,8 @@
  * 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
+ * @oncall ws_labs
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };

package/dist/lib/Serializer.d.ts

@@ -4,8 +4,8 @@
  * 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
+ * @oncall ws_labs
  */
 import { E2EStepInfo, HeapNodeIdSet, IHeapEdge, IHeapNode, IHeapSnapshot, ISerializedInfo, LeakTracePathItem, Nullable } from './Types';
 declare type JSONifyArgs = {

package/dist/lib/Serializer.js

@@ -5,8 +5,8 @@
  * 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
+ * @oncall ws_labs
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -99,7 +99,7 @@ function JSONifyDetachedHTMLElement(node, args, options) {
     // options for elem.__reactProps$xxx
     const propsOptions = Object.assign({}, options);
     propsOptions.forceJSONifyDepth = 1;
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         if (Utils_1.default.isReactFiberEdge(edge)) {
             info[key] = JSONifyNode(edge.toNode, args, fiberOptions);
@@ -110,7 +110,8 @@ function JSONifyDetachedHTMLElement(node, args, options) {
         else {
             info[key] = JSONifyNodeInShort(edge.toNode);
         }
-    }
+        return null;
+    });
     return info;
 }
 function calculateReturnTrace(node, cache) {
@@ -128,15 +129,16 @@ function calculateReturnTrace(node, cache) {
 const objectNodeUsefulProps = new Set(['_context']);
 function JSONifyNodeOneLevel(node) {
     const info = Object.create(null);
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         info[key] = JSONifyNodeShallow(edge.toNode);
-    }
+        return null;
+    });
     return info;
 }
 function JSONifyNodeShallow(node) {
     const info = Object.create(null);
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         if (objectNodeUsefulProps.has(edge.name_or_index)) {
             info[key] = JSONifyNodeShallow(edge.toNode);
@@ -144,7 +146,8 @@ function JSONifyNodeShallow(node) {
         else {
             info[key] = JSONifyNodeInShort(edge.toNode);
         }
-    }
+        return null;
+    });
     return info;
 }
 const fiberNodeUsefulProps = new Set([
@@ -154,15 +157,17 @@ const fiberNodeUsefulProps = new Set([
 ]);
 function JSONifyFiberNodeShallow(node) {
     const info = Object.create(null);
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         if (fiberNodeUsefulProps.has(edge.name_or_index) &&
             Utils_1.default.isObjectNode(edge.toNode)) {
             info[key] = JSONifyNodeShallow(edge.toNode);
-            continue;
         }
-        info[key] = JSONifyNodeInShort(edge.toNode);
-    }
+        else {
+            info[key] = JSONifyNodeInShort(edge.toNode);
+        }
+        return null;
+    });
     return info;
 }
 // calculate the summary of return chain of the FiberNode
@@ -187,7 +192,9 @@ function JSONifyFiberNodeReturnTrace(node, args, options) {
         }
         const parentInfo = getNodeNameInJSON(parent, args);
         key = `${key}:  --return (property)--->  ${parentInfo}`;
-        const info = JSONifyFiberNodeShallow(parent);
+        const info = Config_1.default.includeObjectInfoInTraceReturnChain
+            ? JSONifyFiberNodeShallow(parent)
+            : Object.create(null);
         trace[key] = info;
     }
     return trace;
@@ -206,25 +213,27 @@ function JSONifyFiberNode(node, args, options) {
         propsOptions.forceJSONifyDepth = 1;
     }
     propsOptions.forceJSONifyDepth--;
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         info[key] =
-            propsOptions.forceJSONifyDepth >= 1
+            propsOptions.forceJSONifyDepth && propsOptions.forceJSONifyDepth >= 1
                 ? JSONifyNode(edge.toNode, args, propsOptions)
                 : JSONifyNodeInShort(edge.toNode);
-    }
+        return null;
+    });
     return info;
 }
 function JSONifyClosure(node, args, options) {
     const info = Object.create(null);
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         if (edge.name_or_index === 'shared' ||
             edge.name_or_index === 'context' ||
             edge.name_or_index === 'displayName') {
             const key = filterJSONPropName(edge.name_or_index);
             info[key] = JSONifyNode(edge.toNode, args, options);
         }
-    }
+        return null;
+    });
     return info;
 }
 function JSONifyNumberNode(node, 
@@ -238,7 +247,7 @@ _options) {
 }
 function JSONifyCode(node, args, options) {
     const info = Object.create(null);
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         if (edge.name_or_index === 'name_or_scope_info' &&
             edge.toNode.name === '(function scope info)') {
             const key = 'variables with non-number values in closure scope chain';
@@ -251,14 +260,15 @@ function JSONifyCode(node, args, options) {
             const key = filterJSONPropName(edge.name_or_index);
             info[key] = JSONifyNode(edge.toNode, args, options);
         }
-    }
+        return null;
+    });
     return info;
 }
 function JSONifyContext(node, args, options) {
     const info = Object.create(null);
     const key = 'variables in scope (used by nested closures)';
     const closure_vars = (info[key] = Object.create(null));
-    for (const edge of node.references) {
+    iterateSelectedEdges(node, (edge) => {
         const key = filterJSONPropName(edge.name_or_index);
         if (edge.type === 'context') {
             closure_vars[key] = JSONifyNodeInShort(edge.toNode);
@@ -266,15 +276,27 @@ function JSONifyContext(node, args, options) {
         else if (edge.type === '') {
             info[key] = JSONifyNode(edge.toNode, args, options);
         }
-    }
+        return null;
+    });
     return info;
 }
+function iterateSelectedEdges(node, callback) {
+    let edgesProcessed = 0;
+    node.forEachReference((edge) => {
+        if (edge.type === 'internal') {
+            if (edge.name_or_index === 'map' || edge.is_index) {
+                return;
+            }
+        }
+        if (edgesProcessed++ > 100) {
+            return { stop: true };
+        }
+        return callback(edge);
+    });
+}
 function JSONifyOrdinaryValue(node, args, options) {
     const info = Object.create(null);
-    for (const edge of node.references) {
-        if (edge.name_or_index === 'map' && edge.type === 'internal') {
-            continue;
-        }
+    iterateSelectedEdges(node, (edge) => {
         const key = JSONifyEdgeNameAndType(edge);
         const toNode = edge.toNode;
         const toNodeName = toNode.name;
@@ -293,7 +315,8 @@ function JSONifyOrdinaryValue(node, args, options) {
         else {
             info[key] = JSONifyNodeInShort(toNode);
         }
-    }
+        return null;
+    });
     return info;
 }
 function JSONifyNode(node, args, options) {

package/dist/lib/StringLoader.d.ts

@@ -4,9 +4,9 @@
  * 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
- * @lightSyntaxTransform
  * @format
+ * @lightSyntaxTransform
+ * @oncall ws_labs
  */
 /// <reference types="node" />
 declare type ReadFileOptions = {

package/dist/lib/StringLoader.js

@@ -4,9 +4,9 @@
  * 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
- * @lightSyntaxTransform
  * @format
+ * @lightSyntaxTransform
+ * @oncall ws_labs
  */
 'use strict';
 var __importDefault = (this && this.__importDefault) || function (mod) {