https-timer

A lightweight, dependency-free Node.js module for timing HTTP/HTTPS requests.

Useful for determining the duration of different HTTPS phases:

Socket Initialization
DNS Lookup
TCP Connection
TLS Handshake
Time to First Byte
Content Transfer

Used on PingMe.io for testing website latency.

Installation

$ npm install https-timer --save

Basic Usage

const httpsTimer = require('https-timer');
httpsTimer.get('https://www.google.com', (error, response) => {
  if (!error && response) {
    console.log(response.timing); // Prints the timing durations below
  }
});

When a request has ended, a timing object is added to the response object.

Here is an example snapshot of the timing object. The timing durations are in milliseconds:

{
  "durations": {
    "socketOpen": 1.579389,
    "dnsLookup": 39.922508,
    "tcpConnection": 28.770425,
    "tlsHandshake": 218.159047,
    "firstByte": 148.640706,
    "contentTransfer": 1.954565,
    "total": 439.02664
  }
}

Request with custom options

Since httpsTimer utilizes the native Node.js http and https modules, you can pass an options object when making a request:

const httpsTimer = require('https-timer');
const options = {
  url: 'https://api.github.com/repos/JoshCrozier/https-timer',
  headers: {
    'User-Agent': 'HTTPS Request Timer'
  }
};
httpsTimer.get(options, (error, response) => {
  if (!error && response && response.statusCode === 200) {
    console.log('Response body: ', JSON.parse(response.body));
    console.log('Response Timing: ', response.timing);
  } else {
    console.log('Request error: ', error);
  }
});

Promises and Async/Await

The get and request methods also have async equivalents: getAsync and requestAsync respectively.

Promise usage:

const httpsTimer = require('https-timer');
httpsTimer.getAsync('https://www.google.com').then(response => {
  console.log(response.timing);
});

Async/Await usage:

const httpsTimer = require('https-timer');
const response = await httpsTimer.getAsync('https://www.google.com');
console.log(response.timing);

For more detailed examples with error handling, see the examples directory.

Command-Line Usage

If you prefer to time requests directly from the command-line with preformatted output, you can alternatively install the time-request package:

$ npm install -g time-request

Usage:

$ time-request https://google.com

Example Output:

Request Phase               Duration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Socket Open                 1.61 ms
DNS Lookup                  34.15 ms
TCP Connection              47.69 ms
TLS Handshake               102.25 ms
Time to First Byte          67.23 ms
Content Transfer            1.69 ms
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Total                       254.62 ms

License

MIT License