time-diff

Returns the formatted, high-resolution time difference between start and end times.

Install

Install with npm:

$ npm install time-diff --save

Usage

Uses [pretty-time][] to format time diffs.

var Time = require('time-diff');
var time = new Time();

// create a start time for `foo`
time.start('foo');

// call `end` wherever the `foo` process ends
console.log(time.end('foo'));
//=> 12ms

API

.start

Start a timer for the given name.

Params

• name {String}: Name to use for the starting time.
• returns {Array}: Returns the array from process.hrtime()

Example

var time = new Time();
time.start('foo');

.end

Returns the cumulative elapsed time since the first time time.start(name) was called.

Params

• name {String}: The name of the cached starting time to create the diff
• returns {Array}: Returns the array from process.hrtime()

Example

var time = new Time();
time.start('foo');

// do stuff
time.end('foo');
//=> 104μs

// do more stuff
time.end('foo');
//=> 1ms

// do more stuff
time.end('foo');
//=> 2ms

.diff

Returns a function for logging out out both the cumulative elapsed time since the first time .diff(name) was called, as well as the incremental elapsed time since the last .diff(name) was called. Unlike .end(), this method logs to stderr instead of returning a string. We could probably change this to return an object, feedback welcome.

Results in something like:

Params

• name {String}: The name of the starting time to store.
• options {String}

Example

var time = new Time();
var diff = time.diff('my-app-name');

// do stuff
diff('after init');
//=> [19:44:05] my-app-name: after init 108μs

// do more stuff
diff('before options');
//=> [19:44:05] my-app-name: before options 2ms (+2ms)

// do more stuff
diff('after options');
//=> [19:44:05] my-app-name: after options 2ms (+152μs)

Options

options.logDiff

Disable time diffs, or filter time diffs to the specified name(s).

type: Boolean|String

default: undefined

options.nocolor

Set to true to disable color in the output.

type: Boolean

default: undefined

Example

var diff = time.diff('foo', {nocolor: true});

options.formatArgs

Format arguments passed to process.stderr.

type: Function

default: undefined

Examples

Show message and elapsed time only:

var time = new Time();
var diff = time.diff('foo', {
  formatArgs: function(timestamp, name, msg, elapsed) {
    return [msg, elapsed];
  }
});

diff('first diff');
//=> 'first diff 36μs'
diff('second diff');
//=> 'second diff 71μs'

Show name and elapsed time only:

var diff = time.diff('foo', {
  formatArgs: function(timestamp, name, msg, elapsed) {
    return [name, elapsed];
  }
});

diff('first diff');
//=> 'foo 36μs'
diff('second diff');
//=> 'foo 71μs'

Examples

Create an instance of Time, optionally specifying the time scale to use and the number of decimal places to display.

Options

• options.smallest: the smallest time scale to show
• options.digits: the number of decimal places to display (digits)

Examples

(See [pretty-time][] for all available formats)

Given the following:

var time = new Time(options);
time.start('foo');

Returns milliseconds by default

console.log(time.end('foo'));
//=> 13ms

Milliseconds to 3 decimal places

console.log(time.end('foo', 'ms', 3));
// or
console.log(time.end('foo', 3));
//=> 12.743ms

Seconds to 3 decimal places

console.log(time.end('foo', 's', 3));
//=> 0.013s

Seconds

console.log(time.end('foo', 's'));
//=> 0s

Microseconds

console.log(time.end('foo', 'μs'));
//=> 12ms 934μs

Microseconds to 2 decimal places

console.log(time.end('foo', 'μs', 2));
//=> 14ms 435.78μs

nano-seconds

console.log(time.end('foo', 'n', 3));
//=> 13ms 796μs 677ns

nano-seconds to 3 decimal places

console.log(time.end('foo', 'n', 3));
//=> 13ms 427μs 633.000ns

CLI usage

If you're using time-diff with a command line application, try using [minimist][] for setting options.

var opts = {alias: {nocolor: 'n', logTime: 't', logDiff: 'd'}};
var argv = require('minimist')(process.argv.slice(2), opts);

var Time = require('time-diff');
var time = new Time(argv);

Related projects

You might also be interested in these projects:

• ansi-colors: Collection of ansi colors and styles. | homepage
• log-utils: Basic logging utils: colors, symbols and timestamp. | homepage
• pretty-time: Easily format the time from node.js process.hrtime. Works with timescales ranging from weeks to nanoseconds. | homepage
• time-diff: Returns the formatted, high-resolution time difference between start and end times. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Building docs

Generate readme and API documentation with [verb][]:

$ npm install verb && npm run docs

Or, if [verb][] is installed globally:

$ verb

Running tests

Install dev dependencies:

$ npm install -d && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2016, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb, v0.9.0, on April 30, 2016.

pretty-time minimist verb