Suite Management

/**
 * The Suite constructor creates a benchmark suite
 * @param {string} [name] - The name of the suite
 * @param {object} [options] - Suite configuration options
 * @returns {Benchmark.Suite} New suite instance
 */
function Benchmark.Suite(name, options);

// Can be called without 'new'
const suite = Benchmark.Suite('my-suite');
const suite2 = new Benchmark.Suite('my-suite');

const Benchmark = require('benchmark');

// Basic suite
const suite = new Benchmark.Suite;

// Named suite
const suite2 = new Benchmark.Suite('Performance Tests');

// With options
const suite3 = new Benchmark.Suite('API Tests', {
  onComplete: function() {
    console.log('Suite completed');
  }
});

// Execution state
suite.aborted;          // boolean: Whether suite was aborted
suite.running;          // boolean: Whether suite is currently running
suite.length;           // number: Number of benchmarks in suite

// Array-like properties (Suite extends Array)
suite[0];               // Benchmark: First benchmark
suite[1];               // Benchmark: Second benchmark
// ... etc

const suite = new Benchmark.Suite('test');

suite.add('test1', function() { Math.random(); })
     .add('test2', function() { Math.round(Math.random()); });

console.log('Suite length:', suite.length);        // 2
console.log('First benchmark:', suite[0].name);    // "test1"
console.log('Running:', suite.running);            // false

/**
 * Add a benchmark to the suite
 * @param {string} name - Benchmark name
 * @param {function|string} fn - Test function or code string
 * @param {object} [options] - Benchmark options
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.add(name, fn, options);

/**
 * Add benchmark to the beginning of the suite
 * @param {Benchmark|string} benchmark - Benchmark instance or name
 * @param {function|string} [fn] - Test function if first param is name
 * @param {object} [options] - Benchmark options if first param is name
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.unshift(benchmark, fn, options);

/**
 * Add benchmark to the end of the suite
 * @param {Benchmark|string} benchmark - Benchmark instance or name
 * @param {function|string} [fn] - Test function if first param is name
 * @param {object} [options] - Benchmark options if first param is name
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.push(benchmark, fn, options);

const suite = new Benchmark.Suite('String Operations');

// Add benchmarks with chaining
suite.add('RegExp#test', function() {
  /o/.test('Hello World!');
})
.add('String#indexOf', function() {
  'Hello World!'.indexOf('o') > -1;
})
.add('String#match', function() {
  'Hello World!'.match(/o/);
});

// Add with options
suite.add('Async test', function(deferred) {
  setTimeout(function() {
    deferred.resolve();
  }, 1);
}, { defer: true });

// Add existing benchmark
const existingBench = new Benchmark('External', function() { Math.random(); });
suite.push(existingBench);

// Add to beginning
suite.unshift('First test', function() { Date.now(); });

/**
 * Run all benchmarks in the suite
 * @param {object} [options] - Runtime options
 * @param {boolean} [options.async] - Run asynchronously (default: false)
 * @param {boolean} [options.queued] - Run benchmarks in sequence (default: false)
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.run(options);

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

/**
 * Reset all benchmarks in the suite
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.reset();

const suite = new Benchmark.Suite('Performance Tests');

suite.add('test1', function() { Math.random(); })
     .add('test2', function() { Math.round(Math.random()); });

// Add event listeners
suite.on('cycle', function(event) {
  console.log(String(event.target));
})
.on('complete', function() {
  console.log('Fastest is ' + this.filter('fastest').map('name'));
});

// Run synchronously
suite.run();

// Run asynchronously
suite.run({ async: true });

// Run in sequence (one at a time)
suite.run({ queued: true });

// Abort if needed
// suite.abort();

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

/**
 * Remove and return the last benchmark
 * @returns {Benchmark|undefined} The removed benchmark
 */
suite.pop();

/**
 * Remove and return the first benchmark
 * @returns {Benchmark|undefined} The removed benchmark
 */
suite.shift();

/**
 * Extract a slice of benchmarks
 * @param {number} [start=0] - Start index
 * @param {number} [end=length] - End index
 * @returns {Benchmark[]} Array of benchmarks
 */
suite.slice(start, end);

/**
 * Sort benchmarks in the suite
 * @param {function} [compareFn] - Comparison function
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.sort(compareFn);

/**
 * Reverse the order of benchmarks
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.reverse();

/**
 * Change suite contents by removing/adding benchmarks
 * @param {number} start - Start index
 * @param {number} deleteCount - Number to remove
 * @param {...Benchmark} items - Benchmarks to add
 * @returns {Benchmark[]} Array of removed benchmarks
 */
suite.splice(start, deleteCount, ...items);

/**
 * Join benchmark results into a string
 * @param {string} [separator=','] - Separator character
 * @returns {string} Joined results
 */
suite.join(separator);

const suite = new Benchmark.Suite;

suite.add('test1', function() { Math.random(); })
     .add('test2', function() { Math.round(Math.random()); })
     .add('test3', function() { Math.floor(Math.random()); });

// Remove last benchmark
const lastBench = suite.pop();
console.log('Removed:', lastBench.name); // "test3"

// Remove first benchmark
const firstBench = suite.shift();
console.log('Removed:', firstBench.name); // "test1"

// Get slice of benchmarks
const subset = suite.slice(0, 1);

// Sort by name
suite.sort(function(a, b) {
  return a.name.localeCompare(b.name);
});

// Reverse order
suite.reverse();

// Replace benchmarks
suite.splice(1, 1, new Benchmark('replacement', function() { Math.abs(Math.random()); }));

/**
 * Filter benchmarks in the suite
 * @param {function|string} callback - Filter function or property name
 * @returns {Benchmark[]} Array of filtered benchmarks
 */
suite.filter(callback);

/**
 * Iterate over each benchmark in the suite
 * @param {function} callback - Iterator function
 * @param {*} [thisArg] - Value to use as 'this'
 * @returns {Benchmark.Suite} The suite instance (chainable)
 */
suite.forEach(callback, thisArg);

/**
 * Find index of benchmark in suite
 * @param {Benchmark|function} benchmark - Benchmark or search function
 * @param {number} [fromIndex=0] - Start index
 * @returns {number} Index of benchmark (-1 if not found)
 */
suite.indexOf(benchmark, fromIndex);

/**
 * Transform each benchmark using callback
 * @param {function} callback - Transform function
 * @param {*} [thisArg] - Value to use as 'this'
 * @returns {*[]} Array of transformed values
 */
suite.map(callback, thisArg);

/**
 * Reduce suite to single value
 * @param {function} callback - Reducer function
 * @param {*} [initialValue] - Initial accumulator value
 * @returns {*} Reduced value
 */
suite.reduce(callback, initialValue);

const suite = new Benchmark.Suite;

suite.add('fast', function() { 1 + 1; })
     .add('slow', function() { Math.random() * 1000; })
     .add('medium', function() { Math.sqrt(16); });

// Run benchmarks first
suite.run();

// Filter fastest benchmarks
const fastest = suite.filter('fastest');
console.log('Fastest:', fastest.map(b => b.name));

// Filter by custom criteria
const highPerf = suite.filter(function(benchmark) {
  return benchmark.hz > 1000000;
});

// Iterate over benchmarks
suite.forEach(function(benchmark, index) {
  console.log(index + ':', benchmark.name, 'ops/sec:', benchmark.hz);
});

// Find benchmark by name
const targetIndex = suite.indexOf(suite.filter(function(b) { 
  return b.name === 'medium'; 
})[0]);

// Map to names
const names = suite.map(function(benchmark) {
  return benchmark.name;
});

// Reduce to total operations
const totalOps = suite.reduce(function(total, benchmark) {
  return total + benchmark.hz;
}, 0);

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

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

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

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

const suite = new Benchmark.Suite('Performance Suite');

// Add comprehensive event handling
suite.on('start', function() {
  console.log('Suite started');
})
.on('cycle', function(event) {
  console.log('Completed:', String(event.target));
})
.on('complete', function() {
  const fastest = this.filter('fastest');
  const slowest = this.filter('slowest');
  
  console.log('Results:');
  console.log('Fastest:', fastest.map('name').join(', '));
  console.log('Slowest:', slowest.map('name').join(', '));
  
  if (fastest.length > 1) {
    console.log('Multiple benchmarks tied for fastest');
  }
})
.on('error', function(event) {
  console.error('Suite error:', event.target.error);
})
.on('abort', function() {
  console.log('Suite was aborted');
});

// Add benchmarks and run
suite.add('RegExp#test', function() {
  /o/.test('Hello World!');
})
.add('String#indexOf', function() {
  'Hello World!'.indexOf('o') > -1;
})
.run({ async: true });

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

const originalSuite = new Benchmark.Suite('Original');

originalSuite.add('test1', function() { Math.random(); })
            .add('test2', function() { Math.round(Math.random()); });

// Clone with same benchmarks
const clonedSuite = originalSuite.clone();

// Clone with different name
const namedClone = originalSuite.clone({ name: 'Cloned Suite' });

// Clone with different options
const modifiedClone = originalSuite.clone({
  name: 'Modified',
  onComplete: function() {
    console.log('Modified suite completed');
  }
});

interface SuiteOptions {
  name?: string;         // Suite display name
  onAbort?: function;    // Abort event handler
  onComplete?: function; // Complete event handler
  onCycle?: function;    // Cycle event handler (called for each benchmark)
  onError?: function;    // Error event handler
  onReset?: function;    // Reset event handler
  onStart?: function;    // Start event handler
}

interface SuiteRunOptions {
  async?: boolean;       // Run suite asynchronously (default: false)
  queued?: boolean;      // Run benchmarks sequentially (default: false)
}