SpeedTest JS

A high-performance Speed Test library for JavaScript (ESM). Measures latency, jitter, download, and upload speeds using the Speedtest.net infrastructure.

Features

• Multi-threaded Testing: Saturates high-speed connections for accurate download measurements.
• Global Discovery: Search for servers locally or remotely via the Speedtest API.
• Network Stability: Measures both Latency (Ping) and Jitter.
• Fully Typed: TypeScript definitions included and documented with JSDoc.
• Isomorphic: Works in modern Node.js (18+) and Browser environments.
• Automatic Optimization: Automatically selects the best server based on geographical distance and latency.

Installation

npm install @ginkohub/speedtest-js

Quick Start

import { SpeedTestService } from '@ginkohub/speedtest-js';

const service = new SpeedTestService();

// 1. Initialize and fetch closest servers
await service.fetchClientInfo();
const bestServer = await service.findBestServer();

// 2. Test Latency & Jitter
const { latency, jitter } = await service.testLatency(bestServer);
console.log(`Latency: ${latency}ms, Jitter: ${jitter.toFixed(2)}ms`);

// 3. Test Download (Multi-threaded)
const dlSpeed = await service.testDownload(bestServer, (speed) => {
  process.stdout.write(`\rDownload: ${speed.toFixed(2)} Mbps`);
});

// 4. Test Upload
const ulSpeed = await service.testUpload(bestServer, (speed) => {
  process.stdout.write(`\rUpload: ${speed.toFixed(2)} Mbps`);
});

API Reference

SpeedTestService

fetchClientInfo()

Fetches public IP and ISP details.

fetchServers()

Discovers available servers and sorts them by geographical distance.

findBestServer()

Tests latency for the 10 closest servers and selects the one with the lowest ping.

searchRemoteServers(query: string)

Searches the global Speedtest.net server database for matches (e.g., "London" or "Japan").

testLatency(server, samples = 5)

Measures minimum latency and average jitter over multiple samples.

testDownload(server, onProgress, options)

Options:

• threads: Number of parallel streams (default: 4).
• duration: Test length in ms (default: 10000).

testUpload(server, onProgress, options)

Options:

• duration: Test length in ms (default: 10000).

Examples

Check the examples/ directory for detailed usage:

• basic.js: Standard end-to-end test.
• search.js: Finding and testing specific global servers.

License

MPL-2.0