traffic-lens/dist/index.d.ts

A network traffic monitoring tool with proxy awareness for Node.js

/**
 * Configuration options for TrafficLens
 * @interface Config
 */
export interface Config {
    /** The port number used by your proxy server */
    proxyPort: number;
    /** Update interval in milliseconds (minimum 3000ms, default 5000ms) */
    updateInterval?: number;
}
/**
 * Base metrics for network traffic volume
 * @interface VolumeMetrics
 */
interface VolumeMetrics {
    /** Total bytes uploaded */
    upload: number;
    /** Total bytes downloaded */
    download: number;
}
/**
 * Metrics for network speed
 * @interface SpeedMetrics
 */
interface SpeedMetrics {
    /** Upload speed in bytes per second */
    uploadSpeed: number;
    /** Download speed in bytes per second */
    downloadSpeed: number;
}
/**
 * Combined metrics for network traffic including both volume and speed
 * @interface NetworkMetrics
 */
export type NetworkMetrics = VolumeMetrics & SpeedMetrics;
/**
 * Metrics specific to proxy connections
 * @interface ProxyMetrics
 * @extends NetworkMetrics
 */
export interface ProxyMetrics extends NetworkMetrics {
    /** Number of active proxy connections */
    activeConnections: number;
}
/**
 * Complete traffic statistics including both proxied and direct traffic
 * @interface TrafficStats
 */
export interface TrafficStats {
    /** Statistics for proxied traffic */
    proxied: ProxyMetrics;
    /** Statistics for direct (non-proxied) traffic */
    direct: NetworkMetrics;
    /** Timestamp when the statistics were collected */
    timestamp: number;
}
/** Callback function type for traffic updates */
export type MonitorCallback = (stats: TrafficStats) => void;
/**
 * TrafficLens - A network traffic monitoring tool with proxy awareness
 * @class
 */
declare class TrafficLens {
    private lastStats;
    private totalStats;
    private intervalId;
    private callbacks;
    private config;
    /**
     * Creates a new TrafficLens instance
     * @param {Config} config - Configuration options
     * @throws {Error} If update interval is less than 3 seconds
     * @example
     * ```typescript
     * const monitor = new TrafficLens({
     *   proxyPort: 1080,
     *   updateInterval: 5000
     * });
     * ```
     */
    constructor(config: Config);
    /**
     * Get the current network stats
     * @returns NetworkStats | null
     */
    private getCurrentStats;
    /**
     * Get the current proxy connections
     * @returns ProxyConnections
     */
    private checkProxyConnections;
    /**
     * Starts monitoring network traffic
     * @returns {Promise<void>}
     * @throws {Error} If monitor is already running
     * @example
     * ```typescript
     * await monitor.start();
     * ```
     */
    start(): Promise<void>;
    /**
     * Stops monitoring network traffic
     * @example
     * ```typescript
     * monitor.stop();
     * ```
     */
    stop(): void;
    /**
     * Subscribes to traffic updates
     * @param {MonitorCallback} callback - Function to be called with traffic updates
     * @returns {Function} Unsubscribe function
     * @example
     * ```typescript
     * const unsubscribe = monitor.subscribe((stats) => {
     *   console.log('Upload speed:', stats.proxied.uploadSpeed);
     * });
     *
     * // Later, to unsubscribe:
     * unsubscribe();
     * ```
     */
    subscribe(callback: MonitorCallback): () => void;
    /**
     * Gets the current traffic statistics
     * @returns {TrafficStats} Current traffic statistics
     * @example
     * ```typescript
     * const stats = monitor.getTrafficStats();
     * console.log('Active proxy connections:', stats.proxied.activeConnections);
     * ```
     */
    getTrafficStats(): TrafficStats;
    /**
     * Gets current speeds for proxied connections
     * @returns {SpeedMetrics} Current proxy connection speeds
     * @example
     * ```typescript
     * const speeds = monitor.getProxySpeed();
     * console.log('Proxy upload speed:', TrafficLens.formatSpeed(speeds.uploadSpeed));
     * ```
     */
    getProxySpeed(): SpeedMetrics;
    /**
     * Gets current speeds for direct connections
     * @returns {SpeedMetrics} Current direct connection speeds
     * @example
     * ```typescript
     * const speeds = monitor.getDirectSpeed();
     * console.log('Direct download speed:', TrafficLens.formatSpeed(speeds.downloadSpeed));
     * ```
     */
    getDirectSpeed(): SpeedMetrics;
    /**
     * Formats traffic bytes to a human readable string
     * @param {number} bytes - Number of bytes to format
     * @returns {string} Formatted string with appropriate unit
     * @example
     * ```typescript
     * TrafficLens.formatBytes(1024);  // "1.00 KB"
     * TrafficLens.formatBytes(1048576);  // "1.00 MB"
     * ```
     */
    static formatBytes(bytes: number): string;
    /**
     * Formats speed to a human readable string (bytes per second)
     * @param {number} bytesPerSec - Speed in bytes per second
     * @returns {string} Formatted string with appropriate unit per second
     * @example
     * ```typescript
     * TrafficLens.formatSpeed(1024);  // "1.00 KB/s"
     * TrafficLens.formatSpeed(1048576);  // "1.00 MB/s"
     * ```
     */
    static formatSpeed(bytesPerSec: number): string;
}
export default TrafficLens;