@memlab/lens 1.0.0

package/src/core/react-fiber-analysis.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 utils from '../utils/utils';
+import type {Fiber} from 'react-reconciler';
+import {
+  traverseFiber,
+  getDisplayNameOfFiberNode,
+  getFiberNodeFromElement,
+  getTopMostFiberWithChild,
+} from '../utils/react-fiber-utils';
+import {ScanResult, AnyValue} from './types';
+import {isValidComponentName} from './valid-component-name';
+
+export default class ReactFiberAnalyzer {
+  scan(
+    elementWeakRefList: Array<WeakRef<Element>>,
+    elementToComponentStack: WeakMap<Element, string[]>,
+  ): ScanResult {
+    const visitedRootFibers = new Set<Fiber>();
+    const components = new Set<string>();
+    const componentToFiberNodeCount = new Map();
+    const detachedComponentToFiberNodeCount = new Map();
+    const topDownVisited = new Set();
+    const analyzedFibers = new Set();
+    const fiberNodes: Array<WeakRef<Fiber>> = [];
+    let totalElements = 0;
+    let totalDetachedElements = 0;
+
+    function analyzeFiber(fiberNode: Fiber): void {
+      traverseFiber(
+        fiberNode,
+        (fiberNode: Fiber) => {
+          // skip if the fiber node has already been analyzed
+          if (analyzedFibers.has(fiberNode)) {
+            return true;
+          }
+          analyzedFibers.add(fiberNode);
+
+          // traverse the fiber tree up to find the component name
+          const displayName = getDisplayNameOfFiberNode(fiberNode);
+          if (displayName != null && isValidComponentName(displayName)) {
+            components.add(displayName);
+            utils.addCountbyKey(componentToFiberNodeCount, displayName, 1);
+            return true;
+          }
+        },
+        true,
+      );
+    }
+
+    for (const weakRef of elementWeakRefList) {
+      const elem = weakRef.deref();
+      if (elem == null) {
+        continue;
+      }
+      // elements stats
+      ++totalElements;
+      // TODO: simplify this logic
+      if (!elem.isConnected) {
+        if (elementToComponentStack.has(elem)) {
+          const componentStack = elementToComponentStack.get(elem) ?? [];
+          // set component name
+          const component = componentStack[0];
+          (elem as AnyValue).__component_name = component;
+          utils.addCountbyKey(detachedComponentToFiberNodeCount, component, 1);
+        }
+        ++totalDetachedElements;
+      }
+
+      // analyze fiber nodes
+      const fiberNode = getFiberNodeFromElement(elem);
+      if (fiberNode == null) {
+        continue;
+      }
+      analyzeFiber(fiberNode);
+
+      // try to traverse each fiber node in the entire fiber tree
+      const rootFiber = getTopMostFiberWithChild(fiberNode);
+      if (rootFiber == null) {
+        continue;
+      }
+      if (visitedRootFibers.has(rootFiber)) {
+        continue;
+      }
+      visitedRootFibers.add(rootFiber);
+
+      // start traversing fiber tree from the know root host
+      traverseFiber(
+        rootFiber,
+        (node: Fiber) => {
+          if (topDownVisited.has(node)) {
+            return true;
+          }
+          topDownVisited.add(node);
+          fiberNodes.push(new WeakRef(node));
+          analyzeFiber(node);
+        },
+        false,
+      );
+    }
+
+    topDownVisited.clear();
+    analyzedFibers.clear();
+    visitedRootFibers.clear();
+
+    return {
+      components,
+      componentToFiberNodeCount,
+      totalElements,
+      totalDetachedElements,
+      detachedComponentToFiberNodeCount,
+      fiberNodes,
+      leakedFibers: [],
+    };
+  }
+}

package/src/core/react-memory-scan.ts

@@ -0,0 +1,366 @@
+/**
+ * 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 {Fiber} from 'react-reconciler';
+import type {
+  AnalysisResult,
+  AnalysisResultCallback,
+  BoundingRect,
+  CreateOptions,
+  DOMElementInfo,
+  Optional,
+  ScanResult,
+  AnyValue,
+  EventListenerLeak,
+  Nullable,
+} from './types';
+import type {BasicExtension} from '../extensions/basic-extension';
+
+import * as utils from '../utils/utils';
+import ReactFiberAnalyzer from './react-fiber-analysis';
+import {
+  getFiberNodeFromElement,
+  getReactComponentStack,
+} from '../utils/react-fiber-utils';
+import {DOMObserver} from './dom-observer';
+import {config} from '../config/config';
+import {EventListenerTracker} from './event-listener-tracker';
+
+export default class ReactMemoryScan {
+  static nextElementId = 0;
+  #elementWeakRefs: Array<WeakRef<Element>>;
+  #isActivated: boolean;
+  #intervalId: NodeJS.Timeout;
+  #elementToBoundingRects: WeakMap<Element, BoundingRect>;
+  #elementToComponentStack: WeakMap<Element, string[]>;
+  #knownFiberNodes: Array<WeakRef<Fiber>>;
+  #fiberAnalyzer: ReactFiberAnalyzer;
+  #isDevMode: boolean;
+  #subscribers: Array<AnalysisResultCallback>;
+  #extensions: Array<BasicExtension>;
+  #scanIntervalMs: number;
+  #domObserver: Optional<DOMObserver>;
+  #eventListenerTracker: Nullable<EventListenerTracker>;
+
+  constructor(options: CreateOptions = {}) {
+    this.#elementWeakRefs = [];
+    this.#isActivated = false;
+    this.#elementToBoundingRects = new WeakMap();
+    this.#elementToComponentStack = new WeakMap();
+    this.#knownFiberNodes = [];
+    this.#eventListenerTracker = options.trackEventListenerLeaks
+      ? EventListenerTracker.getInstance()
+      : null;
+
+    this.#fiberAnalyzer = new ReactFiberAnalyzer();
+    this.#intervalId = 0 as unknown as NodeJS.Timeout;
+    this.#isDevMode = options.isDevMode ?? false;
+    this.#subscribers = options.subscribers ?? [];
+    this.#extensions = options.extensions ?? [];
+    this.#scanIntervalMs =
+      options.scanIntervalMs ?? config.performance.scanIntervalMs;
+  }
+
+  #log(...args: AnyValue[]): void {
+    if (this.#isDevMode && config.features.enableConsoleLogs) {
+      utils.consoleLog(...args);
+    }
+  }
+
+  subscribe(callback: AnalysisResultCallback): () => void {
+    this.#subscribers.push(callback);
+    return () => this.unsubscribe(callback);
+  }
+
+  unsubscribe(callback: AnalysisResultCallback): void {
+    this.#subscribers = this.#subscribers.filter(cb => cb !== callback);
+  }
+
+  #notifySubscribers(result: AnalysisResult): void {
+    for (const subscriber of this.#subscribers) {
+      subscriber(result);
+    }
+    const duration = result.end - result.start;
+    this.#log('duration: ', `${duration} ms`);
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const {scanner, leakedFibers, fiberNodes, ...rest} = result;
+    this.#log(rest);
+  }
+
+  registerExtension(extension: BasicExtension): () => void {
+    this.#extensions.push(extension);
+    return () => this.unregisterExtension(extension);
+  }
+
+  unregisterExtension(extension: BasicExtension): void {
+    this.#extensions = this.#extensions.filter(e => e !== extension);
+  }
+
+  #notifyExtensionsBeforeScan(): void {
+    for (const extension of this.#extensions) {
+      extension?.beforeScan();
+    }
+  }
+
+  #notifyExtensionsAfterScan(result: AnalysisResult): void {
+    for (const extension of this.#extensions) {
+      extension?.afterScan(result);
+    }
+  }
+
+  start() {
+    this.#isActivated = true;
+    this.#intervalId = setInterval(
+      this.#scanCycle.bind(this),
+      this.#scanIntervalMs,
+    );
+    if (config.features.enableMutationObserver) {
+      if (this.#domObserver == null) {
+        this.#domObserver = new DOMObserver();
+        // NOTE: do not update the fiber or component information here
+        // with this.#domObserver.register as those elements in the delta
+        // list may be unmounted or just attached and their shape and
+        // component info is not correct or not set yet
+      }
+      this.#domObserver.startMonitoring();
+    }
+    console.log('[Memory] Tracking React and DOM memory...');
+  }
+
+  #scanCycle() {
+    if (!this.#isActivated) {
+      return;
+    }
+    this.#notifyExtensionsBeforeScan();
+    const start = performance.now();
+    const stats = this.scan();
+    const end = performance.now();
+
+    // inform subscribers and extensions
+    const analysiResult = {
+      ...stats,
+      start,
+      end,
+      scanner: this,
+    };
+    this.#notifySubscribers(analysiResult);
+    this.#notifyExtensionsAfterScan(analysiResult);
+  }
+
+  pause() {
+    this.#isActivated = false;
+  }
+
+  stop() {
+    this.#isActivated = false;
+    clearInterval(this.#intervalId);
+    this.#elementWeakRefs = [];
+    this.#domObserver?.stopMonitoring();
+  }
+
+  recordBoundingRectangles(elementRefs: Array<WeakRef<Element>>) {
+    for (const elemRef of elementRefs) {
+      const element = elemRef.deref();
+      if (element == null || this.#elementToBoundingRects.has(element)) {
+        continue;
+      }
+      const rect = utils.getBoundingClientRect(element);
+      if (rect != null) {
+        this.#elementToBoundingRects.set(element, rect);
+      }
+    }
+  }
+
+  getDetachedDOMInfo(): Array<DOMElementInfo> {
+    const detachedDOMElements = [];
+    for (const weakRef of this.#elementWeakRefs) {
+      const element = weakRef.deref();
+      if (element == null || element.isConnected) {
+        continue;
+      }
+      // add a unique id to that detach dom element
+      const elem = element as AnyValue;
+      if (elem.detachedElementId == null) {
+        const elementId = ReactMemoryScan.nextElementId++;
+        elem.detachedElementIdStr = `memory-id-${elementId}@`;
+        elem.detachedElementId = elementId;
+      }
+      const componentStack = this.#elementToComponentStack.get(element) ?? [];
+      detachedDOMElements.push({
+        element: weakRef,
+        boundingRect: this.#elementToBoundingRects.get(element),
+        componentStack,
+      });
+    }
+    return detachedDOMElements;
+  }
+
+  isDevMode(): boolean {
+    return this.#isDevMode;
+  }
+
+  #updateElementToComponentInfo(elements: Array<WeakRef<Element>>): void {
+    for (const elemRef of elements) {
+      const element = elemRef.deref();
+      if (element == null || this.#elementToComponentStack.has(element)) {
+        continue;
+      }
+      const fiberNode = getFiberNodeFromElement(element);
+      if (fiberNode == null) {
+        continue;
+      }
+      this.#elementToComponentStack.set(
+        element,
+        getReactComponentStack(fiberNode),
+      );
+    }
+  }
+
+  getCachedComponentName(elementRef: WeakRef<Element>): string {
+    const FALLBACK_NAME = '<Unknown>';
+    const element = elementRef.deref();
+    if (element == null) {
+      return FALLBACK_NAME;
+    }
+    const componentStack = this.#elementToComponentStack.get(element);
+    if (componentStack == null) {
+      return FALLBACK_NAME;
+    }
+    return componentStack[0] ?? FALLBACK_NAME;
+  }
+
+  updateFiberNodes(fiberNodes: Array<WeakRef<Fiber>>): Array<WeakRef<Fiber>> {
+    const knownFiberSet = new WeakSet<Fiber>();
+    for (const fiberNode of this.#knownFiberNodes) {
+      const fiber = fiberNode.deref();
+      if (fiber != null) {
+        knownFiberSet.add(fiber);
+      }
+    }
+    const newFiberSet = new WeakSet<Fiber>();
+    for (const fiberNode of fiberNodes) {
+      const fiber = fiberNode.deref();
+      if (fiber != null) {
+        newFiberSet.add(fiber);
+      }
+    }
+    const leakedFibers: Array<WeakRef<Fiber>> = [];
+    const newExistingFibers: Array<WeakRef<Fiber>> = [];
+    // clean up and compact the existing fiber node lists
+    for (const fiberRef of this.#knownFiberNodes) {
+      const fiber = fiberRef.deref();
+      if (fiber == null) {
+        continue;
+      }
+      if (!newFiberSet.has(fiber)) {
+        leakedFibers.push(fiberRef);
+      } else {
+        newExistingFibers.push(fiberRef);
+        if (fiber.return == null) {
+          leakedFibers.push(fiberRef);
+        }
+      }
+    }
+    // add new fibers to the existing list
+    for (const fiberRef of fiberNodes) {
+      const fiber = fiberRef.deref();
+      if (fiber == null) {
+        continue;
+      }
+      if (!knownFiberSet.has(fiber)) {
+        newExistingFibers.push(fiberRef);
+      }
+    }
+    this.#knownFiberNodes = newExistingFibers;
+    this.#log('known fibers: ', this.#knownFiberNodes.length);
+    this.#log('leaked fibers: ', leakedFibers.length);
+    return leakedFibers;
+  }
+
+  packLeakedFibers(leakedFibers: Array<WeakRef<Fiber>>): Array<LeakedFiber> {
+    const ret = [];
+    for (const leakedFiber of leakedFibers) {
+      ret.push(new LeakedFiber(leakedFiber));
+    }
+    return ret;
+  }
+
+  #getTrackedDOMRefs(): Array<WeakRef<Element>> {
+    if (this.#domObserver == null) {
+      return utils.getDOMElements();
+    }
+    return [...utils.getDOMElements(), ...this.#domObserver.getDOMElements()];
+  }
+
+  #runGC(): void {
+    if ((window as AnyValue)?.gc != null) {
+      (window as AnyValue).gc();
+    }
+  }
+
+  #scanEventListenerLeaks(): EventListenerLeak[] {
+    if (this.#eventListenerTracker == null) {
+      return [];
+    }
+    // Scan for event listener leaks
+    const detachedListeners = this.#eventListenerTracker.scan(
+      this.getCachedComponentName.bind(this),
+    );
+    const eventListenerLeaks: EventListenerLeak[] = [];
+    for (const [componentName, listeners] of detachedListeners.entries()) {
+      const typeCount = new Map<string, number>();
+      for (const listener of listeners) {
+        const count = typeCount.get(listener.type) ?? 0;
+        typeCount.set(listener.type, count + 1);
+      }
+      for (const [type, count] of typeCount.entries()) {
+        eventListenerLeaks.push({
+          type,
+          componentName,
+          count,
+        });
+      }
+    }
+    return eventListenerLeaks;
+  }
+
+  scan(): ScanResult {
+    const start = Date.now();
+    this.#runGC();
+    const weakRefList = this.#elementWeakRefs;
+    // TODO: associate elements with URL and other metadata
+    const allElements = this.#getTrackedDOMRefs();
+    this.#updateElementToComponentInfo(allElements);
+    this.recordBoundingRectangles(allElements);
+    utils.updateWeakRefList(weakRefList, allElements);
+    const scanResult = this.#fiberAnalyzer.scan(
+      weakRefList,
+      this.#elementToComponentStack,
+    );
+    const leakedFibers = this.updateFiberNodes(scanResult.fiberNodes);
+    scanResult.leakedFibers = leakedFibers;
+
+    // scan for event listener leaks
+    // TODO: show the results in the UI widget
+    scanResult.eventListenerLeaks = this.#scanEventListenerLeaks();
+
+    (window as AnyValue).leakedFibers = this.packLeakedFibers(leakedFibers);
+    const end = Date.now();
+    this.#log(`scan took ${end - start}ms`);
+    return scanResult;
+  }
+}
+
+class LeakedFiber {
+  leakedFiber: WeakRef<Fiber>;
+
+  constructor(fiber: WeakRef<Fiber>) {
+    this.leakedFiber = fiber;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 {Fiber} from 'react-reconciler';
+import type {BasicExtension} from '../extensions/basic-extension';
+import type ReactMemoryScan from './react-memory-scan';
+
+/** @internal */
+export type AnyValue = any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+/** @internal */
+export type ObjectValue = {[key: string]: AnyValue};
+
+/** @internal */
+export type RecordValue =
+  | string
+  | number
+  | boolean
+  | null
+  | RecordValue[]
+  | {[key: string]: RecordValue};
+
+/**
+ * Given any type `T`, return the union type `T` and `null`
+ * @typeParam T - The type that will be made nullable.
+ */
+export type Nullable<T> = T | null;
+
+/**
+ * Given any type `T`, return the union type `T`, `null`, and `undefined`.
+ * @typeParam T - The type that will be made both nullable and undefinable.
+ */
+export type Optional<T> = T | null | undefined;
+
+/**
+ * Given any type `T`, return the union type `T` and `undefined`.
+ * @typeParam T - The type that will be made undefinable.
+ */
+export type Undefinable<T> = T | undefined;
+
+/** @internal */
+export type AnyRecord = Record<string, RecordValue>;
+/** @internal */
+export type StringRecord = Record<string, string>;
+
+/**
+ * Options for creating a ReactMemoryScan instance
+ * @property {boolean} [isDevMode] - When true, enables dev mode features
+ */
+export type CreateOptions = {
+  isDevMode?: boolean;
+  subscribers?: Array<AnalysisResultCallback>;
+  extensions?: Array<BasicExtension>;
+  scanIntervalMs?: number;
+  trackEventListenerLeaks?: boolean;
+};
+
+/**
+ * Result of scanning react fiber tree and DOM elements
+ * @property {Set<string>} components - Set of component names found in the fiber tree
+ * @property {Map<string, number>} componentToFiberNodeCount - Map of component names to their instance counts
+ * @property {number} totalElements - Total number of DOM elements found
+ * @property {number} totalDetachedElements - Number of detached DOM elements found
+ * @property {Map<string, number>} detachedComponentToFiberNodeCount - Map of component names to their detached instance counts
+ */
+export type EventListenerLeak = {
+  type: string;
+  componentName: string;
+  count: 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>>;
+  eventListenerLeaks?: EventListenerLeak[];
+};
+
+/**
+ * Result of analyzing React fiber nodes and DOM elements
+ * @property {number} start - Start time of the analysis
+ * @property {number} end - End time of the analysis
+ */
+export type AnalysisResult = ScanResult & {
+  start: number;
+  end: number;
+  scanner: ReactMemoryScan;
+};
+
+/**
+ * Callback function type for analysis results
+ * @param {AnalysisResult} result - The analysis result
+ */
+export type AnalysisResultCallback = (result: AnalysisResult) => void;
+
+/**
+ * Represents the dimensions and position of an element's bounding box
+ * @property {number} x - The x-coordinate of the element's left edge relative to the viewport
+ * @property {number} y - The y-coordinate of the element's top edge relative to the viewport
+ * @property {number} width - The width of the element's bounding box
+ * @property {number} height - The height of the element's bounding box
+ * @property {number} top - The distance from the top of the viewport to the element's top edge
+ * @property {number} right - The distance from the left of the viewport to the element's right edge
+ * @property {number} bottom - The distance from the top of the viewport to the element's bottom edge
+ * @property {number} left - The distance from the left of the viewport to the element's left edge
+ * @property {number} scrollLeft - The scroll distance from the left of the viewport to the element's left edge
+ * @property {number} scrollTop - The scroll distance from the top of the viewport to the element's top edge
+ */
+export interface BoundingRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+  scrollLeft: number;
+  scrollTop: number;
+}
+
+/**
+ * Represents information about a DOM element
+ * @property {WeakRef<Element>} element - A weak reference to the DOM element
+ * @property {Optional<BoundingRect>} boundingRect - The bounding rectangle of the element
+ * @property {Optional<string>} component - The react component name associated with the element
+ */
+export type DOMElementInfo = {
+  element: WeakRef<Element>;
+  boundingRect: Optional<BoundingRect>;
+  componentStack: Optional<string[]>;
+};
+
+/** @internal */
+export type DOMElementStats = {
+  elements: number;
+  detachedElements: number;
+};
+
+export type DOMObserveCallback = (list: Array<WeakRef<Element>>) => void;
+
+export type PerformanceConfig = {
+  scanIntervalMs: number;
+  maxComponentStackDepth: number;
+  memoryMeasurementIntervalMs: number;
+};
+
+export type FeatureFlags = {
+  enableMutationObserver: boolean;
+  enableMemoryTracking: boolean;
+  enableComponentStack: boolean;
+  enableConsoleLogs: boolean;
+};
+
+export type Config = {
+  performance: PerformanceConfig;
+  features: FeatureFlags;
+};
+
+export type Entry<K extends object, V> = {
+  ref: WeakRef<K>;
+  value: V;
+};
+
+export type FallbackMode = 'strong' | 'noop';
+
+export type WeakMapPlusOptions = {
+  fallback?: FallbackMode;
+  cleanupMs?: number;
+};

package/src/core/valid-component-name.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 {Optional} from './types';
+
+const displayNameBlockList = new Set();
+
+export function isValidComponentName(name: Optional<string>): boolean {
+  return name != null && !displayNameBlockList.has(name);
+}