HTTP Response Decompression Utility

Common errors

• ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/decompress-response/index.js

  cause Attempting to `require()` `decompress-response` in a CommonJS context after upgrading to version 8.0.0 or newer, which is a pure ESM package.
  fix Convert your consuming file or project to use ECMAScript Modules (ESM) syntax (`import decompressResponse from 'decompress-response';`) and ensure your `package.json` includes `"type": "module"` or your file uses a `.mjs` extension.

• TypeError: decompressResponse is not a function

  cause Incorrect import statement (e.g., `import { decompressResponse } from 'decompress-response';` instead of default import) or a TypeScript configuration mismatch, especially when transitioning between versions.
  fix Ensure you are using the correct default import: `import decompressResponse from 'decompress-response';`. For older TypeScript versions (5.x-7.x), check if the `import decompressResponse = require('decompress-response');` syntax is required by your specific setup.

• Error: stream.pipeline is not a function

  cause Using an older Node.js version (pre-Node.js 10) with `decompress-response` versions that rely on `stream.pipeline` (v5.0.0 and later).
  fix Upgrade your Node.js runtime to version 10 or newer. For `decompress-response` v10.x, Node.js 20 or newer is required.

Warnings

• breaking Version 10.0.0 requires Node.js 20 or newer. Users on older Node.js versions must remain on `decompress-response` v9.x or earlier.
  Fix: Upgrade your Node.js runtime to version 20 or later, or pin `decompress-response` to version `^9.0.0` or `<10`.
• breaking Version 9.0.0 requires Node.js 18 or newer. This continues the trend of aligning major releases with Node.js LTS versions.
  Fix: Upgrade your Node.js runtime to version 18 or later, or pin `decompress-response` to version `^8.0.0` or `<9`.
• breaking Version 8.0.0 converted the package to pure ECMAScript Module (ESM). CommonJS `require()` statements are no longer supported, leading to `ERR_REQUIRE_ESM` errors.
  Fix: Migrate your project to ESM by setting `"type": "module"` in your `package.json` or by using `.mjs` file extensions, and update all imports to use `import decompressResponse from 'decompress-response';`.
• breaking Version 8.0.0 increased the minimum Node.js requirement to 12.20.0.
  Fix: Upgrade your Node.js runtime to version 12.20.0 or later, or pin `decompress-response` to version `^7.0.0` or `<8`.
• breaking Version 7.0.0 removed the `content-encoding` header from the response. While primarily a TypeScript type change, if your application relied on inspecting this header after `decompressResponse` was applied, it would break.
  Fix: Adjust any logic that inspects the `content-encoding` header on the *returned* stream. The header should be checked on the *original* `response` object if needed.
• breaking Version 5.0.0 introduced a breaking change for TypeScript users, requiring a change from `import decompressResponse from 'decompress-response';` to `import decompressResponse = require('decompress-response');` due to a CommonJS-only export for the TypeScript definition. This was subsequently reverted by the pure ESM transition in v8.0.0.
  Fix: For versions 5.x to 7.x, adjust TypeScript imports. For v8.0.0 and above, revert to the standard `import` statement for ESM compatibility.
• gotcha In version 9.0.0, a fix was implemented to prevent `decompress-response` from incorrectly modifying the original response object. Prior versions might have unintended side effects if the original response was used elsewhere after being passed to the function.
  Fix: Upgrade to v9.0.0 or later to ensure the original `http.IncomingMessage` stream is not unintentionally modified. If on an older version, treat the original `response` object as potentially altered after calling `decompressResponse`.

Install

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

Imports

• decompressResponse
  wrong:

  const decompressResponse = require('decompress-response');

  correct:

  import decompressResponse from 'decompress-response';

  Package is pure ESM since v8.0.0. CommonJS `require()` syntax will not work. For TypeScript users on v5.x, the correct syntax was `import decompressResponse = require('decompress-response');`, but this was reverted by the ESM-only change in v8.x.
• http

  import http from 'node:http';

  The `node:` prefix is recommended for built-in Node.js modules for clarity and to avoid conflicts.
• zlib

  import zlib from 'node:zlib';

  Required if you need to manually compress data (e.g., for testing) before passing it to decompress-response. Use the `node:` prefix.

Quickstart

Demonstrates how to set up a basic Node.js server that sends a gzipped response, and then how a client can use `decompress-response` to automatically decompress and consume the HTTP stream.

import http from 'node:http';
import zlib from 'node:zlib';
import decompressResponse from 'decompress-response';

// Create a simple HTTP server to simulate a compressed response
const server = http.createServer((request, serverResponse) => {
  if (request.url === '/compressed-data') {
    serverResponse.writeHead(200, {
      'Content-Type': 'text/plain',
      'Content-Encoding': 'gzip' // Indicate gzipped content
    });
    // Compress the response body
    zlib.gzip('Hello from decompress-response! This is some example text to be decompressed.', (error, buffer) => {
      if (error) {
        console.error('Error gzipping:', error);
        serverResponse.end('Error gzipping content');
        return;
      }
      serverResponse.end(buffer);
    });
  } else {
    serverResponse.end('Not found');
  }
});

server.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');

  // Client-side usage: Fetch and decompress the response
  http.get('http://localhost:3000/compressed-data', response => {
    console.log('Original response headers:', response.headers);

    let decompressedResponse = decompressResponse(response);
    let data = '';

    decompressedResponse.on('data', chunk => {
      data += chunk.toString();
    });

    decompressedResponse.on('end', () => {
      console.log('Decompressed data:', data); // Should print 'Hello from decompress-response! ...'
      server.close(); // Clean up the server after the request
    });

    decompressedResponse.on('error', error => {
      console.error('Error during decompression:', error);
      server.close();
    });
  }).on('error', error => {
    console.error('HTTP GET request error:', error);
    server.close();
  });
});