Simple JavaScript Speedometer

Common errors

• TypeError: speedometer is not a function

  cause Attempting to use `import speedometer from 'speedometer'` in an ESM context when the package only exports CommonJS.
  fix Change your import statement to `const speedometer = require('speedometer')` and ensure your environment supports CommonJS modules.

• ReferenceError: require is not defined

  cause Trying to use `require('speedometer')` in an environment where CommonJS `require` is not available, such as a pure ES module Node.js project (`"type": "module"` in `package.json`) or a browser context without a CJS-compatible bundler.
  fix This package is CommonJS-only and primarily for Node.js. If in a Node.js ESM project, you might need to wrap it in a CJS loader or reconsider using a different package. For browser use, a bundler might make it work, but direct use is not supported.

Warnings

• gotcha The `speedometer` package is designed for Node.js environments and uses Node.js-specific features like `require`. It does not provide an ES module (ESM) export and is not intended for direct browser usage.
  Fix: Ensure you are using a CommonJS environment (Node.js without `"type": "module"` in `package.json` or a bundler configured for CJS) and use `require('speedometer')`.
• gotcha The default buffer window for speed calculation is 5 seconds. If you need more immediate feedback or a longer-term average, remember to adjust this value during initialization.
  Fix: Initialize with `speedometer(bufferTimeInSeconds)`, e.g., `const speed = speedometer(1);` for a 1-second average or `speedometer(60)` for a 1-minute average.
• gotcha The `speedometer` function expects numerical values representing the number of bytes transferred. Passing non-numeric or invalid input can lead to incorrect speed calculations or runtime errors.
  Fix: Always ensure the argument passed to the `speed()` function is a positive number representing the data length, e.g., `speed(data.length)`.

Install

• npm install speedometer npm
• yarn add speedometer yarn
• pnpm add speedometer pnpm

Imports

• speedometer
  wrong:

  import speedometer from 'speedometer'

  correct:

  const speedometer = require('speedometer')

  This package is CommonJS-only. Attempting to use ES module `import` syntax will result in a runtime error or incorrect module resolution.

Quickstart

This example demonstrates how to initialize the speedometer, feed it data chunk lengths, and continuously log the calculated bytes per second for a data stream.

const speedometer = require('speedometer');
const fs = require('fs');

// Create a speedometer instance with a 10-second buffer
const speed = speedometer(10);
const stream = fs.createReadStream('/dev/urandom', { highWaterMark: 1024 * 1024 }); // Read in 1MB chunks

let totalBytes = 0;
let lastLogTime = Date.now();

stream.on('data', function(data) {
  // Pass the amount of bytes transferred to the speedometer
  const bytesPerSecond = speed(data.length);
  totalBytes += data.length;

  // Log speed every second
  if (Date.now() - lastLogTime >= 1000) {
    console.log(`Current speed: ${bytesPerSecond.toFixed(2)} bytes/second`);
    lastLogTime = Date.now();
  }
});

stream.on('end', () => {
  console.log(`
Finished reading. Total bytes: ${totalBytes}`);
  const finalSpeed = speed(); // Get current speed one last time
  console.log(`Final calculated speed (over buffer): ${finalSpeed.toFixed(2)} bytes/second`);
});

stream.on('error', (err) => {
  console.error('Stream error:', err);
});