0
# Response Time
1

2
Response Time is a Node.js middleware library that measures and reports HTTP request response times. It creates middleware that records the elapsed time from when a request enters the middleware to when the response headers are written out to the client.
3

4
## Package Information
5

6
- **Package Name**: response-time
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install response-time`
10

11
## Core Imports
12

13
```javascript
14
const responseTime = require('response-time');
15
```
16

17
## Basic Usage
18

19
```javascript
20
const express = require('express');
21
const responseTime = require('response-time');
22

23
const app = express();
24

25
// Add X-Response-Time header automatically
26
app.use(responseTime());
27

28
app.get('/', (req, res) => {
29
  res.send('hello, world!');
30
});
31

32
app.listen(3000);
33
```
34

35
## Capabilities
36

37
### Automatic Header Mode
38

39
Creates middleware that automatically adds an X-Response-Time header to responses.
40

41
```javascript { .api }
42
/**
43
 * Create middleware that adds X-Response-Time header displaying response duration
44
 * @param {ResponseTimeOptions} [options] - Configuration options
45
 * @returns {Function} Express/Connect middleware function
46
 */
47
function responseTime(options?: ResponseTimeOptions): MiddlewareFunction;
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
const express = require('express');
54
const responseTime = require('response-time');
55

56
const app = express();
57

58
// Default options (3 digits, X-Response-Time header, ms suffix)
59
app.use(responseTime());
60

61
// Custom precision
62
app.use(responseTime({ digits: 5 }));
63

64
// Custom header name  
65
app.use(responseTime({ header: 'X-Time-Taken' }));
66

67
// No suffix
68
app.use(responseTime({ suffix: false }));
69

70
// Combined options
71
app.use(responseTime({
72
  digits: 2,
73
  header: 'X-Processing-Time',
74
  suffix: true
75
}));
76
```
77

78
### Custom Callback Mode
79

80
Creates middleware that measures response time and calls a custom function with the timing data.
81

82
```javascript { .api }
83
/**
84
 * Create middleware that records response time and calls custom callback
85
 * @param {ResponseTimeCallback} fn - Callback function receiving timing data
86
 * @returns {Function} Express/Connect middleware function
87
 */
88
function responseTime(fn: ResponseTimeCallback): MiddlewareFunction;
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
const express = require('express');
95
const responseTime = require('response-time');
96
const StatsD = require('node-statsd');
97

98
const app = express();
99
const stats = new StatsD();
100

101
// Custom metrics collection
102
app.use(responseTime((req, res, time) => {
103
  const stat = (req.method + req.url).toLowerCase()
104
    .replace(/[:.]/g, '')
105
    .replace(/\//g, '_');
106
  stats.timing(stat, time);
107
}));
108

109
// Logging response times
110
app.use(responseTime((req, res, time) => {
111
  console.log(`${req.method} ${req.url} - ${time}ms`);
112
}));
113

114
// Conditional processing
115
app.use(responseTime((req, res, time) => {
116
  if (time > 1000) {
117
    console.warn(`Slow request: ${req.method} ${req.url} took ${time}ms`);
118
  }
119
}));
120
```
121

122
### Vanilla HTTP Server Usage
123

124
Response-time can be used with vanilla Node.js HTTP servers without Express.
125

126
**Usage Example:**
127

128
```javascript
129
const http = require('http');
130
const finalhandler = require('finalhandler');
131
const responseTime = require('response-time');
132

133
// Create middleware instance
134
const _responseTime = responseTime();
135

136
http.createServer((req, res) => {
137
  const done = finalhandler(req, res);
138
  
139
  _responseTime(req, res, (err) => {
140
    if (err) return done(err);
141
    
142
    // Respond to request
143
    res.setHeader('content-type', 'text/plain');
144
    res.end('hello, world!');
145
  });
146
}).listen(3000);
147
```
148

149
## Types
150

151
```javascript { .api }
152
/**
153
 * Configuration options for automatic header mode
154
 */
155
interface ResponseTimeOptions {
156
  /** Number of decimal digits in output (default: 3) */
157
  digits?: number;
158
  /** Name of response header to set (default: 'X-Response-Time') */  
159
  header?: string;
160
  /** Whether to add 'ms' suffix to output (default: true) */
161
  suffix?: boolean;
162
}
163

164
/**
165
 * Callback function for custom response time handling
166
 * @param req - HTTP request object
167
 * @param res - HTTP response object  
168
 * @param time - Response time in milliseconds
169
 */
170
type ResponseTimeCallback = (req: any, res: any, time: number) => void;
171

172
/**
173
 * Express/Connect middleware function signature
174
 * @param req - HTTP request object
175
 * @param res - HTTP response object
176
 * @param next - Next middleware function
177
 */
178
type MiddlewareFunction = (req: any, res: any, next: Function) => void;
179
```
180

181
## Backward Compatibility
182

183
The library supports a deprecated single number argument for backwards compatibility:
184

185
```javascript
186
// Deprecated - triggers deprecation warning
187
app.use(responseTime(3));
188

189
// Equivalent modern usage
190
app.use(responseTime({ digits: 3 }));
191
```
192

193
## Error Handling
194

195
Response-time follows standard Express middleware error handling patterns. If an error occurs, it will be passed to the next middleware via the `next(err)` function.
196

197
## Integration Patterns
198

199
### Express Application
200

201
```javascript
202
const express = require('express');
203
const responseTime = require('response-time');
204

205
const app = express();
206

207
// Apply to all routes
208
app.use(responseTime());
209

210
app.get('/api/users', (req, res) => {
211
  // Your route logic
212
  res.json({ users: [] });
213
});
214
```
215

216
### Connect Application
217

218
```javascript
219
const connect = require('connect');
220
const responseTime = require('response-time');
221

222
const app = connect();
223

224
app.use(responseTime());
225
app.use((req, res) => {
226
  res.end('Hello World');
227
});
228
```