@usefy/use-memory-monitor 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,537 @@
+/**
+ * Memory information at a point in time
+ */
+interface MemoryInfo {
+    /** Used JS heap size in bytes */
+    heapUsed: number;
+    /** Total JS heap size in bytes */
+    heapTotal: number;
+    /** JS heap size limit in bytes */
+    heapLimit: number;
+    /** Timestamp when this measurement was taken */
+    timestamp: number;
+}
+/**
+ * A named memory snapshot for comparison
+ */
+interface MemorySnapshot {
+    /** Unique identifier for this snapshot */
+    id: string;
+    /** Memory information at snapshot time */
+    memory: MemoryInfo;
+    /** Number of DOM nodes (if tracking enabled) */
+    domNodes?: number;
+    /** Estimated event listener count (if tracking enabled) */
+    eventListeners?: number;
+    /** Timestamp when snapshot was taken */
+    timestamp: number;
+}
+/**
+ * Result of comparing two memory snapshots
+ */
+interface SnapshotDiff {
+    /** Difference in heap usage (bytes) */
+    heapDelta: number;
+    /** Percentage change in heap usage */
+    heapPercentChange: number;
+    /** Difference in DOM node count */
+    domNodesDelta?: number;
+    /** Difference in event listener count */
+    eventListenersDelta?: number;
+    /** Time elapsed between snapshots (ms) */
+    timeDelta: number;
+}
+/**
+ * Result of memory leak analysis
+ */
+interface LeakAnalysis {
+    /** Whether a memory leak is detected */
+    isLeaking: boolean;
+    /** Probability of memory leak (0-100) */
+    probability: number;
+    /** Memory usage trend */
+    trend: Trend;
+    /** Average memory growth per interval (bytes) */
+    averageGrowth: number;
+    /** R-squared value indicating regression fit quality (0-1) */
+    rSquared: number;
+    /** Samples used for analysis */
+    samples: MemoryInfo[];
+    /** Human-readable recommendation */
+    recommendation?: string;
+}
+/**
+ * Information about why memory monitoring is not supported
+ */
+interface UnsupportedInfo {
+    /** Reason for lack of support */
+    reason: UnsupportedReason;
+    /** Browser name if detected */
+    browser?: string;
+    /** Available fallback strategies */
+    availableFallbacks: FallbackStrategy[];
+}
+/**
+ * Reason why memory API is not supported
+ */
+type UnsupportedReason = "no-api" | "server-side" | "insecure-context" | "browser-restriction";
+/**
+ * Level of memory API support
+ */
+type SupportLevel = "full" | "partial" | "none";
+/**
+ * Available memory metrics based on browser support
+ */
+type AvailableMetric = "heapUsed" | "heapTotal" | "heapLimit" | "domNodes" | "eventListeners";
+/**
+ * Memory usage severity level
+ */
+type Severity = "normal" | "warning" | "critical";
+/**
+ * Memory usage trend direction
+ */
+type Trend = "stable" | "increasing" | "decreasing";
+/**
+ * Fallback strategy for unsupported browsers
+ */
+type FallbackStrategy = "none" | "estimation" | "dom-only";
+/**
+ * Leak detection sensitivity level
+ */
+type LeakSensitivity = "low" | "medium" | "high";
+/**
+ * Warning data passed to onWarning callback
+ */
+interface MemoryWarning {
+    /** Current memory info */
+    memory: MemoryInfo;
+    /** Current usage percentage */
+    usagePercentage: number;
+    /** Warning threshold that was exceeded */
+    threshold: number;
+    /** Timestamp of warning */
+    timestamp: number;
+}
+/**
+ * Critical alert data passed to onCritical callback
+ */
+interface MemoryCritical {
+    /** Current memory info */
+    memory: MemoryInfo;
+    /** Current usage percentage */
+    usagePercentage: number;
+    /** Critical threshold that was exceeded */
+    threshold: number;
+    /** Timestamp of critical alert */
+    timestamp: number;
+}
+/**
+ * Browser support detection result
+ */
+interface BrowserSupport {
+    /** Level of support */
+    level: SupportLevel;
+    /** Available metrics in this browser */
+    availableMetrics: AvailableMetric[];
+    /** Any limitations or caveats */
+    limitations: string[];
+    /** Whether secure context requirements are met */
+    isSecureContext: boolean;
+    /** Whether cross-origin isolated */
+    isCrossOriginIsolated: boolean;
+    /** Whether precise memory API is available */
+    hasPreciseMemoryAPI: boolean;
+}
+/**
+ * Formatted memory values for display
+ */
+interface FormattedMemory {
+    /** Formatted heap used (e.g., "45.2 MB") */
+    heapUsed: string;
+    /** Formatted heap total (e.g., "100 MB") */
+    heapTotal: string;
+    /** Formatted heap limit (e.g., "2 GB") */
+    heapLimit: string;
+    /** Formatted DOM node count */
+    domNodes?: string;
+    /** Formatted event listener count */
+    eventListeners?: string;
+}
+/**
+ * Leak detection configuration
+ */
+interface LeakDetectionOptions {
+    /** Enable leak detection */
+    enabled?: boolean;
+    /** Detection sensitivity */
+    sensitivity?: LeakSensitivity;
+    /** Number of samples to analyze */
+    windowSize?: number;
+    /** Custom growth rate threshold (bytes/sample) */
+    threshold?: number;
+}
+/**
+ * Threshold configuration for alerts
+ */
+interface ThresholdOptions {
+    /** Warning threshold percentage (0-100) */
+    warning?: number;
+    /** Critical threshold percentage (0-100) */
+    critical?: number;
+}
+/**
+ * Configuration options for useMemoryMonitor hook
+ */
+interface UseMemoryMonitorOptions {
+    /** Monitoring interval in milliseconds (default: 5000) */
+    interval?: number;
+    /** Auto-start monitoring on mount (default: true) */
+    autoStart?: boolean;
+    /** Enable monitoring (default: true) */
+    enabled?: boolean;
+    /** Enable history recording (default: false) */
+    enableHistory?: boolean;
+    /** Maximum history size (default: 50) */
+    historySize?: number;
+    /** Threshold configuration for warnings/alerts */
+    thresholds?: ThresholdOptions;
+    /** Leak detection configuration */
+    leakDetection?: LeakDetectionOptions;
+    /** Enable development mode features (default: false) */
+    devMode?: boolean;
+    /** Track DOM node count (default: false) */
+    trackDOMNodes?: boolean;
+    /** Track event listener count (default: false) */
+    trackEventListeners?: boolean;
+    /** Log updates to console (default: false) */
+    logToConsole?: boolean;
+    /** Called on each memory update */
+    onUpdate?: (memory: MemoryInfo) => void;
+    /** Called when warning threshold is exceeded */
+    onWarning?: (data: MemoryWarning) => void;
+    /** Called when critical threshold is exceeded */
+    onCritical?: (data: MemoryCritical) => void;
+    /** Called when memory leak is detected */
+    onLeakDetected?: (analysis: LeakAnalysis) => void;
+    /** Called when monitoring is not supported */
+    onUnsupported?: (info: UnsupportedInfo) => void;
+    /** Disable in production builds (default: false) */
+    disableInProduction?: boolean;
+    /** Fallback strategy for unsupported browsers (default: 'dom-only') */
+    fallbackStrategy?: FallbackStrategy;
+}
+/**
+ * Return type for useMemoryMonitor hook
+ */
+interface UseMemoryMonitorReturn {
+    /** Current memory information (null if unsupported) */
+    memory: MemoryInfo | null;
+    /** Used JS heap in bytes (null if unsupported) */
+    heapUsed: number | null;
+    /** Total JS heap in bytes (null if unsupported) */
+    heapTotal: number | null;
+    /** JS heap limit in bytes (null if unsupported) */
+    heapLimit: number | null;
+    /** Memory usage percentage (null if unsupported) */
+    usagePercentage: number | null;
+    /** Current DOM node count (null if not tracking) */
+    domNodes: number | null;
+    /** Estimated event listener count (null if not tracking) */
+    eventListeners: number | null;
+    /** Whether memory API is supported */
+    isSupported: boolean;
+    /** Whether monitoring is currently active */
+    isMonitoring: boolean;
+    /** Whether a memory leak is detected */
+    isLeakDetected: boolean;
+    /** Current severity level */
+    severity: Severity;
+    /** Level of API support */
+    supportLevel: SupportLevel;
+    /** List of available metrics */
+    availableMetrics: AvailableMetric[];
+    /** Memory history array (empty if history disabled) */
+    history: MemoryInfo[];
+    /** Memory usage trend */
+    trend: Trend;
+    /** Probability of memory leak (0-100) */
+    leakProbability: number;
+    /** Start monitoring */
+    start: () => void;
+    /** Stop monitoring */
+    stop: () => void;
+    /** Take a named snapshot */
+    takeSnapshot: (id: string) => MemorySnapshot | null;
+    /** Compare two snapshots */
+    compareSnapshots: (id1: string, id2: string) => SnapshotDiff | null;
+    /** Clear history */
+    clearHistory: () => void;
+    /** Request garbage collection hint */
+    requestGC: () => void;
+    /** Formatted memory values for display */
+    formatted: FormattedMemory;
+}
+
+/**
+ * A React hook for monitoring browser memory usage in real-time.
+ * Detects memory leaks, provides threshold alerts, and supports snapshot comparison.
+ *
+ * Features:
+ * - Real-time memory tracking (JS Heap, DOM Nodes)
+ * - Memory leak detection with configurable sensitivity
+ * - Threshold-based warnings (warning/critical levels)
+ * - Memory snapshot comparison
+ * - SSR compatible
+ * - Graceful degradation for unsupported browsers
+ *
+ * @param options - Configuration options
+ * @returns Memory monitoring state and control functions
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function MemoryDisplay() {
+ *   const { heapUsed, formatted, isSupported } = useMemoryMonitor();
+ *
+ *   if (!isSupported) {
+ *     return <p>Memory monitoring not available</p>;
+ *   }
+ *
+ *   return <p>Memory: {formatted.heapUsed}</p>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With leak detection
+ * const monitor = useMemoryMonitor({
+ *   enableHistory: true,
+ *   leakDetection: { enabled: true, sensitivity: 'medium' },
+ *   onLeakDetected: (analysis) => {
+ *     console.warn('Leak detected:', analysis);
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With threshold alerts
+ * const monitor = useMemoryMonitor({
+ *   thresholds: { warning: 70, critical: 90 },
+ *   onWarning: (data) => console.warn('Memory warning:', data),
+ *   onCritical: (data) => console.error('Memory critical:', data),
+ * });
+ * ```
+ */
+declare function useMemoryMonitor(options?: UseMemoryMonitorOptions): UseMemoryMonitorReturn;
+
+/**
+ * Format bytes to human-readable string (e.g., "45.2 MB")
+ *
+ * @param bytes - Number of bytes to format
+ * @param decimals - Number of decimal places (default: 2)
+ * @returns Formatted string with unit
+ */
+declare function formatBytes(bytes: number | null | undefined, decimals?: number): string;
+/**
+ * Format a percentage value
+ *
+ * @param percentage - Percentage value (0-100)
+ * @param decimals - Number of decimal places (default: 1)
+ * @returns Formatted percentage string
+ */
+declare function formatPercentage(percentage: number | null | undefined, decimals?: number): string;
+/**
+ * Format a number with thousand separators
+ *
+ * @param value - Number to format
+ * @returns Formatted string with thousand separators
+ */
+declare function formatNumber(value: number | null | undefined): string;
+/**
+ * Calculate usage percentage from memory info
+ *
+ * @param heapUsed - Used heap size in bytes
+ * @param heapLimit - Heap limit in bytes
+ * @returns Usage percentage (0-100) or null if invalid
+ */
+declare function calculateUsagePercentage(heapUsed: number | null | undefined, heapLimit: number | null | undefined): number | null;
+/**
+ * Format time duration in milliseconds to human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns Formatted duration string
+ */
+declare function formatDuration(ms: number): string;
+
+/**
+ * Check if running in a server-side environment
+ */
+declare function isServer(): boolean;
+/**
+ * Check if running in a client-side environment
+ */
+declare function isClient(): boolean;
+/**
+ * Check if the legacy performance.memory API is available (Chrome/Edge)
+ */
+declare function hasLegacyMemoryAPI(): boolean;
+/**
+ * Check if the modern measureUserAgentSpecificMemory API is available
+ */
+declare function hasPreciseMemoryAPI(): boolean;
+/**
+ * Attempt to detect the browser name
+ */
+declare function detectBrowser(): string | undefined;
+/**
+ * Comprehensive browser support detection
+ */
+declare function detectSupport(): BrowserSupport;
+/**
+ * Check if any memory monitoring is possible
+ */
+declare function canMonitorMemory(): boolean;
+
+/**
+ * A fixed-size circular buffer (ring buffer) for efficient history storage.
+ * Provides O(1) push operations and automatically overwrites oldest entries
+ * when capacity is reached.
+ *
+ * @template T - Type of items stored in the buffer
+ */
+declare class CircularBuffer<T> {
+    private buffer;
+    private head;
+    private tail;
+    private _size;
+    private readonly _capacity;
+    /**
+     * Create a new circular buffer with the specified capacity
+     *
+     * @param capacity - Maximum number of items the buffer can hold
+     * @throws Error if capacity is less than 1
+     */
+    constructor(capacity: number);
+    /**
+     * Add an item to the buffer.
+     * If the buffer is full, the oldest item will be overwritten.
+     *
+     * @param item - Item to add
+     */
+    push(item: T): void;
+    /**
+     * Get all items in the buffer as an array, from oldest to newest.
+     *
+     * @returns Array of items in insertion order (oldest first)
+     */
+    toArray(): T[];
+    /**
+     * Get the most recent N items from the buffer.
+     *
+     * @param count - Number of items to retrieve
+     * @returns Array of most recent items (oldest first within the slice)
+     */
+    getRecent(count: number): T[];
+    /**
+     * Get the most recently added item.
+     *
+     * @returns The most recent item, or undefined if buffer is empty
+     */
+    get last(): T | undefined;
+    /**
+     * Get the oldest item in the buffer.
+     *
+     * @returns The oldest item, or undefined if buffer is empty
+     */
+    get first(): T | undefined;
+    /**
+     * Get an item at a specific index (0 = oldest).
+     *
+     * @param index - Index of the item to retrieve
+     * @returns The item at the index, or undefined if out of bounds
+     */
+    at(index: number): T | undefined;
+    /**
+     * Current number of items in the buffer.
+     */
+    get size(): number;
+    /**
+     * Maximum capacity of the buffer.
+     */
+    get capacity(): number;
+    /**
+     * Check if the buffer is empty.
+     */
+    get isEmpty(): boolean;
+    /**
+     * Check if the buffer is full.
+     */
+    get isFull(): boolean;
+    /**
+     * Clear all items from the buffer.
+     */
+    clear(): void;
+    /**
+     * Iterate over all items in the buffer (oldest to newest).
+     */
+    [Symbol.iterator](): Iterator<T>;
+    /**
+     * Apply a function to each item in the buffer.
+     *
+     * @param callback - Function to call for each item
+     */
+    forEach(callback: (item: T, index: number) => void): void;
+    /**
+     * Map items to a new array.
+     *
+     * @param callback - Function to transform each item
+     * @returns Array of transformed items
+     */
+    map<U>(callback: (item: T, index: number) => U): U[];
+    /**
+     * Filter items based on a predicate.
+     *
+     * @param predicate - Function to test each item
+     * @returns Array of items that pass the test
+     */
+    filter(predicate: (item: T, index: number) => boolean): T[];
+}
+
+/**
+ * Result of linear regression analysis
+ */
+interface RegressionResult {
+    /** Slope of the regression line (bytes per sample) */
+    slope: number;
+    /** Y-intercept of the regression line */
+    intercept: number;
+    /** R-squared value (coefficient of determination, 0-1) */
+    rSquared: number;
+}
+/**
+ * Perform simple linear regression on a set of points.
+ * Uses the least squares method.
+ *
+ * @param points - Array of [x, y] coordinate pairs
+ * @returns Regression result with slope, intercept, and R-squared
+ */
+declare function linearRegression(points: [number, number][]): RegressionResult;
+/**
+ * Calculate the memory trend from samples.
+ *
+ * @param samples - Array of memory info samples
+ * @returns Trend direction
+ */
+declare function calculateTrend(samples: MemoryInfo[]): Trend;
+/**
+ * Analyze memory samples for potential leaks.
+ *
+ * @param samples - Array of memory info samples (minimum 5 recommended)
+ * @param sensitivity - Detection sensitivity level
+ * @param customThreshold - Optional custom growth threshold (bytes/sample)
+ * @returns Leak analysis result
+ */
+declare function analyzeLeakProbability(samples: MemoryInfo[], sensitivity?: LeakSensitivity, customThreshold?: number): LeakAnalysis;
+
+export { type AvailableMetric, type BrowserSupport, CircularBuffer, type FallbackStrategy, type FormattedMemory, type LeakAnalysis, type LeakDetectionOptions, type LeakSensitivity, type MemoryCritical, type MemoryInfo, type MemorySnapshot, type MemoryWarning, type RegressionResult, type Severity, type SnapshotDiff, type SupportLevel, type ThresholdOptions, type Trend, type UnsupportedInfo, type UnsupportedReason, type UseMemoryMonitorOptions, type UseMemoryMonitorReturn, analyzeLeakProbability, calculateTrend, calculateUsagePercentage, canMonitorMemory, detectBrowser, detectSupport, formatBytes, formatDuration, formatNumber, formatPercentage, hasLegacyMemoryAPI, hasPreciseMemoryAPI, isClient, isServer, linearRegression, useMemoryMonitor };