@memlab/core 1.1.19 → 1.1.21

package/dist/lib/Types.d.ts

@@ -23,6 +23,8 @@ export declare type Optional<T> = Nullable<T> | undefined;
 /** @internal */
 export declare type AnyRecord = Record<string, RecordValue>;
 /** @internal */
+export declare type StringRecord = Record<string, string>;
+/** @internal */
 export declare type AnyAyncFunction = (...args: AnyValue[]) => Promise<AnyValue>;
 /** @internal */
 export declare type AnyFunction = (...args: AnyValue[]) => AnyValue;
@@ -47,6 +49,7 @@ export declare type FileOption = {
     workDir?: Optional<string>;
     clear?: boolean;
     transient?: boolean;
+    errorWhenAbsent?: boolean;
 };
 /** @internal */
 export declare type CLIOptions = {
@@ -65,6 +68,7 @@ export declare type XvfbType = {
 export declare type ShellOptions = {
     dir?: Optional<string>;
     ignoreError?: Optional<boolean>;
+    throwError?: Optional<boolean>;
     disconnectStdio?: Optional<boolean>;
 };
 /** @internal */
@@ -897,6 +901,7 @@ export interface IE2EStepBasic {
 /** @internal */
 export declare type E2EStepInfo = IE2EStepBasic & {
     snapshot: boolean;
+    snapshotFile?: string;
     screenshot: boolean;
     idx: number;
     JSHeapUsedSize: number;
@@ -940,6 +945,8 @@ export declare type RunMetaInfo = {
      * output data from the browser
      */
     browserInfo: IBrowserInfo;
+    /** @internal */
+    extraInfo?: StringRecord;
 };
 /**
  * A heap snapshot is generally a graph where graph nodes are JS heap objects
@@ -1218,6 +1225,16 @@ export interface IHeapLocation {
      * get the column number
      */
     column: number;
+    /**
+     * convert to a concise readable string output
+     * (like calling `JSON.stringify(node, ...args)`).
+     * Note: calling `JSON.stringify(node, ...args)` will not work
+     * since the string is too large and not readable.
+     *
+     * This API does not completely serialize all the information
+     * captured by the hosting object.
+     */
+    toJSONString(...args: Array<AnyValue>): string;
 }
 /** @internal */
 export interface IHeapEdgeBasic {
@@ -1290,6 +1307,16 @@ export interface IHeapEdge extends IHeapEdgeBasic {
      * JS heap object where this reference starts
      */
     fromNode: IHeapNode;
+    /**
+     * convert to a concise readable string output
+     * (like calling `JSON.stringify(node, ...args)`).
+     * Note: calling `JSON.stringify(node, ...args)` will not work
+     * since the string is too large and not readable.
+     *
+     * This API does not completely serialize all the information
+     * captured by the hosting object.
+     */
+    toJSONString(...args: Array<AnyValue>): string;
 }
 /**
  * A pseudo array containing all heap graph edges (references to heap objects
@@ -1446,6 +1473,11 @@ export interface IHeapNode extends IHeapNodeBasic {
      * object (including engine-internal, native, and JS references).
      */
     referrers: IHeapEdge[];
+    /**
+     * Get the number of all incoming references pointing to this heap object
+     * (including engine-internal, native, and JS references).
+     */
+    numOfReferrers: number;
     /**
      * returns true if the heap node has been set an incoming edge
      * which leads to the parent node on the shortest path to GC root.
@@ -1493,6 +1525,16 @@ export interface IHeapNode extends IHeapNodeBasic {
      * inside the string node.
      */
     toStringNode(): Nullable<IHeapStringNode>;
+    /**
+     * convert to a concise readable string output
+     * (like calling `JSON.stringify(node, ...args)`).
+     * Note: calling `JSON.stringify(node, ...args)` will not work
+     * since the string is too large and not readable.
+     *
+     * This API does not completely serialize all the information
+     * captured by the hosting object.
+     */
+    toJSONString(...args: Array<AnyValue>): string;
     /**
      * executes a provided callback once for each JavaScript reference in the
      * hosting node (or outgoing edges from the node)
@@ -1563,6 +1605,24 @@ export interface IHeapNode extends IHeapNodeBasic {
      * ```
      */
     findAnyReferrer: (predicate: Predicator<IHeapEdge>) => Nullable<IHeapEdge>;
+    /**
+     * executes a provided predicate callback once for each JavaScript heap
+     * object (heap graph node) pointing to the hosting node
+     * (or nodes having edges to the hosting node) until the predicate
+     * returns `true`
+     * @param predicate the callback for each incoming JavaScript heap object
+     * @returns the first referring node for which the predicate returns `true`,
+     * otherwise returns `null` if no such node is found.
+     *
+     * * **Examples**:
+     * ```typescript
+     * const referrer = node.findAnyReferrerNode((node: IHeapNode) => {
+     *   // find the referring node with name "Parent"
+     *   return node.name === 'Parent';
+     * });
+     * ```
+     */
+    findAnyReferrerNode(predicate: Predicator<IHeapNode>): Nullable<IHeapNode>;
     /**
      * executes a provided predicate callback once for each JavaScript reference
      * pointing to the hosting node (or incoming edges to the node)
@@ -1580,6 +1640,24 @@ export interface IHeapNode extends IHeapNodeBasic {
      * ```
      */
     findReferrers: (predicate: Predicator<IHeapEdge>) => IHeapEdge[];
+    /**
+     * executes a provided predicate callback once for each JavaScript heap
+     * object (heap graph node) pointing to the hosting node
+     * (or nodes having edges to the hosting node)
+     * @param predicate the callback for each referrer nodes
+     * @returns an array containing all the referrer nodes for which the
+     * predicate returns `true`, otherwise returns an empty array if no such
+     * node is found.
+     *
+     * * **Examples**:
+     * ```typescript
+     * const referrerNodes = node.findReferrerNodes((node: IHeapNode) => {
+     *   // find all the referring nodes with name "Parent"
+     *   return node.name === 'Parent';
+     * });
+     * ```
+     */
+    findReferrerNodes: (predicate: Predicator<IHeapNode>) => IHeapNode[];
     /**
      * Given a JS reference's name and type, this API finds an outgoing JS
      * reference from the hosting node.
@@ -1851,12 +1929,12 @@ export interface IOveralLeakInfo extends Partial<IOveralHeapInfo> {
 }
 /** @internal */
 export declare type DiffLeakOptions = {
-    controlWorkDir: string;
+    controlWorkDirs: string[];
     treatmentWorkDir: string;
 };
 /** @internal */
 export declare type PlotMemoryOptions = {
-    controlWorkDir?: string;
+    controlWorkDirs?: string[];
     treatmentWorkDir?: string;
     workDir?: string;
 } & IMemoryAnalystOptions;

package/dist/lib/Utils.d.ts

@@ -7,13 +7,15 @@
  * @format
  * @oncall web_perf_infra
  */
-import type { HaltOrThrowOptions, HeapNodeIdSet, ShellOptions } from './Types';
+import type { HaltOrThrowOptions, HeapNodeIdSet, ShellOptions, StringRecord } from './Types';
 import type { Browser, Page } from 'puppeteer';
-import type { AnyAyncFunction, AnyOptions, E2EStepInfo, IHeapSnapshot, IHeapNode, IHeapEdge, IScenario, ILeakFilter, LeakTracePathItem, RunMetaInfo, RawHeapSnapshot, Nullable, Optional } from './Types';
+import type { AnyAyncFunction, AnyOptions, E2EStepInfo, IHeapSnapshot, IHeapNode, IHeapEdge, IScenario, ILeakFilter, LeakTracePathItem, RawHeapSnapshot, Nullable, Optional } from './Types';
 declare function isHermesInternalObject(node: IHeapNode): boolean;
 declare function isStackTraceFrame(node: IHeapNode): boolean;
 declare function isFiberNode(node: Optional<IHeapNode>): boolean;
 declare function isDetachedFiberNode(node: IHeapNode): boolean;
+declare function isDOMInternalNode(node: Optional<IHeapNode>): boolean;
+declare function isGlobalHandlesNode(node: Optional<IHeapNode>): boolean;
 declare function isDetachedDOMNode(node: Optional<IHeapNode>, args?: AnyOptions): boolean;
 declare function isWeakMapEdge(edge: IHeapEdge): boolean;
 declare function isWeakMapEdgeToKey(edge: IHeapEdge): boolean;
@@ -23,6 +25,9 @@ declare function isFiberNodeDeletionsEdge(edge: IHeapEdge): boolean;
 declare function isBlinkRootNode(node: IHeapNode): boolean;
 declare function isPendingActivityNode(node: IHeapNode): boolean;
 declare function isDOMNodeIncomplete(node: IHeapNode): boolean;
+declare function isXMLDocumentNode(node: IHeapNode): boolean;
+declare function isHTMLDocumentNode(node: IHeapNode): boolean;
+declare function isDOMTextNode(node: IHeapNode): boolean;
 declare function isRootNode(node: IHeapNode, opt?: AnyOptions): boolean;
 declare function isDirectPropEdge(edge: IHeapEdge): boolean;
 declare function isReturnEdge(edge: IHeapEdge): boolean;
@@ -64,12 +69,8 @@ declare function getBooleanNodeValue(node: IHeapNode): Nullable<boolean>;
 declare function getToNodeByEdge(node: Nullable<IHeapNode>, propName: string, propType?: string): Nullable<IHeapNode>;
 declare function extractHTMLElementNodeInfo(node: IHeapNode): string;
 declare function hasOnlyWeakReferrers(node: IHeapNode): boolean;
-declare function getRunMetaFilePath(): string;
-declare function loadRunMetaInfo(metaFile?: Optional<string>): RunMetaInfo;
-declare function loadTargetInfoFromRunMeta(): void;
 declare function getSnapshotSequenceFilePath(): string;
 declare function loadTabsOrder(metaFile?: Optional<string>): E2EStepInfo[];
-declare function isInterestingPath(p: LeakTracePathItem): boolean;
 declare function isObjectNode(node: IHeapNode): boolean;
 declare function isPlainJSObjectNode(node: IHeapNode): boolean;
 declare function pathHasDetachedHTMLNode(path: LeakTracePathItem): boolean;
@@ -125,16 +126,20 @@ declare function isNodeDominatedByDeletionsArray(node: IHeapNode): boolean;
 declare function getUniqueID(): string;
 declare function getClosureSourceUrl(node: IHeapNode): Nullable<string>;
 export declare function runShell(command: string, options?: ShellOptions): Nullable<string>;
-export declare function getRetainedSize(node: IHeapNode): number;
-export declare function aggregateDominatorMetrics(ids: HeapNodeIdSet, snapshot: IHeapSnapshot, checkNodeCb: (node: IHeapNode) => boolean, nodeMetricsCb: (node: IHeapNode) => number): number;
+declare function getRetainedSize(node: IHeapNode): number;
+declare function aggregateDominatorMetrics(ids: HeapNodeIdSet, snapshot: IHeapSnapshot, checkNodeCb: (node: IHeapNode) => boolean, nodeMetricsCb: (node: IHeapNode) => number): number;
+declare function getLeakTracePathLength(path: LeakTracePathItem): number;
+declare function getNumberAtPercentile(arr: number[], percentile: number): number;
+declare function mapToObject(map: Map<string, string>): StringRecord;
+declare function objectToMap(object: StringRecord): Map<string, string>;
 declare const _default: {
     aggregateDominatorMetrics: typeof aggregateDominatorMetrics;
     applyToNodes: typeof applyToNodes;
     callAsync: typeof callAsync;
     camelCaseToReadableString: typeof camelCaseToReadableString;
+    checkIsChildOfParent: typeof checkIsChildOfParent;
     checkSnapshots: typeof checkSnapshots;
     checkUninstalledLibrary: typeof checkUninstalledLibrary;
-    checkIsChildOfParent: typeof checkIsChildOfParent;
     closePuppeteer: typeof closePuppeteer;
     dumpSnapshot: typeof dumpSnapshot;
     equalOrMatch: typeof equalOrMatch;
@@ -143,29 +148,31 @@ declare const _default: {
     extractHTMLElementNodeInfo: typeof extractHTMLElementNodeInfo;
     filterNodesInPlace: typeof filterNodesInPlace;
     getAllDominators: typeof getAllDominators;
+    getBooleanNodeValue: typeof getBooleanNodeValue;
     getClosureSourceUrl: typeof getClosureSourceUrl;
     getConditionalDominatorIds: typeof getConditionalDominatorIds;
-    getError: typeof getError;
     getEdgeByNameAndType: typeof getEdgeByNameAndType;
+    getError: typeof getError;
     getLastNodeId: typeof getLastNodeId;
+    getLeakTracePathLength: typeof getLeakTracePathLength;
     getLeakedNode: typeof getLeakedNode;
     getNodesIdSet: typeof getNodesIdSet;
+    getNumberAtPercentile: typeof getNumberAtPercentile;
     getNumberNodeValue: typeof getNumberNodeValue;
     getReadableBytes: typeof getReadableBytes;
     getReadablePercent: typeof getReadablePercent;
     getReadableTime: typeof getReadableTime;
     getRetainedSize: typeof getRetainedSize;
-    getRunMetaFilePath: typeof getRunMetaFilePath;
     getScenarioName: typeof getScenarioName;
     getSingleSnapshotFileForAnalysis: typeof getSingleSnapshotFileForAnalysis;
     getSnapshotDirForAnalysis: typeof getSnapshotDirForAnalysis;
-    getSnapshotFilesInDir: typeof getSnapshotFilesInDir;
+    getSnapshotFilePath: typeof getSnapshotFilePath;
+    getSnapshotFilePathWithTabType: typeof getSnapshotFilePathWithTabType;
     getSnapshotFilesFromTabsOrder: typeof getSnapshotFilesFromTabsOrder;
+    getSnapshotFilesInDir: typeof getSnapshotFilesInDir;
     getSnapshotFromFile: typeof getSnapshotFromFile;
     getSnapshotNodeIdsFromFile: typeof getSnapshotNodeIdsFromFile;
     getSnapshotSequenceFilePath: typeof getSnapshotSequenceFilePath;
-    getSnapshotFilePath: typeof getSnapshotFilePath;
-    getSnapshotFilePathWithTabType: typeof getSnapshotFilePathWithTabType;
     getStringNodeValue: typeof getStringNodeValue;
     getToNodeByEdge: typeof getToNodeByEdge;
     getUniqueID: typeof getUniqueID;
@@ -176,18 +183,21 @@ declare const _default: {
     hasReactEdges: typeof hasReactEdges;
     isAlternateNode: typeof isAlternateNode;
     isBlinkRootNode: typeof isBlinkRootNode;
+    isDOMInternalNode: typeof isDOMInternalNode;
+    isDOMNodeIncomplete: typeof isDOMNodeIncomplete;
+    isDOMTextNode: typeof isDOMTextNode;
     isDebuggableNode: typeof isDebuggableNode;
-    isDetachedFiberNode: typeof isDetachedFiberNode;
     isDetachedDOMNode: typeof isDetachedDOMNode;
+    isDetachedFiberNode: typeof isDetachedFiberNode;
     isDirectPropEdge: typeof isDirectPropEdge;
     isDocumentDOMTreesRoot: typeof isDocumentDOMTreesRoot;
-    isDOMNodeIncomplete: typeof isDOMNodeIncomplete;
     isEssentialEdge: typeof isEssentialEdge;
     isFiberNode: typeof isFiberNode;
     isFiberNodeDeletionsEdge: typeof isFiberNodeDeletionsEdge;
+    isGlobalHandlesNode: typeof isGlobalHandlesNode;
+    isHTMLDocumentNode: typeof isHTMLDocumentNode;
     isHermesInternalObject: typeof isHermesInternalObject;
     isHostRoot: typeof isHostRoot;
-    isInterestingPath: typeof isInterestingPath;
     isMeaningfulEdge: typeof isMeaningfulEdge;
     isMeaningfulNode: typeof isMeaningfulNode;
     isNodeDominatedByDeletionsArray: typeof isNodeDominatedByDeletionsArray;
@@ -206,17 +216,18 @@ declare const _default: {
     isWeakMapEdge: typeof isWeakMapEdge;
     isWeakMapEdgeToKey: typeof isWeakMapEdgeToKey;
     isWeakMapEdgeToValue: typeof isWeakMapEdgeToValue;
+    isXMLDocumentNode: typeof isXMLDocumentNode;
     iterateChildFiberNodes: typeof iterateChildFiberNodes;
     iterateDescendantFiberNodes: typeof iterateDescendantFiberNodes;
-    loadRunMetaInfo: typeof loadRunMetaInfo;
     loadLeakFilter: typeof loadLeakFilter;
     loadScenario: typeof loadScenario;
     loadTabsOrder: typeof loadTabsOrder;
-    loadTargetInfoFromRunMeta: typeof loadTargetInfoFromRunMeta;
+    mapToObject: typeof mapToObject;
     markAllDetachedFiberNode: typeof markAllDetachedFiberNode;
     markAlternateFiberNode: typeof markAlternateFiberNode;
     memCache: Record<string, any>;
     normalizeBaseUrl: typeof normalizeBaseUrl;
+    objectToMap: typeof objectToMap;
     pathHasDetachedHTMLNode: typeof pathHasDetachedHTMLNode;
     pathHasEdgeWithIndex: typeof pathHasEdgeWithIndex;
     repeat: typeof repeat;
@@ -229,7 +240,6 @@ declare const _default: {
     shuffleArray: typeof shuffleArray;
     throwError: typeof throwError;
     upperCaseFirstCharacter: typeof upperCaseFirstCharacter;
-    getBooleanNodeValue: typeof getBooleanNodeValue;
 };
 export default _default;
 //# sourceMappingURL=Utils.d.ts.map