Stability: 1.1 - Active Development
The bench-node
module gives the ability to measure
performance of JavaScript code. To access it:
import benchmark from 'bench-node';
const benchmark = require('bench-node');
This module is only available under the node:
scheme. The following will not
work:
import benchmark from 'bench-node';
const benchmark = require('bench-node');
The following example illustrates how benchmarks are written using the
benchmark
module.
import { Suite } from 'bench-node';
const suite = new Suite();
suite.add('Using delete to remove property from object', function() {
const data = { x: 1, y: 2, z: 3 };
delete data.y;
data.x;
data.y;
data.z;
});
suite.run();
const { Suite } = require('bench-node');
const suite = new Suite();
suite.add('Using delete to remove property from object', function() {
const data = { x: 1, y: 2, z: 3 };
delete data.y;
data.x;
data.y;
data.z;
});
suite.run();
$ node my-benchmark.js
Using delete property x 5,853,505 ops/sec ± 0.01% (10 runs sampled) min..max=(169ns ... 171ns) p75=170ns p99=171ns
Stability: 1.1 Active Development
An Suite
is responsible for managing and executing
benchmark functions. It provides two methods: add()
and run()
.
options
{Object} Configuration options for the suite. The following properties are supported:reporter
{Function} Callback function with results to be called after benchmark is concluded. The callback function should receive two arguments:suite
- A {Suite} object andresult
- A object containing three properties:opsSec
{string},iterations {Number}
,histogram
{Histogram} instance.
If no reporter
is provided, the results will printed to the console.
import { Suite } from 'bench-node';
const suite = new Suite();
const { Suite } = require('bench-node');
const suite = new Suite();
name
{string} The name of the benchmark, which is displayed when reporting benchmark results.options
{Object} Configuration options for the benchmark. The following properties are supported:minTime
{number} The minimum time a benchmark can run. Default:0.05
seconds.maxTime
{number} The maximum time a benchmark can run. Default:0.5
seconds.
fn
{Function|AsyncFunction}- Returns: {Suite}
This method stores the benchmark of a given function (fn
).
The fn
parameter can be either an asynchronous (async function () {}
) or
a synchronous (function () {}
) function.
$ node my-benchmark.js
(node:14165) ExperimentalWarning: The benchmark module is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
Using delete property x 5,853,505 ops/sec ± 0.01% (10 runs sampled) min..max=(169ns ... 171ns) p75=170ns p99=171ns
- Returns:
{Promise<Array<Object>>}
opsSec
{number} The amount of operations per seconditerations
{number} The amount executions offn
histogram
{Histogram} Histogram object used to record benchmark iterations
The purpose of the run method is to run all the benchmarks that have been
added to the suite using the suite.add()
function.
By calling the run method, you can easily trigger the execution of all
the stored benchmarks and obtain the corresponding results.
You can customize the data reporting by passing an function to the reporter
argument while creating your Suite
:
import { Suite } from 'bench-node';
function reporter(bench, result) {
console.log(`Benchmark: ${bench.name} - ${result.opsSec} ops/sec`);
}
const suite = new Suite({ reporter });
suite.add('Using delete to remove property from object', () => {
const data = { x: 1, y: 2, z: 3 };
delete data.y;
data.x;
data.y;
data.z;
});
suite.run();
const { Suite } = require('bench-node');
function reporter(bench, result) {
console.log(`Benchmark: ${bench.name} - ${result.opsSec} ops/sec`);
}
const suite = new Suite({ reporter });
suite.add('Using delete to remove property from object', () => {
const data = { x: 1, y: 2, z: 3 };
delete data.y;
data.x;
data.y;
data.z;
});
suite.run();
$ node my-benchmark.js
Benchmark: Using delete to remove property from object - 6032212 ops/sec
The benchmark function has a special handling when you pass an argument, for example:
const { Suite } = require('bench-node');
const { readFileSync, writeFileSync, rmSync } = require('node:fs');
const suite = new Suite();
suite.add('readFileSync', (timer) => {
const randomFile = Date.now();
const filePath = `./${randomFile}.txt`;
writeFileSync(filePath, Math.random().toString());
timer.start();
readFileSync(filePath, 'utf8');
timer.end();
rmSync(filePath);
}).run();
In this way, you can control when the timer
will start
and also when the timer
will stop.
In the timer, we also give you a property count
that will tell you how much iterations
you should run your function to achieve the benchmark.minTime
,
see the following example:
import { Suite } from 'bench-node';
import { readFileSync, writeFileSync, rmSync } from 'node:fs';
const suite = new Suite();
suite.add('readFileSync', (timer) => {
const randomFile = Date.now();
const filePath = `./${randomFile}.txt`;
writeFileSync(filePath, Math.random().toString());
timer.start();
for (let i = 0; i < timer.count; i++)
readFileSync(filePath, 'utf8');
// You must send to the `.end` function the amount of
// times you executed the function, by default,
// the end will be called with value 1.
timer.end(timer.count);
rmSync(filePath);
});
suite.run();
const { Suite } = require('bench-node');
const { readFileSync, writeFileSync, rmSync } = require('node:fs');
const suite = new Suite();
suite.add('readFileSync', (timer) => {
const randomFile = Date.now();
const filePath = `./${randomFile}.txt`;
writeFileSync(filePath, Math.random().toString());
timer.start();
for (let i = 0; i < timer.count; i++)
readFileSync(filePath, 'utf8');
// You must send to the `.end` function the amount of
// times you executed the function, by default,
// the end will be called with value 1.
timer.end(timer.count);
rmSync(filePath);
});
suite.run();
Once your function has at least one argument,
you must call .start
and .end
, if you didn't,
it will throw the error ERR_BENCHMARK_MISSING_OPERATION.