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
    • Reporters
    • Customization
  • 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.

Reporters

• 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()));

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.

add new metrics:

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,

        // dont calculate quantiles
        q25 : null,
        q75 : null
    },
    items : {
        overMean : (arr, metrics) => arr.filter(i => i.bench > metrics.mean).map(i => i.payload)
    }
});

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.