lag-monitor/dist/index.d.cts

A lightweight utility for monitoring JavaScript event loop lag in real-time

/**
 * Supported lag measurement types
 */
type LagType = "setTimeout" | "setInterval" | "requestAnimationFrame";
/**
 * Lag measurement data
 */
interface LagData {
    /** Most recent lag measurement in milliseconds */
    latest?: number;
    /** Average lag over the sample window in milliseconds */
    average?: number;
    /** Minimum lag in the current sample window */
    min?: number;
    /** Maximum lag in the current sample window */
    max?: number;
    /** Number of samples collected */
    samples?: number;
}
/**
 * Callback function called on each lag measurement
 */
type LagCallback = (currentLag: number, lagData: LagData) => void;
/**
 * Configuration options for lag monitoring
 */
interface LagMonitorOptions {
    /** Method used for scheduling measurements */
    lagType?: LagType;
    /** Interval between measurements in milliseconds */
    sampleRate?: number;
    /** Number of samples to keep for average calculation */
    sampleCount?: number;
    /** Optional callback invoked on each measurement */
    callback?: LagCallback;
    /** Whether to start monitoring immediately */
    autoStart?: boolean;
    /** Custom metrics to include in snapshots */
    metrics?: Record<string, () => number>;
    /** User-defined metrics to compute from lag samples */
    userMetrics?: Record<string, (samples: number[]) => number>;
}
declare class LagMonitor {
    private lagSamples;
    private isActive;
    private options;
    private timerId;
    private lastTimestamp;
    private userMetrics;
    constructor(options?: LagMonitorOptions);
    get latest(): number;
    get average(): number;
    get min(): number;
    get max(): number;
    private scheduleNext;
    private tick;
    private clearTimer;
    /**
     * Get a metric value by name - handles both built-in and user-defined metrics
     */
    private getMetricValue;
    /**
     * Get all available metric functions (built-in + user-defined)
     */
    getAvailableMetrics(): string[];
    /**
     * Compute a specific metric or all metrics
     */
    snapshot(metric?: string): LagData | {
        [key: string]: number;
    };
    start(): void;
    stop(): void;
    reset(): void;
    restart(): void;
    isRunning(): boolean;
}

interface Buffer<T> {
    push(item: T): void;
    latest: T | undefined;
    toArray(): T[];
    length: number;
    clear(): void;
}
declare class CircularBuffer<T> implements Buffer<T> {
    private capacity;
    private buffer;
    private index;
    private filled;
    constructor(capacity: number);
    push(item: T): void;
    get latest(): T | undefined;
    toArray(): T[];
    get length(): number;
    clear(): void;
}

/**
 * Event Loop Lag Monitor
 *
 * A lightweight utility for monitoring JavaScript event loop lag in real-time.
 * Useful for performance monitoring, debugging, and alerting on event loop blocking.
 *
 * @author Your Name
 * @version 1.0.0
 * @license MIT
 */

export { type Buffer, CircularBuffer, type LagCallback, type LagData, LagMonitor, type LagMonitorOptions, type LagType, LagMonitor as default };