@memlab/heap-analysis 1.0.15 → 1.0.17

package/dist/BaseAnalysis.d.ts

@@ -8,7 +8,7 @@
  * @oncall web_perf_infra
  */
 import type { AnyValue, BaseOption } from '@memlab/core';
-import type { AnalyzeSnapshotResult, HeapAnalysisOptions } from './PluginUtils';
+import type { AnalyzeSnapshotResult, HeapAnalysisOptions, RunHeapAnalysisOptions } from './PluginUtils';
 declare abstract class Analysis {
     process(_options: HeapAnalysisOptions): Promise<void>;
     /**
@@ -26,6 +26,7 @@ declare abstract class Analysis {
     /**
      * Run heap analysis for a single heap snapshot file
      * @param file the absolute path of a `.heapsnapshot` file.
+     * @param options optional configuration for the heap analysis run
      * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
      * the logging file of analysis console output. Alternatively, to get more
      * structured analysis results, check out the documentation of the hosting
@@ -35,17 +36,29 @@ declare abstract class Analysis {
      * ```typescript
      * const analysis = new StringAnalysis();
      * // analysis console output is saved in result.analysisOutputFile
-     * const result = await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile);
      * // query analysis-specific and structured results
      * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
      * ```
+     * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotFromFile(file: string): Promise<AnalyzeSnapshotResult>;
+    analyzeSnapshotFromFile(file: string, options?: RunHeapAnalysisOptions): Promise<AnalyzeSnapshotResult>;
     /**
      * 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.
+     * @param options optional configuration for the heap analysis run
      * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
      * the logging file of analysis console output. Alternatively, to get more
      * structured analysis results, check out the documentation of the hosting
@@ -55,12 +68,23 @@ declare abstract class Analysis {
      * ```typescript
      * const analysis = new ShapeUnboundGrowthAnalysis();
      * // analysis console output is saved in result.analysisOutputFile
-     * const result = await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory);
      * // query analysis-specific and structured results
      * const shapes = analysis.getShapesWithUnboundGrowth();
      * ```
+     * * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotsInDirectory(directory: string): Promise<AnalyzeSnapshotResult>;
+    analyzeSnapshotsInDirectory(directory: string, options?: RunHeapAnalysisOptions): Promise<AnalyzeSnapshotResult>;
 }
 /**
  *

package/dist/BaseAnalysis.js

@@ -68,6 +68,7 @@ class Analysis {
     /**
      * Run heap analysis for a single heap snapshot file
      * @param file the absolute path of a `.heapsnapshot` file.
+     * @param options optional configuration for the heap analysis run
      * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
      * the logging file of analysis console output. Alternatively, to get more
      * structured analysis results, check out the documentation of the hosting
@@ -77,13 +78,28 @@ class Analysis {
      * ```typescript
      * const analysis = new StringAnalysis();
      * // analysis console output is saved in result.analysisOutputFile
-     * const result = await anaysis.analyzeSnapshotFromFile(snapshotFile);
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile);
      * // query analysis-specific and structured results
      * const stringPatterns = analysis.getTopDuplicatedStringsInCount();
      * ```
+     * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new StringAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotFromFile(snapshotFile, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotFromFile(file) {
+    analyzeSnapshotFromFile(file, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (options.workDir) {
+                // set and init the new work dir
+                core_1.config.defaultFileManagerOption = options;
+            }
             const analysisOutputFile = core_1.fileManager.initNewHeapAnalysisLogFile();
             core_1.info.registerLogFile(analysisOutputFile);
             yield this.process({
@@ -102,6 +118,7 @@ class Analysis {
      * @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.
+     * @param options optional configuration for the heap analysis run
      * @returns this API returns {@link AnalyzeSnapshotResult}, which contains
      * the logging file of analysis console output. Alternatively, to get more
      * structured analysis results, check out the documentation of the hosting
@@ -111,13 +128,28 @@ class Analysis {
      * ```typescript
      * const analysis = new ShapeUnboundGrowthAnalysis();
      * // analysis console output is saved in result.analysisOutputFile
-     * const result = await anaysis.analyzeSnapshotsInDirectory(snapshotDirectory);
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory);
      * // query analysis-specific and structured results
      * const shapes = analysis.getShapesWithUnboundGrowth();
      * ```
+     * * Additionally, you can specify a working directory to where
+     * the intermediate, logging, and final output files will be dumped:
+     * ```typescript
+     * const analysis = new ShapeUnboundGrowthAnalysis();
+     * // analysis console output is saved in result.analysisOutputFile
+     * // which is inside the specified working directory
+     * const result = await analysis.analyzeSnapshotsInDirectory(snapshotDirectory, {
+     *   // if the specified directory doesn't exist, memlab will create it
+     *   workDir: '/tmp/your/work/dir',
+     * });
+     * ```
      */
-    analyzeSnapshotsInDirectory(directory) {
+    analyzeSnapshotsInDirectory(directory, options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
+            if (options.workDir) {
+                // set and init the new work dir
+                core_1.config.defaultFileManagerOption = options;
+            }
             const analysisOutputFile = core_1.fileManager.initNewHeapAnalysisLogFile();
             core_1.info.registerLogFile(analysisOutputFile);
             yield this.process({

package/dist/PluginUtils.d.ts

@@ -25,6 +25,17 @@ export declare type HeapAnalysisOptions = {
     /** @internal */
     config?: MemLabConfig;
 };
+/**
+ * This is the input option for {@link analyzeSnapshotFromFile}
+ * and {@link analyzeSnapshotsInDirectory}.
+ */
+export declare type RunHeapAnalysisOptions = {
+    /**
+     * specify the working directory to where the intermediate, logging,
+     * and output files should be saved
+     */
+    workDir?: string;
+};
 /**
  * This is the return type from calling {@link analyzeSnapshotFromFile}
  * or {@link analyzeSnapshotsInDirectory}.

package/dist/index.d.ts

@@ -12,7 +12,7 @@ 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 type { AnalyzeSnapshotResult, HeapAnalysisOptions, RunHeapAnalysisOptions, } from './PluginUtils';
 export { default as BaseAnalysis } from './BaseAnalysis';
 export { default as DetachedDOMElementAnalysis } from './plugins/DetachedDOMElementAnalysis';
 export { default as GlobalVariableAnalysis } from './plugins/GlobalVariableAnalysis/GlobalVariableAnalysis';

package/dist/plugins/CollectionUnboundGrowthAnalysis.js

@@ -54,7 +54,7 @@ class CollectionUnboundGrowthAnalysis extends BaseAnalysis_1.default {
             const snapshotDir = PluginUtils_1.default.getSnapshotDirForAnalysis(options);
             const opt = snapshotDir ? { minSnapshots: 2, snapshotDir } : {};
             core_1.config.chaseWeakMapEdge = false;
-            core_1.analysis.visualizeMemoryUsage(opt);
+            core_1.memoryBarChart.plotMemoryBarChart(opt);
             core_1.utils.checkSnapshots(opt);
             yield this.checkUnboundCollection(opt);
         });

package/dist/plugins/ObjectUnboundGrowthAnalysis.js

@@ -58,7 +58,7 @@ class ObjectUnboundGrowthAnalysis extends BaseAnalysis_1.default {
     }
     checkUnbound(options = {}) {
         return __awaiter(this, void 0, void 0, function* () {
-            core_1.analysis.visualizeMemoryUsage(options);
+            core_1.memoryBarChart.plotMemoryBarChart(options);
             core_1.utils.checkSnapshots(options);
             yield this.detectUnboundGrowth(options);
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memlab/heap-analysis",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "license": "MIT",
   "description": "heap analysis plugins for memlab",
   "author": "Liang Gong <lgong@fb.com>",