Gud Bench

A powerful and elegant benchmarking tool for JavaScript and TypeScript.

✨ Features

• 🚀 Zero-config benchmarking - Just point it at your functions
• 📊 Statistical accuracy with multiple cycles and margin of error calculation
• 🔧 TypeScript support - Transpiles .ts files on-the-fly
• ⚡ Multiple export patterns - Detects default, named, and benchmark exports
• 🗑️ Memory management - Advanced garbage collection strategies
• 📈 Export results - JSON output for further analysis
• 📦 Library + CLI - Use programmatically or via command line

Installing

1npm install --global @gud/bench
2
3# or, for local projects
4npm install --save-dev @gud/bench

Quick Start

Running Arbitrary Files with the CLI

The easiest way to benchmark any JavaScript files is using the CLI:

1# Benchmark a single file
2bench --files my-functions.js
3
4# Benchmark multiple files  
5bench --files file1.js file2.js file3.js
6
7# Customize the benchmark parameters
8bench --files my-functions.js --runs 50000 --cycles 3
9
10# Export results to JSON
11bench --files my-functions.js --export true

The CLI will automatically detect and benchmark:

• Default exports (export default function)
• Named function exports (export function myFunction())
• Specific benchmark functions (export { benchmark } or export { test })

Example function file:

1// sort-algorithms.js
2const data = Array.from({ length: 100 }, () => Math.floor(Math.random() * 1000));
3
4export function quickSort(arr = data) {
5  if (arr.length <= 1) return arr;
6  const pivot = arr[arr.length - 1];
7  const left = [], right = [];
8  for (let i = 0; i < arr.length - 1; i++) {
9    if (arr[i] < pivot) left.push(arr[i]);
10    else right.push(arr[i]);
11  }
12  return [...quickSort(left), pivot, ...quickSort(right)];
13}
14
15export function bubbleSort(arr = data) {
16  const result = [...arr];
17  for (let i = 0; i < result.length; i++) {
18    for (let j = 0; j < result.length - 1; j++) {
19      if (result[j] > result[j + 1]) {
20        [result[j], result[j + 1]] = [result[j + 1], result[j]];
21      }
22    }
23  }
24  return result;
25}

Output:

1… 📁 Loading 1 files for benchmarking...
2… Benchmark: Preheating 2 tests 1000 times each...
3▾ Benchmark
4  … Running 1 cycle of 2 tests 100000 times each...
5  ┌──────────────────────────────────┬───────────┬─────────────────┬───────────────┬───────────┬─────────┐
6  │ (index)                          │ Runs      │ Total Time (ms) │ AVG Time (ms) │ Ops/Sec   │ ± (%)   │
7  ├──────────────────────────────────┼───────────┼─────────────────┼───────────────┼───────────┼─────────┤
8  │ 1 - sort-algorithms#quickSort 🏆 │ '100,000' │ '441.9717'      │ '0.004420'    │ '226,259' │ '0.68%' │
9  │ 2 - sort-algorithms#bubbleSort   │ '100,000' │ '1,126.0465'    │ '0.011260'    │ '88,806'  │ '0.06%' │
10  └──────────────────────────────────┴───────────┴─────────────────┴───────────────┴───────────┴─────────┘
11  ℹ Total time: 1,568.018178 ms

Programmatic API

Create sophisticated benchmarks with the programmatic API:

1import { benchmark } from '@gud/bench';
2
3// Create a new benchmark suite
4const bench = benchmark('String Concatenation Benchmark');
5
6// Add test functions
7bench
8  .test('Template literals', () => {
9    const name = 'World';
10    return `Hello ${name}!`;
11  })
12  .test('String concatenation', () => {
13    const name = 'World';
14    return 'Hello ' + name + '!';
15  })
16  .test('Array join', () => {
17    const name = 'World';
18    return ['Hello', name, '!'].join(' ');
19  });
20
21// Run the benchmark
22await bench.run(100000, {
23  cycles: 5,
24  verbosity: 2,
25  gcStrategy: 'per-cycle',
26});
27
28// Export results
29bench.exportToJson('./results/string-concat.json');

Advanced Features

Memory Management:

1// Fine-tune garbage collection for accurate results
2await bench.run(100000, {
3  gcStrategy: 'periodic',  // Force GC periodically
4  gcInterval: 1000,        // Every 1000 iterations
5  cycles: 3                // Multiple cycles for accuracy
6});

Statistical Analysis:

1// Get detailed statistics
2await bench.run(50000, {
3  cycles: 10,              // More cycles = better accuracy
4  verbosity: 2             // Show detailed timing info
5});

TypeScript Support:

1// Works seamlessly with TypeScript files
2bench --files "src/**/*.ts" --runs 10000

API Reference

benchmark(name?: string)

Creates a new benchmark suite.

Parameters:

• name (optional) - Name for the benchmark suite

Returns: Benchmark instance

Benchmark Class

Methods

• test(name: string, fn: Function) - Add a test function
• run(iterations: number, options?: RunOptions) - Execute benchmark
• preheat(iterations: number, options?) - Warm up before benchmarking
• exportToJson(filePath: string) - Export results to JSON
• printResults() - Display formatted results table

RunOptions

1interface RunOptions {
2  cycles?: number;           // Test cycles (default: 1)
3  coolDown?: number;         // MS between runs
4  verbosity?: 0 | 1 | 2;     // Output level (default: 1) 
5  gcStrategy?: 'never' | 'per-cycle' | 'per-test' | 'periodic';
6  gcInterval?: number;       // For periodic GC (default: 1000)
7}

Garbage Collection Strategies

• 'never' - No forced GC (fastest, but memory pressure may affect results)
• 'per-cycle' - GC once per cycle (good balance)
• 'per-test' - GC after each test completes all iterations
• 'periodic' - GC every N iterations (default, configurable via gcInterval)

Note: The CLI automatically restarts with the --expose-gc flag when needed for garbage collection. To disable this behavior, set the environment variable BENCH_NO_EXPOSE_GC=true.