@memlab/lens 1.0.0

package/src/extensions/basic-extension.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type ReactMemoryScan from '../core/react-memory-scan';
+import type {AnalysisResult} from '../core/types';
+
+/**
+ * Base class for React Memory Scanner extensions.
+ * Extensions can hook into the scanning process before and after analysis.
+ */
+export abstract class BasicExtension {
+  protected readonly scanner: ReactMemoryScan;
+
+  constructor(scanner: ReactMemoryScan) {
+    this.scanner = scanner;
+  }
+
+  /**
+   * Hook that runs before the memory scan starts.
+   * Override this method to perform any setup or pre-scan operations.
+   */
+  beforeScan(): void {
+    // to be overridden
+  }
+
+  /**
+   * Hook that runs after the memory scan completes.
+   * Override this method to process or modify the analysis results.
+   * @param analysisResult - The results from the memory scan
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  afterScan(_analysisResult: AnalysisResult): void {
+    // to be overridden
+  }
+}

package/src/extensions/dom-visualization-extension.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type ReactMemoryScan from '../core/react-memory-scan';
+import type {AnalysisResult} from '../core/types';
+
+import DOMElementVisualizer from '../visual/dom-element-visualizer';
+import DOMElementVisualizerInteractive from '../visual/dom-element-visualizer-interactive';
+import {BasicExtension} from './basic-extension';
+
+const USE_INTERACTIVE_VISUALIZER = true;
+
+export class DOMVisualizationExtension extends BasicExtension {
+  #domVirtualizer: DOMElementVisualizer;
+
+  constructor(scanner: ReactMemoryScan) {
+    super(scanner);
+    if (USE_INTERACTIVE_VISUALIZER) {
+      this.#domVirtualizer = new DOMElementVisualizerInteractive();
+    } else {
+      this.#domVirtualizer = new DOMElementVisualizer();
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  afterScan(_analysisResult: AnalysisResult): void {
+    // const start = Date.now();
+    const scanner = this.scanner;
+    if (scanner.isDevMode()) {
+      const detachedDOMInfo = scanner.getDetachedDOMInfo();
+      this.#domVirtualizer.repaint(detachedDOMInfo);
+    }
+    // const end = Date.now();
+    // console.log(`repaint took ${end - start}ms`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export function getBundleContent(): string {
+  const bundlePath = path.join(__dirname, 'memlens.run.bundle.min.js');
+  return fs.readFileSync(bundlePath, 'utf-8');
+}

package/src/memlens.lib.js.flow

@@ -0,0 +1,75 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall memory_lab
+ */
+// Core types
+export type BoundingRect = {
+  bottom: number,
+  height: number,
+  left: number,
+  right: number,
+  top: number,
+  width: number,
+  x: number,
+  y: number,
+};
+
+export type DOMElementInfo = {
+  boundingRect: BoundingRect,
+};
+
+export type Nullable<T> = T | null;
+
+// [lib-index.ts]
+export type ReactMemoryScan = {
+  constructor: (options: CreateOptions) => void,
+  start: () => void,
+  stop: () => void,
+  scan: () => void,
+  visualize: () => void,
+  subscribe: (callback: AnalysisResultCallback) => () => void,
+  unsubscribe: (callback: AnalysisResultCallback) => void,
+  isDevMode: () => boolean,
+};
+
+declare export function createReactMemoryScan(
+  options: CreateOptions,
+): ReactMemoryScan;
+
+export type BasicExtension = {
+  beforeScan: () => void,
+  afterScan: (result: AnalysisResult) => void,
+};
+
+export type CreateOptions = {
+  isDevMode?: boolean,
+  subscribers?: Array<AnalysisResultCallback>,
+  extensions?: Array<BasicExtension>,
+  scanIntervalMs?: number,
+};
+
+export type ScanResult = {
+  components: Set<string>,
+  componentToFiberNodeCount: Map<string, number>,
+  totalElements: number,
+  totalDetachedElements: number,
+  detachedComponentToFiberNodeCount: Map<string, number>,
+  fiberNodes: Array<WeakRef<Fiber>>,
+  leakedFibers: Array<WeakRef<Fiber>>,
+};
+
+export type AnalysisResult = {
+  ...ScanResult,
+  start: number,
+  end: number,
+};
+
+export type AnalysisResultCallback = (result: AnalysisResult) => void;
+
+export type DOMObserveCallback = (list: Array<WeakRef<Element>>) => void;

package/src/memlens.lib.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import ReactMemoryScan from './core/react-memory-scan';
+import {CreateOptions} from './core/types';
+// import { DOMVisualizationExtension } from './extensions/dom-visualization-extension';
+
+export function createReactMemoryScan(
+  options: CreateOptions = {},
+): ReactMemoryScan {
+  return new ReactMemoryScan(options);
+  // const memoryScan = new ReactMemoryScan(options);
+  // const domVisualizer = new DOMVisualizationExtension(memoryScan);
+  // memoryScan.registerExtension(domVisualizer);
+  // return memoryScan;
+}

package/src/memlens.run.ts

@@ -0,0 +1,21 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import ReactMemoryScan from './core/react-memory-scan';
+import {DOMVisualizationExtension} from './extensions/dom-visualization-extension';
+import {hasRunInSession, setRunInSession} from './utils/utils';
+
+if (!hasRunInSession()) {
+  const memoryScan = new ReactMemoryScan({isDevMode: true});
+  const domVisualizer = new DOMVisualizationExtension(memoryScan);
+  memoryScan.registerExtension(domVisualizer);
+
+  memoryScan.start();
+  setRunInSession();
+}

package/src/tests/bundle/lib.bundle.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type {AnyValue} from '../../core/types';
+import {test, expect} from '@playwright/test';
+import {libBundleFilePath} from '../utils/test-utils';
+
+test('test library in browser via addScriptTag', async ({page}) => {
+  // Navigate to an empty page (or a test page)
+  await page.goto('about:blank');
+
+  // Inject the lib bundle file (UMD bundle of the library) into the page
+  await page.addScriptTag({path: libBundleFilePath});
+
+  // Now the global `MemLens` should be available in the page
+  const libraryLoaded = await page.evaluate(() => {
+    const createReactMemoryScan = (window as AnyValue).MemLens
+      .createReactMemoryScan;
+    const instance = createReactMemoryScan();
+    const analysisResult = instance.scan();
+    return typeof analysisResult.totalElements === 'number';
+  });
+
+  expect(libraryLoaded).toBe(true);
+});

package/src/tests/bundle/run.bundle.start.head.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import {test, expect} from '@playwright/test';
+import fs from 'fs';
+import {wait} from '../utils/test-utils';
+import {runBundleFilePath} from '../utils/test-utils';
+
+test.describe('run.bundle.js functionality', () => {
+  test('should load and execute correctly', async ({page}) => {
+    const bundleCode = fs.readFileSync(runBundleFilePath, 'utf8');
+
+    let bundleLoaded = false;
+    // Listen for console messages
+    page.on('console', message => {
+      // add console.log(message) if you would like to debug
+      const msgText = message.text();
+      if (msgText.includes('Tracking React and DOM memory')) {
+        bundleLoaded = true;
+      }
+    });
+
+    await page.setContent(`
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <script>
+            ${bundleCode}
+          </script>
+        </head>
+        <body>
+          <div id="test-container"></div>
+        </body>
+      </html>
+    `);
+
+    await wait(2000);
+
+    // check if the bundle loaded successfully
+    expect(bundleLoaded).toBe(true);
+  });
+});

package/src/tests/bundle/run.bundle.start.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import {test, expect} from '@playwright/test';
+import fs from 'fs';
+import {wait} from '../utils/test-utils';
+import {runBundleFilePath} from '../utils/test-utils';
+
+test.describe('run.bundle.js functionality', () => {
+  test('should load and execute correctly', async ({page}) => {
+    const bundleCode = fs.readFileSync(runBundleFilePath, 'utf8');
+
+    let bundleLoaded = false;
+    // Listen for console messages
+    page.on('console', message => {
+      // add console.log(message) if you would like to debug
+      const msgText = message.text();
+      if (msgText.includes('Tracking React and DOM memory')) {
+        bundleLoaded = true;
+      }
+    });
+
+    await page.setContent(`
+      <!DOCTYPE html>
+      <html>
+        <head>
+        </head>
+        <body>
+          <div id="test-container"></div>
+          <script>
+            ${bundleCode}
+          </script>
+        </body>
+      </html>
+    `);
+
+    await wait(1000);
+
+    // check if the bundle loaded successfully
+    expect(bundleLoaded).toBe(true);
+  });
+});

package/src/tests/bundle/run.bundle.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import {test, expect} from '@playwright/test';
+import fs from 'fs';
+import {wait} from '../utils/test-utils';
+import {runBundleFilePath} from '../utils/test-utils';
+
+test.describe('run.bundle.js functionality', () => {
+  test('should load and execute correctly', async ({page}) => {
+    const bundleCode = fs.readFileSync(runBundleFilePath, 'utf8');
+
+    let bundleLoaded = false;
+    // Listen for console messages
+    page.on('console', message => {
+      // add console.log(message) if you would like to debug
+      const msgText = message.text();
+      if (msgText.includes('duration:')) {
+        bundleLoaded = true;
+      }
+    });
+
+    await page.setContent(`
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <script>
+            window.TEST_MEMORY_SCAN = true;
+          </script>
+        </head>
+        <body>
+          <div id="test-container"></div>
+          <script>
+            ${bundleCode}
+          </script>
+        </body>
+      </html>
+    `);
+
+    await wait(2000);
+
+    // check if the bundle loaded successfully
+    expect(bundleLoaded).toBe(true);
+  });
+});

package/src/tests/fiber/dev.fiber.complex.dev.test.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type {AnyValue} from '../../core/types';
+
+import {test, expect} from '@playwright/test';
+import path from 'path';
+import fs from 'fs';
+import {srcPath} from '../utils/test-utils';
+import {libBundleFilePath} from '../utils/test-utils';
+
+test('scan should identify react components in a complex fiber tree (React 18 Dev)', async ({
+  page,
+}) => {
+  const bundleCode = fs.readFileSync(libBundleFilePath, 'utf8');
+
+  const reactDevPath = path.join(srcPath, 'tests', 'lib', 'react-v18.dev.js');
+  const reactDevCode = fs.readFileSync(reactDevPath, 'utf8');
+
+  const reactDOMDevPath = path.join(
+    srcPath,
+    'tests',
+    'lib',
+    'react-dom-v18.dev.js',
+  );
+  const reactDOMDevCode = fs.readFileSync(reactDOMDevPath, 'utf8');
+
+  // Create a simple test page with React and a custom component
+  await page.setContent(`
+    <html>
+      <body>
+        <div id="root"></div>
+        <script>${reactDevCode}</script>
+        <script>${reactDOMDevCode}</script>
+        <script>${bundleCode}</script>
+        <script>
+          function TopContainer() {
+            return React.createElement(
+              'div',
+              null,
+              React.createElement(TestContainer),
+              React.createElement(TestContainer),
+              React.createElement(TestContainer),
+            );
+          }
+          function TestContainer() {
+            return React.createElement(
+              'div',
+              null,
+              React.createElement(TestComponent),
+              React.createElement(TestComponent)
+            );
+          }
+
+          function TestComponent() {
+            return React.createElement('div', null, 'Test Component');
+          }
+
+          ReactDOM.render(
+            React.createElement(TopContainer),
+            document.getElementById('root')
+          );
+        </script>
+      </body>
+    </html>
+  `);
+
+  // Now the global `MemLens` should be available in the page
+  const componentIdentified = await page.evaluate(() => {
+    const createReactMemoryScan = (window as AnyValue).MemLens
+      .createReactMemoryScan;
+    const instance = createReactMemoryScan();
+    const analysisResult = instance.scan();
+    const componentCountCorrect =
+      analysisResult.componentToFiberNodeCount.get('TestComponent') === 6;
+    const containerCountCorrect =
+      analysisResult.componentToFiberNodeCount.get('TestContainer') === 3;
+    const topContainerCountCorrect =
+      analysisResult.componentToFiberNodeCount.get('TopContainer') === 1;
+    return (
+      componentCountCorrect && containerCountCorrect && topContainerCountCorrect
+    );
+  });
+
+  expect(componentIdentified).toBe(true);
+});

package/src/tests/fiber/dev.fiber.complex.list.dev.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import {AnyValue} from '../../core/types';
+import {test, expect} from '@playwright/test';
+import path from 'path';
+import fs from 'fs';
+import {srcPath} from '../utils/test-utils';
+import {libBundleFilePath} from '../utils/test-utils';
+
+test('scan should identify react components in a complex list fiber tree (React 18 Dev)', async ({
+  page,
+}) => {
+  const bundleCode = fs.readFileSync(libBundleFilePath, 'utf8');
+
+  const reactDevPath = path.join(srcPath, 'tests', 'lib', 'react-v18.dev.js');
+  const reactDevCode = fs.readFileSync(reactDevPath, 'utf8');
+
+  const reactDOMDevPath = path.join(
+    srcPath,
+    'tests',
+    'lib',
+    'react-dom-v18.dev.js',
+  );
+  const reactDOMDevCode = fs.readFileSync(reactDOMDevPath, 'utf8');
+
+  // Create a test page with React and some list components
+  await page.setContent(`
+    <html>
+      <body>
+        <div id="root"></div>
+        <script>${reactDevCode}</script>
+        <script>${reactDOMDevCode}</script>
+        <script>${bundleCode}</script>
+        <script>
+          function ListItem({ text, count }) {
+            return React.createElement('li', null, \`$\{text} ($\{count})\`);
+          }
+
+          function List({ items }) {
+            return React.createElement(
+              'ul',
+              { className: 'list-container' },
+              items.map((item, index) =>
+                React.createElement(ListItem, {
+                  key: index,
+                  text: item.text,
+                  count: item.count
+                })
+              )
+            );
+          }
+
+          function Counter({ initialCount }) {
+            const [count, setCount] = React.useState(initialCount);
+
+            return React.createElement(
+              'div',
+              { className: 'counter' },
+              React.createElement('span', null, \`Count: $\{count}\`),
+              React.createElement(
+                'button',
+                { onClick: () => setCount(count + 1) },
+                'Increment'
+              )
+            );
+          }
+
+          function TestContainer() {
+            const listSetup = [];
+            for (let i = 0; i < 1000; ++i) {
+              listSetup.push({ text: 'Item ' + i, count: i });
+            }
+            const [items] = React.useState(listSetup);
+
+            return React.createElement(
+              'div',
+              { className: 'container' },
+              React.createElement('h1', null, 'Test Application'),
+              React.createElement(Counter, { initialCount: 0 }),
+              React.createElement(Counter, { initialCount: 10 }),
+              React.createElement(List, { items: items }),
+              React.createElement(List, { items: items.slice(0, 500) })
+            );
+          }
+
+          ReactDOM.render(
+            React.createElement(TestContainer),
+            document.getElementById('root')
+          );
+        </script>
+      </body>
+    </html>
+  `);
+
+  // Now the global `MemLens` should be available in the page
+  const componentIdentified = await page.evaluate(() => {
+    const createReactMemoryScan = (window as AnyValue).MemLens
+      .createReactMemoryScan;
+    const instance = createReactMemoryScan();
+    const analysisResult = instance.scan();
+    const counterCorrect =
+      analysisResult.componentToFiberNodeCount.get('Counter') === 2;
+    const listCorrect =
+      analysisResult.componentToFiberNodeCount.get('List') === 2;
+    const listItemCorrect =
+      analysisResult.componentToFiberNodeCount.get('ListItem') === 1500;
+    return counterCorrect && listCorrect && listItemCorrect;
+  });
+
+  expect(componentIdentified).toBe(true);
+});