Lapser

Lapser is a module for assessing performance of code execution (e.g. expensive function calls, db queries, web service calls...etc.)

Table of Contents

1. Installation and Usage
2. Examples
3. API

Installation and Usage

Prerequisites: Node.js >=10+, npm 6+.

You can install Lapser using npm:

``
$ npm install lapser --save
`

Examples

$3

`javascript
const Lapser = require("lapser");

//Create a lapser, providing an identifier for the call
let lapser = Lapser("Slow Algorithm");

//Manually start the tracker (also can autostart by providing flag with instantiation)
lapser.start();
//Begin function call
slowAlgorithm().then(_ => {
//Mark time lapse and output duration of function call
console.log(lapser.lapse().toString());
});
`
#### Output:
`
Slow Algorithm 3088ms
`

#### Async/Await alternative:
`javascript
const Lapser = require("lapser");

//Create a lapser, providing an identifier for the call
let lapser = Lapser("Slow Algorithm");

//Manually start the tracker (also can autostart by providing flag with instantiation)
lapser.start();

//Function call
await slowAlgorithm();

//Mark time lapse and output duration of function call
console.log(lapser.lapse().toString());
`

$3


`javascript
const Lapser = require("lapser");

//Detailed performance tracking
const slowAlgorithm = (params) => {
//instantiate new lapser with name and autostart the tracker
let lapser = Lapser("Slow Algorithm", true);
//Perform calls
loadDataset(params).then(dataset => {
lapser.lapse("Load dataset");
return reduce(dataset);
}).then(reducedData => {
lapser.lapse("Reduce dataset");
return analyse(reducedData);
}).then(results => {
lapser.lapse("Analysation");
return save(results);
}).then(_ => {
lapser.lapse("Save results");
//Output performance tracking
console.log(lapser.toString());
});
};
`

#### Output with total duration and individual durations.
`
Slow Algorithm 16391ms
- Load dataset 2588ms
- Reduce dataset 5128ms
- Analysation 3780ms
- Save results 4895ms
`

#### Async/Await alternative
`javascript
const Lapser = require("lapser");

//Detailed performance tracking
const slowAlgorithm = (params) => {
//instantiate new lapser with name and autostart the tracker
let lapser = Lapser("Slow Algorithm", true);

//Perform calls
let dataset = await loadDataset(params);
lapser.lapse("Load dataset");

let reducedData = await reduce(dataset);
lapser.lapse("Reduce dataset");

let resuts = await analyse(reducedData);
lapser.lapse("Analysation");

await save(results);
lapser.lapse("Save results");

//Output performance tracking
console.log(lapser.toString());
};
`
For a more compact async/await style, see withLapse function under the API section

API

Lapser([name][,autoStart])


* name An optional name for the lapser instance. A name will be automatically assigned if no name is provided.
* autoStart A flag to indiciate whether or not to automatically mark the start of the tracker.
* Returns: an lapser instance (a.k.a "lapser")

Returns a new instance of an elapase tracker (a.k.a "lapser")

`javascript
const Lapser = require("lapser");
let lapser = Lapser("Login", true);
`

Lapser.setAutostart(toggle)


* toggle

The Lapser.setAutostart() function toggles on or off, the autostart feature for all new lapse instances that are created. This makes it convenient if all lapse instances will use the autostart feature.

`javascript
const Lapser = require("lapser");
Lapser.setAutostart(true);
//No need to provide the autostart flag since it was already set to true globally.
let lapser = Lapser("Login");
`

start()

The start() function marks the beginning of the lapse tracker.

`javascript
const Lapser = require("lapser");
let lapser = Lapser("Login");
lapser.start(); //Begin timing
`

lapse([key])


* key An optional identifier for the timing cycle. If no argument is provided, one will be automatically assigned.
* Returns: the given lapser instance

The lapse() function marks the end of a timing cycle.

`javascript
const Lapser = require("lapser");
let lapser = Lapser("Login", true);

`

withLapse(key, evaluatedArg, [verbose]) [introduced in 0.1.22]


* key A mandatory identifier for the timing cycle.
* evaluatedArg the evaluated target (e.g. executed function)
* verbose when true, the elapsed time will be printed to STDOUT [introduced in 0.1.23]
* Returns: evaluatedArg the evaluated target (e.g. executed function)

The withLapse() function is used for compact async formatting

`javascript
const Lapser = require("lapser");
let lapser = Lapser("Slow Algorithm", true);

// the evaluated target parameter is passed in and returned as is to facilitate a concise lapse marking.
let dataset = lapser.withLapse("Load dataset", await loadDataset(params));
let reducedData = lapser.withLapse("Reduce dataset", await reduce(dataset));
let results = lapser.withLapse("Analysation", await analyse(reducedData);

lapser = lapser.withLapse("Save results", await save(results));

//Output performance tracking
console.log(lapser.toString());
`

elapsed()


* Returns: the number of milliseconds elapsed since the start

The elapsed() function provides the number of milliseconds that have elapsed since the lapser instance was started.

getName()


* Returns: the name of the lapser instance

The getName() function returns the name of the lapser instance.

getStart()


* Returns: start of the lapser instance as a unix timestamp.

The getStart() function returns the start of the lapser instance as a unix timestamp.

getLapses()


* Returns: