Benching 💪

Lightweight benchmarking library for JavaScript.

Features

• ⚡ Isomorphic: Uses performance.now() with fallbacks, working in any JS environment.
• 🔍 High Precision: Automatically calculates and subtracts loop iteration overhead to measure only your function.
• 🧠 Smart Batching: Automatically determines optimal batch sizes for nanosecond-scale functions.
• 🤖 Auto-Async: Detects Promises automatically: no need to flag functions as async: true.
• 📊 Advanced Stats: Reports Mean, Standard Deviation, p99 (Tail Latency), and Margin of Error (95% CI).
• 🛡️ Type Safe: Written in TypeScript with strict typing.

Installation

npm install benching

Quick Start

The easiest way to use Benching is the runBenchmarks suite runner, which handles warmup, execution, and pretty-printing results.

import { runBenchmarks } from "benching";

const data = Array.from({ length: 1000 }, () => Math.random());

runBenchmarks({
  // Synchronous Task
  "Array.reduce": () => {
    data.reduce((acc, curr) => acc + curr, 0);
  },

  // Native Loop
  "For Loop": () => {
    let sum = 0;
    for (let i = 0; i < data.length; i++) sum += data[i];
  },

  // Asynchronous Task (Detected automatically)
  "Async Wait": async () => {
    await new Promise((r) => setTimeout(r, 1));
  },
});

Sample Output

Running 3 benchmarks...

• Array.reduce ...
✓ Array.reduce  3,962,235 ops/sec

• For Loop     ...
✓ For Loop      1,382,106 ops/sec

• Async Wait   ...
✓ Async Wait    66 ops/sec


--------------------------------------------------------------------------------
Task         | Ops/Sec       | Average   | Margin    | P99
--------------------------------------------------------------------------------
Array.reduce | 3,962,235     | 0.0003ms  | ±0.90%    | 0.0003ms
For Loop     | 1,382,106     | 0.0007ms  | ±0.18%    | 0.0008ms
Async Wait   | 66            | 15.2661ms | ±4.04%    | 16.5395ms
--------------------------------------------------------------------------------

Advanced Usage

If you need raw data or custom options, you can use the underlying bench function directly.

import { bench } from "benching";

async function main() {
  const result = await bench("My Algo", () => myAlgo(), {
    runs: 100, // Number of sampling runs (default: 50)
    warmupTime: 500, // JIT Warmup time in ms (default: 100)
  });

  console.log(result.meanMs);
  console.log(result.p99Ms);
}

Configuration Options

• runs (number): How many distinct samples to collect. (Default: 50)
• warmupTime (number): Milliseconds to run the function before measuring (warms up V8 JIT). (Default: 100)
• batchSize (number | undefined): Iterations per sample. Leave undefined to let Benching auto-calculate this based on execution speed. (Default: undefined)

Bench Result Properties

The object returned by the bench function contains the complete statistical analysis for the operation.

• name: The descriptive name of the benchmark function provided during execution.

• opsPerSec: The final throughput score, calculated as 1000ms / meanMs. This is the number of times the operation can execute per second.

• meanMs: The arithmetic average time, in milliseconds, that a single operation takes to complete.

• minMs: The minimum time, in milliseconds, observed for a single operation across all runs.

• maxMs: The maximum time, in milliseconds, observed for a single operation across all runs.

• p75Ms: The 75th percentile time. 75% of the recorded samples were faster than this value.

• p99Ms: The 99th percentile time, often referred to as Tail Latency. This is a crucial metric, as it indicates the performance experienced by the slowest 1% of users or executions.

• moe: The Margin of Error (absolute value in milliseconds) for a 95% Confidence Interval. This value indicates the expected range around the meanMs where the true mean performance lies.

• rme: The Relative Margin of Error (as a percentage, e.g., ±2.5%). This is the moe expressed as a percentage of meanMs and indicates the reliability or "noisiness" of the measurement.

• samples: The total number of successful data samples collected during the execution (equal to the runs option).

How it Works

1. Auto-Batching

If your function takes 0.0001ms (like 1 + 1), standard timers cannot measure it accurately. Benching runs your function in a loop (batch) until the batch takes at least ~5ms, then divides the total time by the batch count to get the per-operation time.

2. Loop Overhead Compensation

Running a for loop costs CPU time. For extremely fast functions, the loop mechanics can cost more than the function itself. Benching measures the time of an empty loop of the same batch size and subtracts it from your result, ensuring we only measure your code.

3. Async Detection

You don't need to tell Benching if a function is async. It executes the function once during setup and inspect the return value. If it's a Promise, Benching automatically await it during the benchmark.