Mimic Node.js HTTP Response Stream Properties

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/node_modules/mimic-response/index.js from /your/project/index.js not supported.

  cause Attempting to use `require()` to import `mimic-response` version 4.0.0 or higher in a CommonJS module.
  fix Refactor your consuming code to use `import` syntax within an ES module (by adding `"type": "module"` to `package.json` or using `.mjs` files), or use dynamic `import` like `const mimicResponse = (await import('mimic-response')).default;`.

• SyntaxError: Cannot use import statement outside a module

  cause Using `import` syntax for `mimic-response` v4.0.0+ in a Node.js file that is not treated as an ES module.
  fix Add `"type": "module"` to your `package.json` file, or rename your file to have a `.mjs` extension. Ensure your Node.js version is compatible (Node.js 12.20.0 or higher for v4.x).

• TypeError: Cannot read properties of undefined (reading 'statusCode') OR TypeError: mimicResponse is not a function

  cause Incorrectly attempting to import `mimicResponse` as a named export (e.g., `import { mimicResponse } from 'mimic-response';`) instead of a default export.
  fix Use the correct default import syntax: `import mimicResponse from 'mimic-response';`.

• TypeError: myStream.destroy is not a function (when calling myStream.destroy())

  cause Calling `destroy()` on a target stream (`myStream`) without it having a custom `destroy` method, specifically when you intend for the destroy call to be propagated to the source stream.
  fix Implement a `destroy` method in the constructor options of your target stream (e.g., `new PassThroughStream({ destroy(error, callback) { /* ... */ } })`) that also calls `from.destroy(error)` if propagation is desired.

Warnings

• breaking Version 4.0.0 of `mimic-response` is a pure ESM package. This means it can only be imported using `import` statements in ES modules, or dynamically with `await import()` in CommonJS. Direct `require()` calls are no longer supported.
  Fix: Migrate your project to use ES modules by adding `"type": "module"` to your `package.json` and using `import` statements, or ensure your consuming code is already an ES module. For existing CommonJS projects that cannot migrate, use `await import('mimic-response')` for dynamic loading.
• breaking Version 4.0.0 increased the minimum Node.js requirement to `^12.20.0 || ^14.13.1 || >=16.0.0`.
  Fix: Ensure your Node.js environment meets the minimum version requirement. Upgrade Node.js if necessary.
• breaking Version 3.0.0 increased the minimum Node.js requirement to Node.js 10.
  Fix: Ensure your Node.js environment is at least version 10.x. Upgrade Node.js if necessary, or downgrade `mimic-response` to a v2.x version if strict Node.js 8.x compatibility is required.
• breaking Version 2.0.0 increased the minimum Node.js requirement to Node.js 8.
  Fix: Ensure your Node.js environment is at least version 8.x. Upgrade Node.js if necessary, or use `mimic-response` v1.x for older Node.js compatibility.
• gotcha The `destroy(error)` function of the source stream (`from`) is not automatically proxied to the target stream (`to`). If you need to propagate destroy calls, you must manually implement the `destroy` method on your target stream and call `from.destroy(error)` within it.
  Fix: When creating your target stream, provide a `destroy` method in its constructor options that explicitly calls the `destroy` method of the `from` stream, as shown in the package's API documentation example.

Install

• npm install mimic-response npm
• yarn add mimic-response yarn
• pnpm add mimic-response pnpm

Imports

• mimicResponse
  wrong:

  const mimicResponse = require('mimic-response');

  correct:

  import mimicResponse from 'mimic-response';

  The `mimic-response` package is pure ESM since v4.0.0. CommonJS users must either migrate their project to ESM or use dynamic import with `await import('mimic-response')`.
• mimicResponse
  wrong:

  import { mimicResponse } from 'mimic-response';

  correct:

  import mimicResponse from 'mimic-response';

  `mimicResponse` is the default export of the package and should not be imported as a named export.
• mimicResponse (type)
  wrong:

  import type { mimicResponse } from 'mimic-response';

  correct:

  import type mimicResponse from 'mimic-response';

  The package includes TypeScript definitions. As `mimicResponse` is a default export, its type import should follow the default import syntax.

Quickstart

Demonstrates how to use `mimicResponse` to transfer HTTP response metadata like `statusCode` and `headers` from a source stream (simulated `IncomingMessage`) to a target `PassThroughStream`, and also illustrates the important `destroy` proxying caveat.

import { PassThrough as PassThroughStream } from 'node:stream';
import mimicResponse from 'mimic-response';

function getHttpResponseStream() {
  // Simulate an http.IncomingMessage with relevant properties
  const response = new PassThroughStream();
  Object.defineProperty(response, 'statusCode', { value: 200, configurable: true });
  Object.defineProperty(response, 'statusMessage', { value: 'OK', configurable: true });
  Object.defineProperty(response, 'headers', { value: { 'content-type': 'application/json' }, configurable: true });
  Object.defineProperty(response, 'rawHeaders', { value: ['Content-Type', 'application/json'], configurable: true });
  Object.defineProperty(response, 'trailers', { value: {}, configurable: true });
  Object.defineProperty(response, 'rawTrailers', { value: [], configurable: true });
  return response;
}

const responseStream = getHttpResponseStream();
const myStream = new PassThroughStream();

mimicResponse(responseStream, myStream);

console.log('Original status code:', responseStream.statusCode);
console.log('Mimicked status code:', myStream.statusCode);

// Demonstrating the 'destroy' caveat
const myStreamWithDestroy = new PassThroughStream({
  destroy(error, callback) {
    console.log('myStreamWithDestroy destroy called with error:', error ? error.message : 'none');
    responseStream.destroy(error); // Ensure the source stream's destroy is also called
    callback(error);
  }
});

mimicResponse(responseStream, myStreamWithDestroy);
// Simulate an error causing the stream to destroy
myStreamWithDestroy.destroy(new Error('Simulated stream error'));