Core Benchmarking

/**
 * The Benchmark constructor creates a new benchmark instance
 * @param {string} [name] - The name of the benchmark
 * @param {function|string} [fn] - The test function or code string to benchmark
 * @param {object} [options] - Configuration options
 * @returns {Benchmark} New benchmark instance
 */
function Benchmark(name, fn, options);

// Can be called without 'new'
const bench = Benchmark('test', function() { /* code */ });
const bench2 = new Benchmark('test', function() { /* code */ });

const Benchmark = require('benchmark');

// Basic benchmark
const bench = new Benchmark(function() {
  'Hello World!'.indexOf('o') > -1;
});

// Named benchmark
const bench2 = new Benchmark('String#indexOf', function() {
  'Hello World!'.indexOf('o') > -1;
});

// With options
const bench3 = new Benchmark('RegExp#test', function() {
  /o/.test('Hello World!');
}, {
  defer: true,
  maxTime: 2
});

// String code (not recommended for security)
const bench4 = new Benchmark('eval test', '"Hello World!".indexOf("o") > -1');

// Execution state
benchmark.aborted;      // boolean: Whether benchmark was aborted
benchmark.running;      // boolean: Whether benchmark is currently running
benchmark.count;        // number: Number of times executed
benchmark.cycles;       // number: Number of benchmark cycles completed
benchmark.hz;           // number: Operations per second

// Configuration
benchmark.id;           // number: Unique benchmark identifier
benchmark.name;         // string: Benchmark display name
benchmark.fn;           // function: Test function
benchmark.compiled;     // function: Compiled test function
benchmark.setup;        // function|string: Setup code
benchmark.teardown;     // function|string: Teardown code

// Results
benchmark.error;        // Error|null: Error object if benchmark failed
benchmark.stats;        // object: Statistical data
benchmark.times;        // object: Timing information

const bench = new Benchmark('test', function() { Math.random(); });

bench.run();

console.log('Name:', bench.name);           // "test"
console.log('Operations/sec:', bench.hz);   // e.g., 1234567
console.log('Cycles:', bench.cycles);       // e.g., 20
console.log('Error:', bench.error);         // null if successful
console.log('Stats:', bench.stats);         // Statistical analysis

/**
 * Abort the benchmark
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.abort();

/**
 * Create a deep clone of the benchmark
 * @param {object} [options] - Options to override in the clone
 * @returns {Benchmark} New benchmark instance
 */
benchmark.clone(options);

/**
 * Compare performance with another benchmark
 * @param {Benchmark} other - Benchmark to compare against
 * @returns {number} -1 (slower), 0 (similar), 1 (faster)
 */
benchmark.compare(other);

/**
 * Reset benchmark properties to initial state
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.reset();

/**
 * Execute the benchmark
 * @param {object} [options] - Runtime options
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.run(options);

/**
 * String representation of benchmark results
 * @returns {string} Formatted benchmark results
 */
benchmark.toString();

const bench = new Benchmark('test', function() { Math.random(); });

// Clone with different options
const clone = bench.clone({ name: 'test-clone', maxTime: 1 });

// Run and get results
bench.run();
console.log(bench.toString()); // "test x 1,234,567 ±0.85% (64 runs sampled)"

// Compare benchmarks
const bench2 = new Benchmark('test2', function() { Math.round(Math.random()); });
bench2.run();
console.log(bench.compare(bench2)); // -1, 0, or 1

// Reset for another run
bench.reset().run();

/**
 * Add event listener
 * @param {string} type - Event type ('start', 'cycle', 'complete', 'abort', 'error', 'reset')
 * @param {function} listener - Event handler function
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.on(type, listener);

/**
 * Remove event listener
 * @param {string} [type] - Event type (removes all if omitted)
 * @param {function} [listener] - Specific listener to remove
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.off(type, listener);

/**
 * Emit event to listeners
 * @param {string} type - Event type
 * @param {...*} args - Event arguments
 * @returns {Benchmark} The benchmark instance (chainable)
 */
benchmark.emit(type, ...args);

/**
 * Get event listeners for type
 * @param {string} type - Event type
 * @returns {function[]} Array of listener functions
 */
benchmark.listeners(type);

const bench = new Benchmark('test', function() { Math.random(); });

// Add event listeners
bench.on('start', function() {
  console.log('Benchmark started');
})
.on('cycle', function(event) {
  console.log('Cycle completed:', event.target.toString());
})
.on('complete', function() {
  console.log('Benchmark completed');
})
.on('error', function(event) {
  console.error('Benchmark error:', event.target.error);
});

// Run with events
bench.run();

// Remove listeners
bench.off('cycle'); // Remove all cycle listeners
bench.off('complete', specificListener); // Remove specific listener

// Library information
Benchmark.version;      // string: "2.1.4"

// Default options for all benchmarks
Benchmark.options;      // object: Default benchmark options

// Platform detection
Benchmark.platform;     // object: Platform information (browser/OS details)

// Feature support
Benchmark.support;      // object: Feature detection results
// Properties: browser (boolean), timeout (boolean), decompilation (boolean)

console.log('Benchmark.js version:', Benchmark.version);

// Modify default options
Benchmark.options.maxTime = 3; // All new benchmarks will use 3 second max

// Check platform
console.log('Platform:', Benchmark.platform.description);
console.log('Browser:', Benchmark.platform.name);
console.log('OS:', Benchmark.platform.os);

// Check support
console.log('High-res timer support:', Benchmark.support.timeout);
console.log('Browser environment:', Benchmark.support.browser);
console.log('Function decompilation:', Benchmark.support.decompilation);

/**
 * Create new Benchmark function with custom context
 * @param {object} [context] - Context object with custom globals
 * @returns {function} New Benchmark constructor
 */
Benchmark.runInContext(context);

/**
 * Filter benchmarks by callback or property
 * @param {Benchmark[]} array - Array of benchmarks to filter
 * @param {function|string} callback - Filter function or property name
 * @returns {Benchmark[]} Filtered benchmarks
 */
Benchmark.filter(array, callback);

/**
 * Format number with locale-appropriate separators
 * @param {number} number - Number to format
 * @returns {string} Formatted number string
 */
Benchmark.formatNumber(number);

/**
 * Invoke method on all benchmarks in array
 * @param {Benchmark[]} array - Array of benchmarks
 * @param {string} methodName - Method name to invoke
 * @param {...*} args - Arguments to pass to method
 * @returns {*[]} Array of method results
 */
Benchmark.invoke(array, methodName, ...args);

/**
 * Join benchmark results into string
 * @param {Benchmark[]} array - Array of benchmarks
 * @param {string} [separator=','] - Separator character
 * @returns {string} Joined results
 */
Benchmark.join(array, separator);

const benchmarks = [bench1, bench2, bench3];

// Filter benchmarks
const fastest = Benchmark.filter(benchmarks, 'fastest');
const successful = Benchmark.filter(benchmarks, 'successful');
const custom = Benchmark.filter(benchmarks, function(bench) {
  return bench.hz > 1000;
});

// Format numbers
console.log(Benchmark.formatNumber(1234567)); // "1,234,567"

// Invoke methods on all benchmarks
Benchmark.invoke(benchmarks, 'reset');
Benchmark.invoke(benchmarks, 'run', { async: true });

// Join results
console.log(Benchmark.join(benchmarks, ' vs '));

interface BenchmarkOptions {
  async?: boolean;        // Execute benchmark asynchronously (default: false)
  defer?: boolean;        // Use deferred timing for async tests (default: false)
  delay?: number;         // Delay between test cycles in seconds (default: 0.005)
  id?: string;           // Benchmark identifier (default: auto-generated)
  initCount?: number;    // Number of times to execute test per sample (default: 1)
  maxTime?: number;      // Maximum time to run benchmark in seconds (default: 5)
  minSamples?: number;   // Minimum sample size required (default: 5)
  minTime?: number;      // Minimum time to run benchmark in seconds (default: 0)
  name?: string;         // Benchmark display name
  onAbort?: function;    // Abort event handler
  onComplete?: function; // Complete event handler
  onCycle?: function;    // Cycle event handler
  onError?: function;    // Error event handler
  onReset?: function;    // Reset event handler
  onStart?: function;    // Start event handler
  setup?: function|string;    // Setup code executed before each test cycle
  teardown?: function|string; // Teardown code executed after each test cycle
}

// Statistical analysis results
interface BenchmarkStats {
  deviation: number;     // Standard deviation of samples
  mean: number;         // Sample arithmetic mean in seconds
  moe: number;          // Margin of error
  rme: number;          // Relative margin of error as percentage
  sample: number[];     // Array of sample times in seconds
  sem: number;          // Standard error of the mean
  variance: number;     // Sample variance
}

// Timing information
interface BenchmarkTimes {
  cycle: number;        // Time taken to complete the last cycle in seconds
  elapsed: number;      // Total time elapsed for the benchmark in seconds
  period: number;       // Time period of a single operation in seconds
  timeStamp: number;    // Timestamp in milliseconds when the cycle started
}