Benchmark(name, fn[, options={}])

#ⓈⓉ

The Benchmark constructor.

Note: The Benchmark constructor exposes a handful of lodash methods to make working with arrays, collections, and objects easier. The lodash methods are:
each/forEach,forOwn,has,indexOf,map, andreduce

Arguments

1. name(string): A name to identify the benchmark.
2. fn(Function|string): The test to benchmark.
3. [options={}](Object): Options object.

Example

// basic usage (the `new` operator is optional)
var bench=new Benchmark(fn);

// or using a name first
var bench=new Benchmark('foo', fn);

// or with options
var bench=new Benchmark('foo', fn,{

 // displayed by `Benchmark#toString` if `name` is not available
 'id':'xyz',

 // called when the benchmark starts running
 'onStart': onStart,

 // called after each run cycle
 'onCycle': onCycle,

 // called when aborted
 'onAbort': onAbort,

 // called when a test errors
 'onError':onError,

 // called when reset
 'onReset': onReset,

 // called when the benchmark completes running
 'onComplete': onComplete,

 // compiled/called before the test loop
 'setup': setup,

 // compiled/called after the test loop
 'teardown': teardown
});

// or name and options
var bench=new Benchmark('foo',{

 // a flag to indicate the benchmark is deferred
 'defer':true,

 // benchmark test function
 'fn':function(deferred){
   // call `Deferred#resolve` when the deferred test is finished
    deferred.resolve();
 }
});

// or options only
var bench=new Benchmark({

 // benchmark name
 'name':'foo',

 // benchmark test as a string
 'fn':'[1,2,3,4].sort()'
});

// a test’s `this` binding is set to the benchmark instance
var bench=new Benchmark('foo',function(){
 'My name is '.concat(this.name);// "My name is foo"
});

Benchmark.version

#ⓈⓉ

(string): The semantic version number.

Benchmark.filter(array, callback)

#ⓈⓉ

A genericArray#filter like method.

Arguments

1. array(Array): The array to iterate over.
2. callback(Function|string): The function/alias called per iteration.

Returns

(Array): A new array of values that passed callback filter.

Example

// get odd numbers
Benchmark.filter([1,2,3,4,5],function(n){
 return n%2;
});// -> [1, 3, 5];

// get fastest benchmarks
Benchmark.filter(benches,'fastest');

// get slowest benchmarks
Benchmark.filter(benches,'slowest');

// get benchmarks that completed without erroring
Benchmark.filter(benches,'successful');

Benchmark.formatNumber(number)

#ⓈⓉ

Converts a number to a more readable comma-separated string representation.

Arguments

1. number(number): The number to convert.

Returns

(string): The more readable string representation.

Benchmark.invoke(benches, name[, args])

#ⓈⓉ

Invokes a method on all items in an array.

Arguments

1. benches(Array): Array of benchmarks to iterate over.
2. name(Object|string): The name of the method to invoke OR options object.
3. [args](…)*: Arguments to invoke the method with.

Returns

(Array): A new array of values returned from each method invoked.

Example

// invoke `reset` on all benchmarks
Benchmark.invoke(benches,'reset');

// invoke `emit` with arguments
Benchmark.invoke(benches,'emit','complete', listener);

// invoke `run(true)`, treat benchmarks as a queue, and register invoke callbacks
Benchmark.invoke(benches,{

 // invoke the `run` method
 'name':'run',

 // pass a single argument
 'args':true,

 // treat as queue, removing benchmarks from front of `benches` until empty
 'queued':true,

 // called before any benchmarks have been invoked.
 'onStart': onStart,

 // called between invoking benchmarks
 'onCycle': onCycle,

 // called after all benchmarks have been invoked.
 'onComplete': onComplete
});

Benchmark.join(object[, separator1=',', separator2=': '])

#ⓈⓉ

Creates a string of joined array values or object key-value pairs.

Arguments

1. object(Array|Object): The object to operate on.
2. [separator1=','](string): The separator used between key-value pairs.
3. [separator2=': '](string): The separator used between keys and values.

Returns

(string): The joined result.

Benchmark.runInContext([context=root])

#ⓈⓉ

Create a newBenchmark function using the givencontext object.

Arguments

1. [context=root](Object): The context object.

Returns

(Function): Returns a newBenchmark function.

Benchmark.prototype.aborted

#ⓈⓉ

(boolean): A flag to indicate if the benchmark is aborted.

Benchmark.prototype.compiled

#ⓈⓉ

(Function, string): The compiled test function.

Benchmark.prototype.count

#ⓈⓉ

(number): The number of times a test was executed.

Benchmark.prototype.cycles

#ⓈⓉ

(number): The number of cycles performed while benchmarking.

Benchmark.prototype.error

#ⓈⓉ

(Object): The error object if the test failed.

Benchmark.prototype.fn

#ⓈⓉ

(Function, string): The test to benchmark.

Benchmark.prototype.hz

#ⓈⓉ

(number): The number of executions per second.

Benchmark.prototype.running

#ⓈⓉ

(boolean): A flag to indicate if the benchmark is running.

Benchmark.prototype.setup

#ⓈⓉ

(Function, string): Compiled into the test and executed immediatelybefore the test loop.

Example

// basic usage
var bench= Benchmark({
 'setup':function(){
   var c=this.count,
        element= document.getElementById('container');
   while(c--){
      element.appendChild(document.createElement('div'));
   }
 },
 'fn':function(){
    element.removeChild(element.lastChild);
 }
});

// compiles to something like:
var c=this.count,
    element= document.getElementById('container');
while(c--){
  element.appendChild(document.createElement('div'));
}
var start=new Date;
while(count--){
  element.removeChild(element.lastChild);
}
var end=new Date- start;

// or using strings
var bench= Benchmark({
 'setup':'\
    var a = 0;\n\
    (function() {\n\
      (function() {\n\
        (function() {',
 'fn':'a += 1;',
 'teardown':'\
         }())\n\
       }())\n\
     }())'
});

// compiles to something like:
var a=0;
(function(){
 (function(){
   (function(){
     var start=new Date;
     while(count--){
        a+=1;
     }
     var end=new Date- start;
   }())
 }())
}())

Benchmark.prototype.teardown

#ⓈⓉ

(Function, string): Compiled into the test and executed immediatelyafter the test loop.

Benchmark.prototype.abort()

#ⓈⓉ

Aborts the benchmark without recording times.

Returns

(Object): The benchmark instance.

Benchmark.prototype.clone(options)

#ⓈⓉ

Creates a new benchmark using the same test and options.

Arguments

1. options(Object): Options object to overwrite cloned options.

Returns

(Object): The new benchmark instance.

Example

var bizarro= bench.clone({
 'name':'doppelganger'
});

Benchmark.prototype.compare(other)

#ⓈⓉ

Determines if a benchmark is faster than another.

Arguments

1. other(Object): The benchmark to compare.

Returns

(number): Returns-1 if slower,1 if faster, and0 if indeterminate.

Benchmark.Suite.prototype.emit(type[, args])

#ⓈⓉ

Executes all registered listeners of the specified event type.

Arguments

1. type(Object|string): The event type or object.
2. [args](…)*: Arguments to invoke the listener with.

Returns

()*: Returns the return value of the last listener executed.

Benchmark.Suite.prototype.listeners(type)

#ⓈⓉ

Returns an array of event listeners for a given type that can be manipulated to add or remove listeners.

Arguments

1. type(string): The event type.

Returns

(Array): The listeners array.

Benchmark.Suite.prototype.off([type, listener])

#ⓈⓉ

Unregisters a listener for the specified event type(s), or unregisters all listeners for the specified event type(s), or unregisters all listeners for all event types.

Arguments

1. [type](string): The event type.
2. [listener](Function): The function to unregister.

Returns

(Object): The benchmark instance.

Example

// unregister a listener for an event type
bench.off('cycle', listener);

// unregister a listener for multiple event types
bench.off('start cycle', listener);

// unregister all listeners for an event type
bench.off('cycle');

// unregister all listeners for multiple event types
bench.off('start cycle complete');

// unregister all listeners for all event types
bench.off();

Benchmark.Suite.prototype.on(type, listener)

#ⓈⓉ

Registers a listener for the specified event type(s).

Arguments

1. type(string): The event type.
2. listener(Function): The function to register.

Returns

(Object): The benchmark instance.

Example

// register a listener for an event type
bench.on('cycle', listener);

// register a listener for multiple event types
bench.on('start cycle', listener);

Benchmark.prototype.reset()

#ⓈⓉ

Reset properties and abort if running.

Returns

(Object): The benchmark instance.

Benchmark.prototype.run([options={}])

#ⓈⓉ

Runs the benchmark.

Arguments

1. [options={}](Object): Options object.

Returns

(Object): The benchmark instance.

Example

// basic usage
bench.run();

// or with options
bench.run({'async':true});

Benchmark.prototype.toString()

#ⓈⓉ

Displays relevant benchmark information when coerced to a string.

Returns

(string): A string representation of the benchmark instance.

Benchmark.options

#ⓈⓉ

(Object): The default options copied by benchmark instances.

Benchmark.options.async

#ⓈⓉ

(boolean): A flag to indicate that benchmark cycles will execute asynchronously by default.

Benchmark.options.defer

#ⓈⓉ

(boolean): A flag to indicate that the benchmark clock is deferred.

Benchmark.options.delay

#ⓈⓉ

(number): The delay between test cycles(secs).

Benchmark.options.id

#ⓈⓉ

(string): Displayed byBenchmark#toString when aname is not available(auto-generated if absent).

Benchmark.options.initCount

#ⓈⓉ

(number): The default number of times to execute a test on a benchmark’s first cycle.

Benchmark.options.maxTime

#ⓈⓉ

(number): The maximum time a benchmark is allowed to run before finishing(secs).

Note: Cycle delays aren't counted toward the maximum time.

Benchmark.options.minSamples

#ⓈⓉ

(number): The minimum sample size required to perform statistical analysis.

Benchmark.options.minTime

#ⓈⓉ

(number): The time needed to reduce the percent uncertainty of measurement to1%(secs).

Benchmark.options.name

#ⓈⓉ

(string): The name of the benchmark.

Benchmark.options.onAbort

#ⓈⓉ

An event listener called when the benchmark is aborted.

Benchmark.options.onComplete

#ⓈⓉ

An event listener called when the benchmark completes running.

Benchmark.options.onCycle

#ⓈⓉ

An event listener called after each run cycle.

Benchmark.options.onError

#ⓈⓉ

An event listener called when a test errors.

Benchmark.options.onReset

#ⓈⓉ

An event listener called when the benchmark is reset.

Benchmark.options.onStart

#ⓈⓉ

An event listener called when the benchmark starts running.

Benchmark.platform

#ⓈⓉ

(Object): Platform object with properties describing things like browser name, version, and operating system. Seeplatform.js.

Benchmark.support

#ⓈⓉ

(Object): An object used to flag environments/features.

Benchmark.support.browser

#ⓈⓉ

(boolean): Detect if running in a browser environment.

Benchmark.support.decompilation

#ⓈⓉ

(boolean): Detect if function decompilation is support.

Benchmark.support.timeout

#ⓈⓉ

(boolean): Detect if the Timers API exists.

Benchmark.prototype.stats

#ⓈⓉ

(Object): An object of stats including mean, margin or error, and standard deviation.

Benchmark.prototype.stats.deviation

#ⓈⓉ

(number): The sample standard deviation.

Benchmark.prototype.stats.mean

#ⓈⓉ

(number): The sample arithmetic mean(secs).

Benchmark.prototype.stats.moe

#ⓈⓉ

(number): The margin of error.

Benchmark.prototype.stats.rme

#ⓈⓉ

(number): The relative margin of error(expressed as a percentage of the mean).

Benchmark.prototype.stats.sample

#ⓈⓉ

(Array): The array of sampled periods.

Benchmark.prototype.stats.sem

#ⓈⓉ

(number): The standard error of the mean.

Benchmark.prototype.stats.variance

#ⓈⓉ

(number): The sample variance.

Benchmark.prototype.times

#ⓈⓉ

(Object): An object of timing data including cycle, elapsed, period, start, and stop.

Benchmark.prototype.times.cycle

#ⓈⓉ

(number): The time taken to complete the last cycle(secs).

Benchmark.prototype.times.elapsed

#ⓈⓉ

(number): The time taken to complete the benchmark(secs).

Benchmark.prototype.times.period

#ⓈⓉ

(number): The time taken to execute the test once(secs).

Benchmark.prototype.times.timeStamp

#ⓈⓉ

(number): A timestamp of when the benchmark started(ms).

Benchmark.Deferred(clone)

#ⓈⓉ

The Deferred constructor.

Arguments

1. clone(Object): The cloned benchmark instance.

Benchmark.Deferred.prototype.benchmark

#ⓈⓉ

(Object): The deferred benchmark instance.

Benchmark.Deferred.prototype.cycles

#ⓈⓉ

(number): The number of deferred cycles performed while benchmarking.

Benchmark.Deferred.prototype.elapsed

#ⓈⓉ

(number): The time taken to complete the deferred benchmark(secs).

Benchmark.Deferred.prototype.timeStamp

#ⓈⓉ

(number): A timestamp of when the deferred benchmark started(ms).

Benchmark.Event(type)

#ⓈⓉ

The Event constructor.

Arguments

1. type(Object|string): The event type.

Benchmark.Event.prototype.aborted

#ⓈⓉ

(boolean): A flag to indicate if the emitters listener iteration is aborted.

Benchmark.Event.prototype.cancelled

#ⓈⓉ

(boolean): A flag to indicate if the default action is cancelled.

Benchmark.Event.prototype.currentTarget

#ⓈⓉ

(Object): The object whose listeners are currently being processed.

Benchmark.Event.prototype.result

#ⓈⓉ

(Mixed): The return value of the last executed listener.

Benchmark.Event.prototype.target

#ⓈⓉ

(Object): The object to which the event was originally emitted.

Benchmark.Event.prototype.timeStamp

#ⓈⓉ

(number): A timestamp of when the event was created(ms).

Benchmark.Event.prototype.type

#ⓈⓉ

(string): The event type.

Benchmark.Suite(name[, options={}])

#ⓈⓉ

The Suite constructor.

Note: Each Suite instance has a handful of wrapped lodash methods to make working with Suites easier. The wrapped lodash methods are:
each/forEach,indexOf,map, andreduce

Arguments

1. name(string): A name to identify the suite.
2. [options={}](Object): Options object.

Example

// basic usage (the `new` operator is optional)
var suite=new Benchmark.Suite;

// or using a name first
var suite=new Benchmark.Suite('foo');

// or with options
var suite=new Benchmark.Suite('foo',{

 // called when the suite starts running
 'onStart': onStart,

 // called between running benchmarks
 'onCycle': onCycle,

 // called when aborted
 'onAbort': onAbort,

 // called when a test errors
 'onError':onError,

 // called when reset
 'onReset': onReset,

 // called when the suite completes running
 'onComplete': onComplete
});

Benchmark.Suite.prototype.aborted

#ⓈⓉ

(boolean): A flag to indicate if the suite is aborted.

Benchmark.Suite.prototype.length

#ⓈⓉ

(number): The number of benchmarks in the suite.

Benchmark.Suite.prototype.running

#ⓈⓉ

(boolean): A flag to indicate if the suite is running.

Benchmark.Suite.prototype.abort()

#ⓈⓉ

Aborts all benchmarks in the suite.

Returns

(Object): The suite instance.

Benchmark.Suite.prototype.add(name, fn[, options={}])

#ⓈⓉ

Adds a test to the benchmark suite.

Arguments

1. name(string): A name to identify the benchmark.
2. fn(Function|string): The test to benchmark.
3. [options={}](Object): Options object.

Returns

(Object): The benchmark instance.

Example

// basic usage
suite.add(fn);

// or using a name first
suite.add('foo', fn);

// or with options
suite.add('foo', fn,{
 'onCycle': onCycle,
 'onComplete': onComplete
});

// or name and options
suite.add('foo',{
 'fn': fn,
 'onCycle': onCycle,
 'onComplete': onComplete
});

// or options only
suite.add({
 'name':'foo',
 'fn': fn,
 'onCycle': onCycle,
 'onComplete': onComplete
});

Benchmark.Suite.prototype.clone(options)

#ⓈⓉ

Creates a new suite with cloned benchmarks.

Arguments

1. options(Object): Options object to overwrite cloned options.

Returns

(Object): The new suite instance.

Benchmark.Suite.prototype.emit(type[, args])

#ⓈⓉ

Executes all registered listeners of the specified event type.

Arguments

1. type(Object|string): The event type or object.
2. [args](…)*: Arguments to invoke the listener with.

Returns

()*: Returns the return value of the last listener executed.

Benchmark.Suite.prototype.filter(callback)

#ⓈⓉ

AnArray#filter like method.

Arguments

1. callback(Function|string): The function/alias called per iteration.

Returns

(Object): A new suite of benchmarks that passed callback filter.

Benchmark.Suite.prototype.listeners(type)

#ⓈⓉ

Returns an array of event listeners for a given type that can be manipulated to add or remove listeners.

Arguments

1. type(string): The event type.

Returns

(Array): The listeners array.

Benchmark.Suite.prototype.off([type, listener])

#ⓈⓉ

Unregisters a listener for the specified event type(s), or unregisters all listeners for the specified event type(s), or unregisters all listeners for all event types.

Arguments

1. [type](string): The event type.
2. [listener](Function): The function to unregister.

Returns

(Object): The benchmark instance.

Example

// unregister a listener for an event type
bench.off('cycle', listener);

// unregister a listener for multiple event types
bench.off('start cycle', listener);

// unregister all listeners for an event type
bench.off('cycle');

// unregister all listeners for multiple event types
bench.off('start cycle complete');

// unregister all listeners for all event types
bench.off();

Benchmark.Suite.prototype.on(type, listener)

#ⓈⓉ

Registers a listener for the specified event type(s).

Arguments

1. type(string): The event type.
2. listener(Function): The function to register.

Returns

(Object): The benchmark instance.

Example

// register a listener for an event type
bench.on('cycle', listener);

// register a listener for multiple event types
bench.on('start cycle', listener);

Benchmark.Suite.prototype.reset()

#ⓈⓉ

Resets all benchmarks in the suite.

Returns

(Object): The suite instance.

Benchmark.Suite.prototype.run([options={}])

#ⓈⓉ

Runs the suite.

Arguments

1. [options={}](Object): Options object.

Returns

(Object): The suite instance.

Example

// basic usage
suite.run();

// or with options
suite.run({'async':true,'queued':true});

Benchmark.Suite.options

#ⓈⓉ

(Object): The default options copied by suite instances.

Benchmark.Suite.options.name

#ⓈⓉ

(string): The name of the suite.