vesta

Simplify time measurements.

🇺🇦 Help Ukraine

I woke up on my 26th birthday at 5 am from the blows of russian missiles. They attacked the city of Kyiv, where I live, as well as the cities in which my family and friends live. Now my country is a war zone.

We fight for democratic values, freedom, for our future! Once again Ukrainians have to stand against evil, terror, against genocide. The outcome of this war will determine what path human history is taking from now on.

💛💙 Help Ukraine! We need your support! There are dozen ways to help us, just do it!

Table of Contents

• vesta
  • 🇺🇦 Help Ukraine
  • Table of Contents
  • Requirements
  • Installation
  • Usage
    • Minimal Configuration
    • Sequences
    • Timers
    • Reports
    • Customization
      • Custom mertics
    • Memory
  • Contribute

Requirements

To use library you need to have node and npm installed in your machine:

• node >=10
• npm >=6

Package is continuously tested on darwin, linux and win32 platforms. All active and maintenance LTS node releases are supported.

Installation

To install the library run the following command

  npm i --save vesta

Usage

Minimal Configuration

import BenchMark from 'vesta';

const bench = new BenchMark();

await Promise.all([ 10, 20, 30, 40, 50, 60 ].map(async i => {
    const bi = bench.start('pause');

    await pause(i);
    bench.end(bi);
}));

console.log(bench.report());
// ------------------------
// Label: pause
// Total: 6
// Mean: 35.166666666666664
// Q25: 22.75
// Q75: 47.5

Sequences

in case of consecutive measurements use next api:

import BenchMark, { JSONReporter } from 'vesta';

const bench = new BenchMark();

bench.sequence('before cycle');

for (const iter of [ 1, 2, 3 ]) {
    const iteration = bench.iteration(iter);

    iteration.sequence('before iteration');
    await pause(15);
    iteration.sequence('15ms gone');
    await pause(10);
    iteration.sequence('after 10ms more');
    await pause(20);
    iteration.sequence('end of the iteration');
}

bench.sequence('after cycle');

console.log(bench.report(new JSONReporter()));
// [{"label":"before cycle","benchmark":0},{"label":"after cycle","benchmark":139},{"label":"before iteration","total":3,"mean":0,"q25":0,"q75":0},{"label":"15ms gone","total":3,"mean":15.333333333333334,"q25":15,"q75":15.5},{"label":"after 10ms more","total":3,"mean":10,"q25":10,"q75":10},{"label":"end of the iteration","total":3,"mean":20,"q25":20,"q75":20}]

Timers

Timers are used to fix the moment of time. By default Timer is autodetected among process.hrtime.bigint() performance.now() or new Date() depending on your environment.

All timers available from package:

import { Timer, ProcessHrtime, PerformanceNow } from 'vesta';

you can pass any of them explicitly:

import { Timer } from 'vesta';

class customTimer extends Timer {}

const bench = new BenchMark({
    counter : new customTimer()
});

to implement own timer it is recomended to extends Timer and follow it's interfece.

Reports

There are two reports available:

• JSONReporter - report in json format, usefull for external export.
• PlainReporter - used by default.

use custom reporter on report generation:

import BenchMark, { JSONReporter } from 'vesta';

const bench = new BenchMark();

const report = JSON.parse(bench.report(new JSONReporter()));

to pretty print numbers in report use:

import BenchMark, { PlainReporter } from 'vesta';

const bench = new BenchMark();

bench.report(new PlainReporter(), { pretty: true });

or pass pretty as configuration object:

import BenchMark, { JSONReporter } from 'vesta';

const bench = new BenchMark({});

bench.sequence('before');
await pause(2500);
bench.sequence('after');

console.log(
    bench.report(new JSONReporter(), {
        pretty : {
            exclude : [ 'total' ],
            include : [ 'mean', 'benchmark' ]
        }
    })
);

// [
//     { label: 'before', benchmark: 0 },
//     { label: 'after', benchmark: '2s 504ms' }
// ];

where

• include - array with metric names, for which prettifier will be added.
• exclude - array with metric names, for which prettifier won't be added.

Customization

pass next options to BenchMark properties:

• shortSingleObservations (boolean): use short report when there are only 1 observation. true by default.
• counter (Timer): time measurer. autodetector by default.

Custom mertics

To enrich your reports, you can easily introduce new metrics to the benchmark calculations in your JavaScript code. Utilize the calculate() method along with metrics and items objects within the BenchMark instance:

import BenchMark from 'vesta';

const bench = new BenchMark({});

bench.calculate({
    metrics : {
        over25ms : arr => arr.filter(i => i > 25).length, // number of benchmarks longer then 25ms,

        // Omit calculation for quantiles
        q25 : null,
        q75 : null
    },
    items : {
        // Identify benchmarks over the mean value
        overMean : (arr, metrics) => arr.filter(i => i.bench > metrics.mean).map(i => i.payload)
    }
});

Some of the other custom metrics you might be looking for:

• include a metric for the mean value over the last 10 records exclusively:

metrics : {
    last10 : arr => BenchMark.metrics.mean(arr.slice(-10));
}

These additions allow you to tailor the benchmarks and generate more comprehensive reports tailored to your specific needs.

Memory

Use the same API to benchmark memory usage:

import { Memory, PlainReporter } from 'vesta';

const bench = new Memory();

const b1 = bench.start('before');
const a = Array.from({ length: 1e7 });

bench.end(b1);

console.log(bench.report(new PlainReporter(), { pretty: true }));

//   ------------------------
// Label: before
// Rss: 76.05MB
// HeapTotal: 76.3MB
// HeapUsed: 76.29MB
// External: 0MB
// ArrayBuffers: 0MB

Contribute

Make the changes to the code and tests. Then commit to your branch. Be sure to follow the commit message conventions. Read Contributing Guidelines for details.