@memlab/heap-analysis 1.0.1 → 1.0.4

package/README.md

@@ -1,7 +1,8 @@
 ## memlab Heap Analysis
 
-This is the memlab heap analysis library. It contains all memlab built-in heap analysis and 
+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.d.ts

@@ -11,15 +11,92 @@ import type { AnyValue } from '@memlab/core';
 import type { HeapAnalysisOptions } from './PluginUtils';
 import { BaseOption } from '@memlab/core';
 declare abstract class Analysis {
-    protected process(_options: HeapAnalysisOptions): Promise<AnyValue>;
-    run(options?: HeapAnalysisOptions): Promise<AnyValue>;
-    analyzeSnapshotFromFile(file: string): Promise<AnyValue>;
-    analyzeSnapshotsInDirectory(directory: string): Promise<AnyValue>;
+    process(_options: HeapAnalysisOptions): Promise<void>;
+    /**
+     * DO NOT override this method if you are implementing your own analysis
+     * by extending {@link BaseAnalysis}.
+     * @param options This is the auto-generated arguments passed to all the
+     * `process` method that your self-defined heap analysis should implement.
+     * You are not supposed to construct instances of this class.
+     * @returns any type of value returned from the overridden `process` method
+     * of the heap analysis instance. Each heap analysis class can define
+     * different return value format.
+     * @internal
+     */
+    run(options?: HeapAnalysisOptions): Promise<void>;
+    /**
+     * Run heap analysis for a single heap snapshot file
+     * @param file the absolute path of a `.heapsnapshot` file.
+     * @returns this API returns void. To get the analysis results,
+     * check out the documentation of the hosting heap analysis class and
+     * call the analysis-specific API to get results after calling this method.
+     * * **Example**:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
+     * ```
+     */
+    analyzeSnapshotFromFile(file: string): Promise<void>;
+    /**
+     * Run heap analysis for a series of heap snapshot files
+     * @param directory the absolute path of the directory holding a series of
+     * `.heapsnapshot` files, all snapshot files will be loaded and analyzed
+     * in the alphanumerically ascending order of those snapshot file names.
+     * @returns this API returns void. To get the analysis results,
+     * check out the documentation of the hosting heap analysis class and
+     * call the analysis-specific API to get results after calling this method.
+     * * **Example**:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * const shapes = analysis.getShapesWithUnboundGrowth();
+     * ```
+     */
+    analyzeSnapshotsInDirectory(directory: string): Promise<void>;
 }
+/**
+ *
+ */
 declare class BaseAnalysis extends Analysis {
+    /**
+     * Get the name of the heap analysis, which is also used to reference
+     * the analysis in memlab command-line tool.
+     *
+     * The following terminal command will initiate with this analysis:
+     * `memlab analyze <ANALYSIS_NAME>`
+     *
+     * @returns the name of the analysis
+     * * **Examples**:
+     * ```typescript
+     * const analysis = new YourAnalysis();
+     * const name = analysis.getCommandName();
+     * ```
+     */
     getCommandName(): string;
+    /**
+     * Get the textual description of the heap analysis.
+     * The description of this analysis will be printed by:
+     * `memlab analyze list`
+     *
+     * @returns the description
+     */
     getDescription(): string;
-    protected process(_options: HeapAnalysisOptions): Promise<AnyValue>;
+    /**
+     * Callback for `memlab analyze <command-name>`.
+     * Do the memory analysis and print results in this callback
+     * The analysis should support:
+     *  1) printing results on screen
+     *  2) returning results via the return value
+     * @param options This is the auto-generated arguments passed to all the
+     * `process` method that your self-defined heap analysis should implement.
+     * You are not supposed to construct instances of this class.
+     */
+    process(options: HeapAnalysisOptions): Promise<AnyValue>;
+    /**
+     * override this method if you would like CLI to print the option info
+     * @returns an array of command line options
+     */
     getOptions(): BaseOption[];
 }
 export default BaseAnalysis;

package/dist/BaseAnalysis.js

@@ -48,13 +48,36 @@ class Analysis {
             throw new Error(`${className}.process is not implemented`);
         });
     }
-    // DO NOT override this method
+    /**
+     * DO NOT override this method if you are implementing your own analysis
+     * by extending {@link BaseAnalysis}.
+     * @param options This is the auto-generated arguments passed to all the
+     * `process` method that your self-defined heap analysis should implement.
+     * You are not supposed to construct instances of this class.
+     * @returns any type of value returned from the overridden `process` method
+     * of the heap analysis instance. Each heap analysis class can define
+     * different return value format.
+     * @internal
+     */
     run(options = PluginUtils_1.default.defaultAnalysisArgs) {
         return __awaiter(this, void 0, void 0, function* () {
             loadScenarioConfig();
             return yield this.process(options);
         });
     }
+    /**
+     * Run heap analysis for a single heap snapshot file
+     * @param file the absolute path of a `.heapsnapshot` file.
+     * @returns this API returns void. To get the analysis results,
+     * check out the documentation of the hosting heap analysis class and
+     * call the analysis-specific API to get results after calling this method.
+     * * **Example**:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
+     * ```
+     */
     analyzeSnapshotFromFile(file) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.process({
@@ -66,6 +89,21 @@ class Analysis {
             });
         });
     }
+    /**
+     * Run heap analysis for a series of heap snapshot files
+     * @param directory the absolute path of the directory holding a series of
+     * `.heapsnapshot` files, all snapshot files will be loaded and analyzed
+     * in the alphanumerically ascending order of those snapshot file names.
+     * @returns this API returns void. To get the analysis results,
+     * check out the documentation of the hosting heap analysis class and
+     * call the analysis-specific API to get results after calling this method.
+     * * **Example**:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * const shapes = analysis.getShapesWithUnboundGrowth();
+     * ```
+     */
     analyzeSnapshotsInDirectory(directory) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.process({
@@ -78,33 +116,61 @@ class Analysis {
         });
     }
 }
+/**
+ *
+ */
 class BaseAnalysis extends Analysis {
-    // The following terminal command will initiate with this analysis
-    // `memlab analyze <command-name>`
+    /**
+     * Get the name of the heap analysis, which is also used to reference
+     * the analysis in memlab command-line tool.
+     *
+     * The following terminal command will initiate with this analysis:
+     * `memlab analyze <ANALYSIS_NAME>`
+     *
+     * @returns the name of the analysis
+     * * **Examples**:
+     * ```typescript
+     * const analysis = new YourAnalysis();
+     * const name = analysis.getCommandName();
+     * ```
+     */
     getCommandName() {
         const className = this.constructor.name;
         throw new Error(`${className}.getCommandName is not implemented`);
     }
-    // The description of this analysis will be printed by
-    // `memlab analyze list`
+    /**
+     * Get the textual description of the heap analysis.
+     * The description of this analysis will be printed by:
+     * `memlab analyze list`
+     *
+     * @returns the description
+     */
     getDescription() {
         const className = this.constructor.name;
         throw new Error(`${className}.getDescription is not implemented`);
     }
-    // Callback for `memlab analyze <command-name>`
-    // Do the memory analysis and print results in this callback
-    // The analysis should support:
-    //  1) printing results on screen
-    //  2) returning results via the return value
+    /**
+     * Callback for `memlab analyze <command-name>`.
+     * Do the memory analysis and print results in this callback
+     * The analysis should support:
+     *  1) printing results on screen
+     *  2) returning results via the return value
+     * @param options This is the auto-generated arguments passed to all the
+     * `process` method that your self-defined heap analysis should implement.
+     * You are not supposed to construct instances of this class.
+     */
     process(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    _options) {
+    options) {
         return __awaiter(this, void 0, void 0, function* () {
             const className = this.constructor.name;
             throw new Error(`${className}.process is not implemented`);
         });
     }
-    // override this method if you would like CLI to print the option info
+    /**
+     * override this method if you would like CLI to print the option info
+     * @returns an array of command line options
+     */
     getOptions() {
         return [];
     }

package/dist/PluginUtils.d.ts

@@ -9,11 +9,22 @@
  */
 import type { ParsedArgs } from 'minimist';
 import { IHeapSnapshot, IHeapNode, AnyOptions, IHeapEdge, Nullable, MemLabConfig } from '@memlab/core';
+declare function isNodeWorthInspecting(node: IHeapNode): boolean;
+/**
+ * This is the auto-generated arguments passed to all the `process` method
+ * that your self-defined heap analysis should implement.
+ * You are not supposed to construct instances of this class.
+ *
+ * For code examples on how this options could be used, see
+ * {@link getSnapshotFileForAnalysis}, {@link loadHeapSnapshot},
+ * or {@link snapshotMapReduce}.
+ */
 export declare type HeapAnalysisOptions = {
+    /** @internal */
     args: ParsedArgs;
+    /** @internal */
     config?: MemLabConfig;
 };
-declare function isNodeWorthInspecting(node: IHeapNode): boolean;
 declare type PrintNodeOption = {
     indent?: string;
     printReferences?: boolean;
@@ -21,11 +32,264 @@ declare type PrintNodeOption = {
 declare function printNodeListInTerminal(nodeList: IHeapNode[], options?: AnyOptions & PrintNodeOption): void;
 declare function printReferencesInTerminal(edgeList: IHeapEdge[], options?: AnyOptions & PrintNodeOption): void;
 declare function getObjectOutgoingEdgeCount(node: IHeapNode): number;
+/**
+ * Get the heap snapshot file's absolute path passed to the hosting heap
+ * analysis via `HeapAnalysisOptions`.
+ *
+ * This API is supposed to be used within the overridden `process` method
+ * of an `BaseAnalysis` instance.
+ *
+ * @param options this is the auto-generated input passed to all the `BaseAnalysis` instances
+ * @returns the absolute path of the heap snapshot file
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {HeapAnalysisOptions} from '@memlab/heap-analysis';
+ * import {getSnapshotFileForAnalysis, BaseAnalysis} from '@memlab/heap-analysis';
+ *
+ * class ExampleAnalysis extends BaseAnalysis {
+ *   public getCommandName(): string {
+ *     return 'example-analysis';
+ *   }
+ *
+ *   public getDescription(): string {
+ *     return 'an example analysis for demo';
+ *   }
+ *
+ *   async process(options: HeapAnalysisOptions): Promise<void> {
+ *     const file = getSnapshotFileForAnalysis(options);
+ *   }
+ * }
+ * ```
+ *
+ * Use the following code to invoke the heap analysis:
+ * ```typescript
+ * const analysis = new ExampleAnalysis();
+ * // any .heapsnapshot file recorded by memlab or saved manually from Chrome
+ * await analysis.analyzeSnapshotFromFile(snapshotFile);
+ * ```
+ * The new heap analysis can also be used with {@link analyze}, in that case
+ * `getSnapshotFileForAnalysis` will use the last heap snapshot in alphanumerically
+ * ascending order from {@link BrowserInteractionResultReader}.
+ */
 declare function getSnapshotFileForAnalysis(options: HeapAnalysisOptions): string;
+/**
+ * Get the absolute path of the directory holding all the heap snapshot files
+ * passed to the hosting heap analysis via `HeapAnalysisOptions`.
+ *
+ * This API is supposed to be used within the overridden `process` method
+ * of an `BaseAnalysis` instance.
+ *
+ * @param options this is the auto-generated input passed
+ * to all the `BaseAnalysis` instances
+ * @returns the absolute path of the directory
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {HeapAnalysisOptions} from '@memlab/heap-analysis';
+ * import {getSnapshotFileForAnalysis, BaseAnalysis} from '@memlab/heap-analysis';
+ *
+ * class ExampleAnalysis extends BaseAnalysis {
+ *   public getCommandName(): string {
+ *     return 'example-analysis';
+ *   }
+ *
+ *   public getDescription(): string {
+ *     return 'an example analysis for demo';
+ *   }
+ *
+ *   async process(options: HeapAnalysisOptions): Promise<void> {
+ *     const directory = getSnapshotDirForAnalysis(options);
+ *   }
+ * }
+ * ```
+ *
+ * Use the following code to invoke the heap analysis:
+ * ```typescript
+ * const analysis = new ExampleAnalysis();
+ * // any .heapsnapshot file recorded by memlab or saved manually from Chrome
+ * await analysis.analyzeSnapshotFromFile(snapshotFile);
+ * ```
+ * The new heap analysis can also be used with {@link analyze}, in that case
+ * `getSnapshotDirForAnalysis` use the snapshot directory from
+ * {@link BrowserInteractionResultReader}.
+ */
 declare function getSnapshotDirForAnalysis(options: HeapAnalysisOptions): Nullable<string>;
+/**
+ * Load the heap graph based on the single JavaScript heap snapshot
+ * passed to the hosting heap analysis via `HeapAnalysisOptions`.
+ *
+ * This API is supposed to be used within the `process` implementation
+ * of an `BaseAnalysis` instance.
+ *
+ * @param options this is the auto-generated input passed to all the `BaseAnalysis` instances
+ * @returns the graph representation of the heap
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {HeapAnalysisOptions} from '@memlab/heap-analysis';
+ * import {loadHeapSnapshot, BaseAnalysis} from '@memlab/heap-analysis';
+ *
+ * class ExampleAnalysis extends BaseAnalysis {
+ *   public getCommandName(): string {
+ *     return 'example-analysis';
+ *   }
+ *
+ *   public getDescription(): string {
+ *     return 'an example analysis for demo';
+ *   }
+ *
+ *   async process(options: HeapAnalysisOptions): Promise<void> {
+ *     const heap = await loadHeapSnapshot(options);
+ *     // doing heap analysis
+ *   }
+ * }
+ * ```
+ *
+ * Use the following code to invoke the heap analysis:
+ * ```typescript
+ * const analysis = new ExampleAnalysis();
+ * // any .heapsnapshot file recorded by memlab or saved manually from Chrome
+ * await analysis.analyzeSnapshotFromFile(snapshotFile);
+ * ```
+ * The new heap analysis can also be used with {@link analyze}, in that case
+ * `loadHeapSnapshot` will use the last heap snapshot in alphanumerically
+ * ascending order from {@link BrowserInteractionResultReader}.
+ */
 declare function loadHeapSnapshot(options: HeapAnalysisOptions): Promise<IHeapSnapshot>;
+/**
+ * Load and parse a `.heapsnapshot` file and calculate meta data like
+ * dominator nodes and retained sizes.
+ * @param file the absolute path of the `.heapsnapshot` file
+ * @returns the heap graph representation instance that supports querying
+ * the heap
+ * * **Examples**:
+ * ```typescript
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile} from '@memlab/heap-analysis';
+ *
+ * (async function (){
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap = await getHeapFromFile(heapFile);
+ * })();
+ * ```
+ */
+declare function getHeapFromFile(file: string): Promise<IHeapSnapshot>;
+/**
+ * When a heap analysis is taking multiple heap snapshots as input for memory
+ * analysis (e.g., finding which object keeps growing in size in a series of
+ * heap snapshots), this API could be used to do
+ * [MapRedue](https://en.wikipedia.org/wiki/MapReduce) on all heap snapshots.
+ *
+ * This API is supposed to be used within the `process` implementation
+ * of an `BaseAnalysis` instance that is designed to analyze multiple heap
+ * snapshots (as an example, finding which object keeps growing overtime)
+ *
+ * @param mapCallback the map function in MapReduce, the function will be applied
+ * to each heap snapshot
+ * @param reduceCallback the reduce function in MapReduce, the function will take
+ * as input all intermediate results from all map function calls
+ * @typeParam T1 - the type of the intermediate result from each map function call
+ * @typeParam T2 - the type of the final result of the reduce function call
+ * @param options this is the auto-generated input passed to all the `BaseAnalysis` instances
+ * @returns the return value of your reduce function
+ * * **Examples:**
+ * ```typescript
+ * import type {IHeapSnapshot} from '@memlab/core';
+ * import type {HeapAnalysisOptions} from '@memlab/heap-analysis';
+ * import {snapshotMapReduce, BaseAnalysis} from '@memlab/heap-analysis';
+ *
+ * class ExampleAnalysis extends BaseAnalysis {
+ *   public getCommandName(): string {
+ *     return 'example-analysis';
+ *   }
+ *
+ *   public getDescription(): string {
+ *     return 'an example analysis for demo';
+ *   }
+ *
+ *   async process(options: HeapAnalysisOptions): Promise<void> {
+ *     // check if the number of heap objects keeps growing overtime
+ *     const isMonotonicIncreasing = await snapshotMapReduce(
+ *       (heap) => heap.nodes.length,
+ *       (nodeCounts) =>
+ *         nodeCounts[0] < nodeCounts[nodeCounts.length - 1] &&
+ *         nodeCounts.every((count, i) => i === 0 || count >= nodeCounts[i - 1]),
+ *       options,
+ *     );
+ *   }
+ * }
+ * ```
+ *
+ * Use the following code to invoke the heap analysis:
+ * ```typescript
+ * const analysis = new ExampleAnalysis();
+ * // snapshotDir includes a series of .heapsnapshot files recorded by
+ * // memlab or saved manually from Chrome, those files will be loaded
+ * // in alphanumerically asceneding order
+ * await analysis.analyzeSnapshotsInDirectory(snapshotDir);
+ * ```
+ * The new heap analysis can also be used with {@link analyze}, in that case
+ * `snapshotMapReduce` will use all the heap snapshot in alphanumerically
+ * ascending order from {@link BrowserInteractionResultReader}.
+ *
+ * **Why not passing in all heap snapshots as an array of {@link IHeapSnapshot}s?**
+ * Each heap snapshot could be non-trivial in size, loading them all at once
+ * may not be possible.
+ */
 declare function snapshotMapReduce<T1, T2>(mapCallback: (snapshot: IHeapSnapshot, i: number, file: string) => T1, reduceCallback: (results: T1[]) => T2, options: HeapAnalysisOptions): Promise<T2>;
+/**
+ * This API aggregates metrics from the
+ * [dominator nodes](https://firefox-source-docs.mozilla.org/devtools-user/memory/dominators/index.html)
+ * of the set of input heap objects.
+ *
+ * @param ids Set of ids of heap objects (or nodes)
+ * @param snapshot heap graph loaded from a heap snapshot
+ * @param checkNodeCb filter callback to exclude some heap object/nodes
+ * before calculating the dominator nodes
+ * @param nodeMetricsCb callback to calculate metrics from each dominator node
+ * @returns the aggregated metrics
+ */
 declare function aggregateDominatorMetrics(ids: Set<number>, snapshot: IHeapSnapshot, checkNodeCb: (node: IHeapNode) => boolean, nodeMetricsCb: (node: IHeapNode) => number): number;
+/**
+ * This API calculate the set of
+ * [dominator nodes](https://firefox-source-docs.mozilla.org/devtools-user/memory/dominators/index.html)
+ * of the set of input heap objects.
+ * @param ids Set of ids of heap objects (or nodes)
+ * @param snapshot heap loaded from a heap snapshot
+ * @returns the set of dominator nodes/objects
+ * * * **Examples**:
+ * ```typescript
+ * import {dumpNodeHeapSnapshot} from '@memlab/core';
+ * import {getHeapFromFile, getDominatorNodes} from '@memlab/heap-analysis';
+ *
+ * class TestObject {}
+ *
+ * (async function () {
+ *   const t1 = new TestObject();
+ *   const t2 = new TestObject();
+ *
+ *   // dump the heap of this running JavaScript program
+ *   const heapFile = dumpNodeHeapSnapshot();
+ *   const heap = await getHeapFromFile(heapFile);
+ *
+ *   // find the heap node for TestObject
+ *   let nodes = [];
+ *   heap.nodes.forEach(node => {
+ *     if (node.name === 'TestObject' && node.type === 'object') {
+ *       nodes.push(node);
+ *     }
+ *   });
+ *
+ *   // get the dominator nodes
+ *   const dominatorIds = getDominatorNodes(
+ *     new Set(nodes.map(node => node.id)),
+ *     heap,
+ *   );
+ * })();
+ * ```
+ */
+declare function getDominatorNodes(ids: Set<number>, snapshot: IHeapSnapshot): Set<number>;
 declare function filterOutLargestObjects(snapshot: IHeapSnapshot, objectFilter: (node: IHeapNode) => boolean, listSize?: number): IHeapNode[];
 declare const _default: {
     aggregateDominatorMetrics: typeof aggregateDominatorMetrics;
@@ -35,11 +299,13 @@ declare const _default: {
         };
     };
     filterOutLargestObjects: typeof filterOutLargestObjects;
+    getDominatorNodes: typeof getDominatorNodes;
     getObjectOutgoingEdgeCount: typeof getObjectOutgoingEdgeCount;
     getSnapshotDirForAnalysis: typeof getSnapshotDirForAnalysis;
     getSnapshotFileForAnalysis: typeof getSnapshotFileForAnalysis;
     isNodeWorthInspecting: typeof isNodeWorthInspecting;
     loadHeapSnapshot: typeof loadHeapSnapshot;
+    getHeapFromFile: typeof getHeapFromFile;
     printNodeListInTerminal: typeof printNodeListInTerminal;
     printReferencesInTerminal: typeof printReferencesInTerminal;
     snapshotMapReduce: typeof snapshotMapReduce;