Superagent HTTP Timings Plugin for Node.js

1.0.2 · active · verified Wed Apr 22

superagent-node-http-timings is a superagent plugin designed for Node.js environments to capture detailed HTTP request timing information. It provides granular metrics such as `socketAssigned`, `dnsLookup`, `tcpConnection`, `tlsHandshake`, `firstByte`, and `contentTransfer`, culminating in a `total` request duration. This allows developers to monitor and optimize network performance in Node.js applications, similar to a browser's network inspector. The current stable version is `1.0.2`, with recent updates addressing issues like HTTP keep-alive. While not a high-cadence package, it receives targeted fixes as needed, indicating active maintenance. Its key differentiator is providing a comprehensive breakdown of network timings specifically integrated into the `superagent` request flow for server-side environments.

Common errors

```
TypeError: require is not a function
```
cause Attempting to use `require()` in an ES Modules (ESM) file.

fix For ESM, use `import logNetworkTime from 'superagent-node-http-timings';` and ensure your `package.json` has `"type": "module"` or the file uses the `.mjs` extension.
```
TypeError: (0 , _superagentNodeHttpTimings.default) is not a function
```
cause Incorrect default import when the module's main export is a function (often happens with default CJS export imported as named in ESM).

fix Ensure you are directly importing the default export: `import logNetworkTime from 'superagent-node-http-timings';`
```
Error: Cannot find module 'superagent'
```
cause `superagent` peer dependency is not installed.

fix Install superagent: `npm install superagent` or `yarn add superagent`.

Warnings

gotcha This package is a CommonJS module. If you are working in an ES Modules (ESM) environment, direct named imports (`import { ... } from 'pkg'`) will not work. You will need to use a default import or a bundler to consume it correctly.
Fix: For ESM, use `import logNetworkTime from 'superagent-node-http-timings';`
gotcha The `superagent` package is a peer dependency. Ensure you have `superagent` installed in your project, and be aware of potential compatibility issues with very old or very new versions of `superagent`.
Fix: Install superagent: `npm install superagent` or `yarn add superagent`.
gotcha The timing callback function uses a Node.js-style error-first callback. Modern asynchronous code often prefers Promises or async/await. Ensure proper error handling within this callback, or wrap the `use` call in a Promise for easier integration with `async/await`.
Fix: Handle errors explicitly within the callback: `logNetworkTime((err, result) => { if (err) { console.error(err); return; } ... });`

Install

npm install superagent-node-http-timings npm
yarn add superagent-node-http-timings yarn
pnpm add superagent-node-http-timings pnpm

Imports

logNetworkTime
wrong:
```
import { logNetworkTime } from 'superagent-node-http-timings';
```
correct:
```
const logNetworkTime = require('superagent-node-http-timings');
```
This package is distributed as a CommonJS module. For ESM projects, you will typically need to use a default import: `import logNetworkTime from 'superagent-node-http-timings';` or configure your bundler.

Quickstart

This example demonstrates how to use the superagent-node-http-timings plugin to log detailed HTTP network timings for a GET request to google.com.

const request = require('superagent');
const logNetworkTime = require('superagent-node-http-timings');

async function makeTimedRequest() {
  try {
    const response = await request
      .get(`https://google.com`)
      .use(logNetworkTime((err, result) => {
        if (err) {
          console.error('Timing error:', err);
          return;
        }
        console.log('HTTP Timings:', result);
      }));
    console.log('Request completed with status:', response.status);
  } catch (error) {
    console.error('Request failed:', error.message);
  }
}

makeTimedRequest();

view raw JSON →