@nextrush/timer

Measure how long requests take to process. Uses performance.now() for sub-millisecond accuracy and supports the Server-Timing header for browser DevTools integration.

Installation

$ pnpm add @nextrush/timer

Minimal Usage

import { createApp } from '@nextrush/core';
import { timer } from '@nextrush/timer';

const app = createApp();
app.use(timer());
// Response header: X-Response-Time: 12.34ms

The duration is stored in ctx.state.responseTime as a number (milliseconds).

API Reference

`timer(options?)`

Create response time middleware.

function timer(options?: TimerOptions): Middleware;

TimerOptions

Property	Type	Description
`header`	`string`= 'X-Response-Time'	Response header name
`suffix`	`string`= 'ms'	Time unit suffix
`precision`	`number`= 2	Decimal places (0–6)
`stateKey`	`string`= 'responseTime'	Key in ctx.state for duration
`exposeHeader`	`boolean`= false	Set response header
`now`	`() => number`= performance.now	Custom time getter

The exposeHeader option defaults to false. Set it to true to include the timing header in responses.

`responseTime(options?)`

Alias for timer().

function responseTime(options?: TimerOptions): Middleware;

`serverTiming(options?)`

Create Server-Timing middleware for browser DevTools integration.

function serverTiming(options?: ServerTimingOptions): Middleware;

import { serverTiming } from '@nextrush/timer';

app.use(serverTiming());
// Header: Server-Timing: total;dur=12.34

ServerTimingOptions

Property	Type	Description
`metric`	`string`= 'total'	Metric name
`description?`	`string`	Optional metric description
`precision`	`number`= 2	Decimal places (0–6)
`stateKey`	`string`= 'responseTime'	Key in ctx.state for duration
`exposeHeader`	`boolean`= false	Set response header
`now`	`() => number`= performance.now	Custom time getter

With a description:

app.use(
  serverTiming({
    metric: 'api',
    description: 'API Response Time',
  })
);
// Header: Server-Timing: api;dur=12.34;desc="API Response Time"

`detailedTimer(options?)`

Create detailed timer middleware that stores a TimingResult object instead of a plain number.

function detailedTimer(options?: DetailedTimerOptions): Middleware;

DetailedTimerOptions (extends TimerOptions)

Property	Type	Description
`detailed`	`boolean`= false	Store TimingResult object in ctx.state

TimingResult

Property	Type	Description
`duration`	`number`	Duration in milliseconds
`formatted`	`string`	Formatted string (e.g. "12.34ms")
`start`	`number`	Start timestamp from performance.now()
`end`	`number`	End timestamp from performance.now()

Set detailed: true to get a TimingResult object. Without it, detailedTimer stores a plain number — the same as timer().

import { detailedTimer } from '@nextrush/timer';
import type { TimingResult } from '@nextrush/timer';

app.use(detailedTimer({ detailed: true }));

app.use(async (ctx) => {
  await ctx.next();
  const timing = ctx.state.responseTime as TimingResult;
  console.log(timing.duration); // 12.34
  console.log(timing.formatted); // "12.34ms"
});

Practical Example

Track both database and total timing with Server-Timing headers:

import { serverTiming } from '@nextrush/timer';

// Database timing (custom)
app.use(async (ctx) => {
  const dbStart = performance.now();
  await db.query('SELECT * FROM users');
  const dbTime = performance.now() - dbStart;
  ctx.set('Server-Timing', `db;dur=${dbTime.toFixed(2)};desc="Database"`);
  await ctx.next();
});

// Total request timing
app.use(serverTiming({ metric: 'total' }));

View results in Chrome DevTools → Network → Timing tab.

Middleware Overview — All middleware packages
@nextrush/request-id — Request tracking

TimerOptions

ServerTimingOptions

DetailedTimerOptions (extends TimerOptions)

TimingResult

On this page