Clone HTTP Response Stream

2.0.0 · active · verified Tue Apr 21

The `clone-response` package provides a utility function to duplicate a Node.js HTTP response stream, effectively creating an unconsumed copy. This is particularly useful in scenarios where a response stream needs to be processed in multiple asynchronous contexts or passed to different consumers without fully draining the original stream for all parties. The package ensures that all properties and methods from the original `IncomingMessage` are copied to the new stream, creating a complete duplicate. As of version 2.0.0, it is a pure ESM module and requires Node.js 14 or higher. The package maintains a stable release cadence, primarily updating for Node.js compatibility and modern JavaScript module standards. Its core differentiator is the reliable duplication of a response stream's state and data, enabling flexible handling of HTTP responses without complex stream buffering or re-fetching.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES Module [path/to/node_modules/clone-response/index.js] from [your_file.js] not supported.
```
cause `clone-response` is an ES Module, but you are trying to import it using CommonJS `require()` syntax.

fix Change your import statement from `const cloneResponse = require('clone-response');` to `import cloneResponse from 'clone-response';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: cloneResponse is not a function
```
cause You might be attempting to import `cloneResponse` as a named export (`import { cloneResponse } from 'clone-response';`) when it is the default export.

fix Use the correct default import syntax: `import cloneResponse from 'clone-response';`.
```
Error: The 'http' module cannot be used in 'esm' context with 'require()'.
```
cause While `clone-response` is ESM, you might be mixing CommonJS `require()` for built-in Node.js modules like `http` within an ESM file.

fix Update `const http = require('http');` to `import http from 'node:http';` to consistently use ESM import syntax with `node:` protocol for built-in modules.

Warnings

breaking `clone-response` is now a pure ESM (ECMAScript Module). CommonJS `require()` is no longer supported.
Fix: Migrate your project to ESM using `import` statements or use an older version of the package if CommonJS is strictly required. Ensure your `package.json` has `"type": "module"` or use `.mjs` file extensions.
breaking Node.js 14.16 or higher is now required. Older Node.js versions are not supported.
Fix: Upgrade your Node.js runtime to version 14.16 or newer. If unable to upgrade, you must use `clone-response` version 1.x.x.
gotcha The process of cloning a stream itself consumes the original stream in that immediate tick. While multiple clones can be made in the same tick, passing the original stream into any asynchronous callbacks after cloning will result in it being already consumed.
Fix: Be mindful of stream consumption order. Clone the stream as early as possible. If you need to use the original stream in an async context, ensure you create a clone *before* any operations that might consume it asynchronously.

Install

npm install clone-response npm
yarn add clone-response yarn
pnpm add clone-response pnpm

Imports

cloneResponse
wrong:
```
const cloneResponse = require('clone-response');
```
correct:
```
import cloneResponse from 'clone-response';
```
Since version 2.0.0, `clone-response` is a pure ESM module and must be imported using `import` syntax. Attempting to `require()` it will result in a runtime error.
cloneResponse (named import attempt)
wrong:
```
import { cloneResponse } from 'clone-response';
```
correct:
```
import cloneResponse from 'clone-response';
```
`cloneResponse` is exported as the default export of the module. Using a named import will result in `undefined` or a module not found error depending on the environment.
http (Node.js built-in)
wrong:
```
const http = require('http');
```
correct:
```
import http from 'node:http';
```
In ESM contexts, it is best practice to use the `node:` protocol prefix for built-in Node.js modules like `http` to prevent naming collisions and enhance clarity.

Quickstart

This example demonstrates how to clone an HTTP response stream immediately after receiving it, allowing the original to be piped to `process.stdout` while the cloned stream remains available for later asynchronous consumption.

import http from 'node:http';
import cloneResponse from 'clone-response';

http.get('http://example.com', response => {
	const clonedResponse = cloneResponse(response);
	response.pipe(process.stdout);

	setImmediate(() => {
		// The response stream has already been consumed by the time this executes,
		// however the cloned response stream is still available.
		// In a real application, you would consume clonedResponse here.
		console.log('Cloned response is still available for consumption.');
		// Example: clonedResponse.on('data', chunk => console.log('Cloned data:', chunk.toString()));
	});
});

view raw JSON →