@memlab/lens 1.0.0 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Meta Platforms, Inc. and affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/config.d.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 { Config } from '../core/types';
+export declare const performanceConfig: {
+    scanIntervalMs: number;
+    maxComponentStackDepth: number;
+    memoryMeasurementIntervalMs: number;
+};
+export declare const featureFlags: {
+    enableMutationObserver: boolean;
+    enableMemoryTracking: boolean;
+    enableComponentStack: boolean;
+    enableConsoleLogs: any;
+};
+export declare const config: Config;

package/dist/core/dom-observer.d.ts

@@ -0,0 +1,10 @@
+import { DOMElementStats, DOMObserveCallback } from './types';
+export declare class DOMObserver {
+    #private;
+    constructor();
+    register(callback: DOMObserveCallback): void;
+    startMonitoring(): void;
+    stopMonitoring(): void;
+    getDOMElements(): Array<WeakRef<Element>>;
+    getStats(): DOMElementStats;
+}

package/dist/core/event-listener-tracker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+type EventListenerEntry = {
+    type: string;
+    cb: WeakRef<EventListenerOrEventListenerObject>;
+    options?: boolean | AddEventListenerOptions;
+    fiber?: WeakRef<Fiber>;
+};
+type DetachedListenerGroup = {
+    type: string;
+    count: number;
+    entries: WeakRef<EventListenerEntry>[];
+};
+export declare class EventListenerTracker {
+    #private;
+    private static instance;
+    private constructor();
+    static getInstance(): EventListenerTracker;
+    addListener(el: EventTarget, type: string, cb: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    removeListener(el: EventTarget, type: string, cb: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+    scan(getComponentName: (elRef: WeakRef<Element>) => string): Map<string, DetachedListenerGroup[]>;
+    getDetachedListeners(): Map<string, DetachedListenerGroup[]>;
+    destroy(): void;
+}
+export {};

package/dist/core/react-fiber-analysis.d.ts

@@ -0,0 +1,4 @@
+import { ScanResult } from './types';
+export default class ReactFiberAnalyzer {
+    scan(elementWeakRefList: Array<WeakRef<Element>>, elementToComponentStack: WeakMap<Element, string[]>): ScanResult;
+}

package/dist/core/react-memory-scan.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { AnalysisResultCallback, CreateOptions, DOMElementInfo, ScanResult } from './types';
+import type { BasicExtension } from '../extensions/basic-extension';
+export default class ReactMemoryScan {
+    #private;
+    static nextElementId: number;
+    constructor(options?: CreateOptions);
+    subscribe(callback: AnalysisResultCallback): () => void;
+    unsubscribe(callback: AnalysisResultCallback): void;
+    registerExtension(extension: BasicExtension): () => void;
+    unregisterExtension(extension: BasicExtension): void;
+    start(): void;
+    pause(): void;
+    stop(): void;
+    recordBoundingRectangles(elementRefs: Array<WeakRef<Element>>): void;
+    getDetachedDOMInfo(): Array<DOMElementInfo>;
+    isDevMode(): boolean;
+    getCachedComponentName(elementRef: WeakRef<Element>): string;
+    updateFiberNodes(fiberNodes: Array<WeakRef<Fiber>>): Array<WeakRef<Fiber>>;
+    packLeakedFibers(leakedFibers: Array<WeakRef<Fiber>>): Array<LeakedFiber>;
+    scan(): ScanResult;
+}
+declare class LeakedFiber {
+    leakedFiber: WeakRef<Fiber>;
+    constructor(fiber: WeakRef<Fiber>);
+}
+export {};

package/{src/core/types.ts → dist/core/types.d.ts}

@@ -7,60 +7,49 @@
  * @format
  * @oncall memory_lab
  */
-import {Fiber} from 'react-reconciler';
-import type {BasicExtension} from '../extensions/basic-extension';
+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
-
+export type AnyValue = any;
 /** @internal */
-export type ObjectValue = {[key: string]: AnyValue};
-
+export type ObjectValue = {
+    [key: string]: AnyValue;
+};
 /** @internal */
-export type RecordValue =
-  | string
-  | number
-  | boolean
-  | null
-  | RecordValue[]
-  | {[key: string]: RecordValue};
-
+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;
+    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
@@ -70,39 +59,35 @@ export type CreateOptions = {
  * @property {Map<string, number>} detachedComponentToFiberNodeCount - Map of component names to their detached instance counts
  */
 export type EventListenerLeak = {
-  type: string;
-  componentName: string;
-  count: number;
+    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[];
+    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;
+    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
@@ -117,18 +102,17 @@ export type AnalysisResultCallback = (result: AnalysisResult) => void;
  * @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;
+    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
@@ -136,45 +120,37 @@ export interface BoundingRect {
  * @property {Optional<string>} component - The react component name associated with the element
  */
 export type DOMElementInfo = {
-  element: WeakRef<Element>;
-  boundingRect: Optional<BoundingRect>;
-  componentStack: Optional<string[]>;
+    element: WeakRef<Element>;
+    boundingRect: Optional<BoundingRect>;
+    componentStack: Optional<string[]>;
 };
-
 /** @internal */
 export type DOMElementStats = {
-  elements: number;
-  detachedElements: number;
+    elements: number;
+    detachedElements: number;
 };
-
 export type DOMObserveCallback = (list: Array<WeakRef<Element>>) => void;
-
 export type PerformanceConfig = {
-  scanIntervalMs: number;
-  maxComponentStackDepth: number;
-  memoryMeasurementIntervalMs: number;
+    scanIntervalMs: number;
+    maxComponentStackDepth: number;
+    memoryMeasurementIntervalMs: number;
 };
-
 export type FeatureFlags = {
-  enableMutationObserver: boolean;
-  enableMemoryTracking: boolean;
-  enableComponentStack: boolean;
-  enableConsoleLogs: boolean;
+    enableMutationObserver: boolean;
+    enableMemoryTracking: boolean;
+    enableComponentStack: boolean;
+    enableConsoleLogs: boolean;
 };
-
 export type Config = {
-  performance: PerformanceConfig;
-  features: FeatureFlags;
+    performance: PerformanceConfig;
+    features: FeatureFlags;
 };
-
 export type Entry<K extends object, V> = {
-  ref: WeakRef<K>;
-  value: V;
+    ref: WeakRef<K>;
+    value: V;
 };
-
 export type FallbackMode = 'strong' | 'noop';
-
 export type WeakMapPlusOptions = {
-  fallback?: FallbackMode;
-  cleanupMs?: number;
+    fallback?: FallbackMode;
+    cleanupMs?: number;
 };

package/{src/index.ts → dist/core/valid-component-name.d.ts}

@@ -7,10 +7,5 @@
  * @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');
-}
+import { Optional } from './types';
+export declare function isValidComponentName(name: Optional<string>): boolean;

package/dist/extensions/basic-extension.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare abstract class BasicExtension {
+    protected readonly scanner: ReactMemoryScan;
+    constructor(scanner: ReactMemoryScan);
+    /**
+     * Hook that runs before the memory scan starts.
+     * Override this method to perform any setup or pre-scan operations.
+     */
+    beforeScan(): void;
+    /**
+     * 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
+     */
+    afterScan(_analysisResult: AnalysisResult): void;
+}

package/dist/extensions/dom-visualization-extension.d.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 type ReactMemoryScan from '../core/react-memory-scan';
+import type { AnalysisResult } from '../core/types';
+import { BasicExtension } from './basic-extension';
+export declare class DOMVisualizationExtension extends BasicExtension {
+    #private;
+    constructor(scanner: ReactMemoryScan);
+    afterScan(_analysisResult: AnalysisResult): void;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare function getBundleContent(): string;