Package: @memlab/core

Interfaces

• IBrowserInfo
• IHeapEdge
• IHeapEdges
• IHeapLocation
• IHeapNode
• IHeapNodes
• IHeapSnapshot
• IHeapStringNode
• ILeakFilter
• IScenario

Type Aliases

CheckPageLoadCallback: (page: Page) => Promise<boolean>

Callback function to provide if the page is loaded. For concrete example, check out isPageLoaded.

• Parameters:

  • page: Page | puppeteer's Page object. To import this type, check out Page.

• Returns: Promise<boolean> | a boolean value, if it returns true, memlab will consider the navigation completes, if it returns false, memlab will keep calling this callback until it returns true. This is an async callback, you can also await and returns true until some async logic is resolved.

• Source:

  • core/src/lib/Types.ts:1166

---

Cookie: Object

A single cookie entry in a Cookies list. The name and value field is mandatory. It is better to also specify the domain field, otherwise MemLab will try to infer domain automatically. The other fields are optional. For concrete use case, please check out cookies.

Name	Type	Description
domain?	string	Add when possible: Defines the domain associated with the cookie
expires?	Undefinable<number>	Optional: Indicates when the cookie will expire, in Unix time (seconds)
httpOnly?	Undefinable<boolean>	Optional: Flag to determine if the cookie is accessible only over HTTP
name	string	Mandatory: Represents the name of the cookie
path?	Undefinable<string>	Optional: Defines the domain associated with the cookie
sameSite?	Undefinable<"Strict" | "Lax">	Optional: Determines if a cookie is transmitted with cross-site requests, offering a degree of defense against cross-site request forgery attacks.
secure?	Undefinable<boolean>	Optional: Flag to indicate if the cookie transmission requires a secure protocol (e.g., HTTPS)
session?	Undefinable<boolean>	Optional: Flag to check if the cookie is a session cookie
url?	Undefinable<string>	Optional: Specifies the request-URI linked with the cookie setup. This can influence the cookie's default domain and path
value	string	Mandatory: Represents the value assigned to the cookie

• Source:
  • core/src/lib/Types.ts:236

---

Cookies: Cookie[]

Data structure for holding cookies. For concrete use case, please check out cookies.

• Source:
  • core/src/lib/Types.ts:226

---

EdgeIterationCallback: (edge: IHeapEdge) => Optional<{ stop: boolean }> | void

Executes a provided callback once for JavaScript references. For concrete examples, check out forEachReference or forEachReferrer.

• Parameters:

  • edge: IHeapEdge

• Returns: Optional<{ stop: boolean }> | void | this API returns void

• Source:

  • core/src/lib/Types.ts:1795

---

InitLeakFilterCallback: (snapshot: IHeapSnapshot, leakedNodeIds: HeapNodeIdSet) => void

Lifecycle function callback that is invoked initially once before calling any leak filter function. For concrete example, check out beforeLeakFilter.

• Parameters:

  • snapshot: IHeapSnapshot | heap snapshot see IHeapSnapshot
  • leakedNodeIds: HeapNodeIdSet | the set of leaked object (node) ids.

• Returns: void

• Source:

  • core/src/lib/Types.ts:554

---

InteractionsCallback: (page: Page, args?: OperationArgs) => Promise<void>

The callback defines browser interactions which are used by memlab to interact with the web app under test. For concrete examples, check out action or back.

• Parameters:

  • page: Page | the puppeteer Page object, which provides APIs to interact with the web browser. To import this type, check out Page.
  • args?: OperationArgs

• Returns: Promise<void> | no return value

• Source:

  • core/src/lib/Types.ts:640

---

LeakFilterCallback: (node: IHeapNode, snapshot: IHeapSnapshot, leakedNodeIds: HeapNodeIdSet) => boolean

Callback that can be used to define a logic to filter the leaked objects. The callback is only called for every node allocated but not released from the target interaction in the heap snapshot.

For concrete examples, check out leakFilter.

• Parameters:
  • node: IHeapNode | the node that is kept alive in the memory in the heap snapshot
  • snapshot: IHeapSnapshot | the snapshot of target interaction
  • leakedNodeIds: HeapNodeIdSet | the set of leaked node ids
• Returns: boolean | the value indicating whether the given node in the snapshot should be considered as leaked.
• Examples:

// any node in the heap snapshot that is greater than 1MB
function leakFilter(node, _snapshot, _leakedNodeIds) {
 return node.retainedSize > 1000000;
};

• Source:
  • core/src/lib/Types.ts:581

---

Nullable<T>: T | null

Given any type T, return the union type T and null

Type parameters

Name	Description
T	The type that will be made nullable.

• Source:
  • core/src/lib/Types.ts:32

---

Optional<T>: T | null | undefined

Given any type T, return the union type T, null, and undefined.

Type parameters

Name	Description
T	The type that will be made both nullable and undefinable.

• Source:
  • core/src/lib/Types.ts:38

---

Page: PuppeteerPage

This is the puppeteer Page class used by MemLab. The puppeteer Page class instance provides APIs to interact with the web browser.

The puppeteer Page type can be incompatible across different versions. Your local npm-installed puppeteer version may be different from the puppeteer used by MemLab. This may cause some type errors, for example:

import type {Page} from 'puppeteer';
import type {RunOptions} from '@memlab/api';

const runOptions: RunOptions = {
  scenario: {
    // initial page load url: Google Maps
    url: () => {
      return "https://www.google.com/maps/@37.386427,-122.0428214,11z";
    },
    // type error here if your local puppeeter version is different
    // from the puppeteer used by MemLab
    action: async function (page: Page) {
      await page.click('text/Hotels');
    },
  },
};

To avoid the type error in the code example above, MemLab exports the puppeteer Page type used by MemLab so that your code can import it when necessary:

import type {Page} from '@memlab/core' // import Page type from memlab
import type {RunOptions} from 'memlab';

const runOptions: RunOptions = {
  scenario: {
    // initial page load url: Google Maps
    url: () => {
      return "https://www.google.com/maps/@37.386427,-122.0428214,11z";
    },
    // no type error here
    action: async function (page: Page) {
      await page.click('text/Hotels');
    },
  },
};

• Source:
  • core/src/lib/Types.ts:207

---

Predicator<T>: (entity: T) => boolean

Type parameters

Name	Description
T	the type of the entity to be checked

the predicate callback is used to decide if a entity of type T. For more concrete examples on where it is used, check out findAnyReference, findAnyReferrer, and findReferrers.

• Parameters:

  • entity: T | the entity to be checked

• Returns: boolean | whether the entity passes the predicate check

• Source:

  • core/src/lib/Types.ts:220

---

ReferenceFilterCallback: (edge: IHeapEdge, snapshot: IHeapSnapshot, isReferenceUsedByDefault: boolean) => boolean

Callback that can be used to define a logic to decide whether a reference should be filtered (included) for some calculations (e.g., retainer trace calculation)

For concrete examples, check out leakFilter.

• Parameters:
  • edge: IHeapEdge | the reference (edge) that is considered for calcualting the retainer trace
  • snapshot: IHeapSnapshot | the final snapshot taken after all browser interactions are done.
  • isReferenceUsedByDefault: boolean | MemLab has its own default logic for whether a reference should be filtered (included), if this parameter is true, it means MemLab will consider this reference for inclusion
• Returns: boolean | the value indicating whether the given reference should be filtered (i.e., included)

Please also be aware that some edges like self-referencing edges, JS engine's internal edges, and hidden edges should not be considered as part of the retainer trace. These edges could make the retainer trace unncessarily complex and cause confusion. isReferenceUsedByDefault will be false for these types of edges.

• Examples:

// exclude react fiber references
function retainerReferenceFilter(edge, _snapshot, _isReferenceUsedByDefault) {
  if (edge.name_or_index.toString().startsWith('__reactFiber$')) {
    return false;
  }
  // exclude other references here
  // ...
  return true;
};

• Source:
  • core/src/lib/Types.ts:624

---

RunMetaInfo: Object

This data structure holds the information about memlab run. You can retrieve the instance of this type through getRunMetaInfo.

Name	Type	Description
browserInfo	IBrowserInfo	input configuration for the browser and output data from the browser
type	string	type of the memlab run

• Source:
  • core/src/lib/Types.ts:1247

---

Undefinable<T>: T | undefined

Given any type T, return the union type T and undefined.

Type parameters

Name	Description
T	The type that will be made undefinable.

• Source:
  • core/src/lib/Types.ts:44

Functions

dumpNodeHeapSnapshot()

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: string | the absolute file path to the saved .heapsnapshot file.

• Examples:

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);
})();

• Source:
  • core/src/lib/NodeHeap.ts:84

---

tagObject<T>(o, tag)

Tags a string marker to an object instance, which can later be checked by hasObjectWithTag. This API does not modify the object instance in any way (e.g., no additional or hidden properties added to the tagged object).

Type parameters

Name	Type
T	extends object

• Parameters:
  • o: T | specify the object instance you want to tag, you cannot tag a primitive.
  • tag: string | marker name to tag on the object instance
• Returns: T | returns the tagged object instance (same reference as the input argument o)
• Examples:

import type {IHeapSnapshot, AnyValue} from '@memlab/core';
import {config, takeNodeMinimalHeap, 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 takeNodeMinimalHeap();

  // 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);

• Source:
  • core/src/lib/NodeHeap.ts:59

---

takeNodeMinimalHeap()

Take a heap snapshot of the current program state and parse it as IHeapSnapshot. Notice that this API does not calculate some heap analysis meta data for heap analysis. But this also means faster heap parsing.

• Returns: Promise<IHeapSnapshot> | heap representation without heap analysis meta data.

• Examples:

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 getFullHeapFromFile.

• Source:
  • core/src/lib/NodeHeap.ts:152