TrafficLens

A Node.js library for monitoring network traffic with proxy connection awareness. TrafficLens provides real-time statistics about your system's network usage, distinguishing between proxied and direct traffic.

Features

• Real-time network traffic monitoring
• Proxy connection detection and statistics
• Separate tracking for direct and proxied traffic
• Human-readable traffic formatting
• Event-based updates via subscription
• TypeScript support

Installation

pnpm add traffic-lens

or

npm install traffic-lens

or

yarn add traffic-lens

Usage

Basic Example

import TrafficLens from "traffic-lens";
// Initialize with proxy port
const monitor = new TrafficLens({ proxyPort: 1080 });
// Subscribe to traffic updates
monitor.subscribe((stats) => {
  console.log("Proxy Traffic:", TrafficLens.formatSpeed(stats.proxied.uploadSpeed));
  console.log("Direct Traffic:", TrafficLens.formatSpeed(stats.direct.uploadSpeed));
});
// Start monitoring
await monitor.start();
// ... when done
monitor.stop();

Configuration

const monitor = new TrafficLens({
  proxyPort: 1080, // Required: Your proxy server port
  updateInterval: 5000, // Optional: Update interval in ms (default: 5000, cannot be less than 3000)
});

Traffic Statistics

The monitor provides detailed traffic statistics through various methods:

// Get all traffic stats
const stats = monitor.getTrafficStats();
console.log(stats);

/**
{
proxied: {
upload: number,
download: number,
uploadSpeed: number,
downloadSpeed: number,
activeConnections: number
},
direct: {
upload: number,
download: number,
uploadSpeed: number,
downloadSpeed: number
},
timestamp: number
}
**/

// Get proxy speeds only
const proxySpeed = monitor.getProxySpeed();
console.log(proxySpeed); // { uploadSpeed: number, downloadSpeed: number }
// Get direct traffic speeds only
const directSpeed = monitor.getDirectSpeed();
console.log(directSpeed); // { uploadSpeed: number, downloadSpeed: number }

Formatting Utilities

// Format bytes to human readable string
TrafficLens.formatBytes(1024); // "1.00 KB"
TrafficLens.formatBytes(1048576); // "1.00 MB"
// Format speed to human readable string
TrafficLens.formatSpeed(1024); // "1.00 KB/s"
TrafficLens.formatSpeed(1048576); // "1.00 MB/s"

Event Subscription

// Subscribe to updates
const unsubscribe = monitor.subscribe((stats) => {
  console.log("New traffic stats:", stats);
});
// Unsubscribe when done
unsubscribe();

API Reference

Class: TrafficLens

Constructor

• new TrafficLens(config: Config): Creates a new traffic monitor instance

Methods

• start(): Promise<void>: Starts monitoring network traffic
• stop(): void: Stops monitoring network traffic
• subscribe(callback: MonitorCallback): () => void: Subscribes to traffic updates
• getTrafficStats(): TrafficStats: Gets current traffic statistics
• getProxySpeed(): SpeedMetrics: Gets current proxy connection speeds
• getDirectSpeed(): SpeedMetrics: Gets current direct connection speeds
• static formatBytes(bytes: number): string: Formats bytes to human readable string
• static formatSpeed(bytesPerSec: number): string: Formats speed to human readable string

Types

interface Config {
  proxyPort: number;
  updateInterval?: number; // milliseconds
}
interface TrafficStats {
  proxied: ProxyMetrics;
  direct: NetworkMetrics;
  timestamp: number;
}
interface NetworkMetrics {
  upload: number;
  download: number;
  uploadSpeed: number;
  downloadSpeed: number;
}
interface ProxyMetrics extends NetworkMetrics {
  activeConnections: number;
}

Requirements

• Node.js 18.x or later
• System with network interfaces

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details