Capture HTTP Response Content

1.0.3 · maintenance · verified Wed Apr 22

on-http-end is a lightweight Node.js utility designed to intercept and capture the full HTTP response payload, including headers, status code, and the final data, just before the response stream concludes. Inspired by `apicache`, it offers a simple, callback-based API to register a function that executes when `res.end()` is called. This allows developers to inspect or process the complete response content and metadata, making it suitable for logging, debugging, or custom caching mechanisms. The current stable version is 1.0.3, which includes a fix for proper scope handling, allowing multiple `onEnd` registrations on a single response object. Its release cadence appears infrequent, reflecting its focused scope and stable API. A key differentiator is its direct, low-level integration with Node.js's native `http.ServerResponse` object, providing granular control without the overhead of a full middleware framework.

Common errors

```
TypeError: onEnd is not a function
```
cause Attempting to import `on-http-end` using an incorrect syntax for the current module context (e.g., ESM `import` in a CommonJS file or vice-versa), or a typo in the symbol name.

fix For CommonJS (most Node.js projects without 'type: module' in package.json): `const onEnd = require('on-http-end')`. For ES Modules: `import onEnd from 'on-http-end'`.
```
Error: Can't set headers after they are sent.
```
cause This error occurs when you attempt to modify HTTP headers or the status code within the `onEnd` callback or after `res.end()` has already been called elsewhere.

fix All header and status code modifications must occur *before* `res.end()` is called. The `onEnd` callback is purely for observing the final response data and metadata, not for altering it.
```
onEnd callback not firing or payload.data is empty/missing.
```
cause The `onEnd` callback was registered *after* `res.end()` was called, or `res.end()` was never called on the response object.

fix Ensure that `onEnd(res, callback)` is invoked *before* `res.end()` is called in your request handler. Verify that `res.end()` is indeed being called to terminate the response.

Warnings

gotcha Prior to `v1.0.3`, registering `on-http-end` multiple times on the same `http.ServerResponse` object could lead to previous registrations being overwritten or unexpected behavior. This was fixed to properly allow multiple callbacks.
Fix: Upgrade to `on-http-end@1.0.3` or newer to ensure all registered `onEnd` callbacks execute reliably when `res.end()` is called.
gotcha The `onEnd` callback is executed *after* `res.end()` has been called. Attempting to modify headers or the status code within this callback will have no effect on the client response, as headers would have already been sent.
Fix: Ensure all modifications to `res.statusCode` and `res.setHeader()` occur *before* `res.end()` is invoked. The `onEnd` callback is for *observing* the final response, not modifying it.
gotcha Capturing the entire response body in memory, especially for very large responses, can lead to significant memory consumption. This can be a concern for high-traffic servers or services handling multi-megabyte payloads.
Fix: For applications dealing with potentially very large responses, consider alternative streaming approaches or ensure proper resource management and scaling strategies if using `on-http-end`.
gotcha While `on-http-end` works directly with Node.js's native `http` module, its integration with higher-level web frameworks (e.g., Express, Koa, Fastify) might require careful attention. These frameworks often wrap or modify the `res.end()` method, which could impact when or how `on-http-end` intercepts the response.
Fix: Test `on-http-end` thoroughly within your chosen framework. Ensure it's registered early in the middleware chain to properly capture the response before framework-specific `res.end()` modifications take effect.

Install

npm install on-http-end npm
yarn add on-http-end yarn
pnpm add on-http-end pnpm

Imports

onEnd
wrong:
```
import onEnd from 'on-http-end'
```
correct:
```
const onEnd = require('on-http-end')
```
The package primarily uses CommonJS `require()` syntax as shown in its documentation. For modern Node.js environments configured for ESM, use the `import` statement.

Quickstart

Demonstrates how to integrate `on-http-end` with a basic Node.js HTTP server to capture response details.

const onEnd = require('on-http-end')
const http = require('http')

const server = http.createServer((req, res) => {
  onEnd(res, (payload) => {
    // The payload object contains status, headers, data, and encoding
    console.log('Captured Response Payload:', payload)
    // Example: Log only the data
    // console.log('Response data:', payload.data)
  })

  res.setHeader('x-custom-header', 'captured-value')
  res.statusCode = 201;
  res.end('Hello, on-http-end user!', 'utf-8')
})

server.listen(3000, () => {
  console.log('Server listening on http://localhost:3000')
  console.log('Try visiting http://localhost:3000 in your browser.')
})

view raw JSON →