HTTP Stream Decompression

2.1.0 · maintenance · verified Tue Apr 21

Inflation is a focused utility that automatically decompresses HTTP streams using Node.js's built-in zlib module. It supports common compression algorithms like gzip, deflate, and brotli. Currently at version 2.1.0, the package demonstrates a stable, low-maintenance release cadence, with its last publish two years ago. It's widely adopted, with over 1.5 million dependents, indicating its reliability for its specific function. Its key differentiator is its simplicity and direct integration with Node.js streams for handling `Content-Encoding` headers, aiming to simplify the process of consuming compressed HTTP request bodies or responses without needing to manually detect the compression type. While robust for its core purpose, users should be aware of specific Node.js version requirements, especially for Brotli support.

Common errors

```
Error: Brotli: invalid result
```
cause Attempting to decompress a Brotli stream on a Node.js version older than v11.7.0.

fix Upgrade your Node.js runtime to v11.7.0 or newer to support Brotli decompression.
```
TypeError: Cannot read properties of undefined (reading 'content-encoding')
```
cause The `inflation` function tried to access `stream.headers['content-encoding']` because no `encoding` option was provided, but the input `stream` object did not have a `headers` property.

fix Pass the `encoding` option explicitly: `inflate(myStream, { encoding: 'gzip' })` or ensure the `stream` object has a `headers` property containing `content-encoding`.
```
ERR_REQUIRE_ESM: require() of ES Module ... from ... not supported.
```
cause Trying to `require()` an ES Module or using `import` for a CJS module without proper setup in an ESM context.

fix Use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const inflate = require('inflation');` for ESM projects to import this CJS-only package.

Warnings

gotcha Brotli decompression, while listed as an option, requires Node.js v11.7.0 or newer. The `engines` field in `package.json` (`>= 0.8.0`) is misleading for Brotli compatibility, as versions between 0.8.0 and 11.6.x do not support Brotli natively. Attempting to decompress Brotli streams on older Node.js versions will result in runtime errors.
Fix: Ensure your Node.js runtime is v11.7.0 or higher if Brotli decompression is required. For older Node.js versions, only gzip and deflate are reliably supported.
gotcha The `inflation` package is a CommonJS (CJS) module. Direct `import` statements in ES Module (ESM) contexts will fail unless a compatibility layer like `import { createRequire } from 'module'` is used.
Fix: For ESM projects, use `import { createRequire } from 'module'; const require = createRequire(import.meta.url); const inflate = require('inflation');` or configure your build system to transpile CJS modules.
gotcha If the `encoding` option is not explicitly provided, `inflation` attempts to read `stream.headers['content-encoding']`. If the input `stream` does not have a `headers` property (e.g., it's a generic Readable stream, not an `http.IncomingMessage`), decompression may not occur as expected or could lead to errors.
Fix: Always explicitly pass the `encoding` option to `inflate(stream, { encoding: 'gzip' })` if the input stream is not an `http.IncomingMessage` or similar object with a `headers` property.

Install

npm install inflation npm
yarn add inflation yarn
pnpm add inflation pnpm

Imports

inflate
wrong:
```
import inflate from 'inflation'
```
correct:
```
const inflate = require('inflation')
```
This package is CommonJS (CJS) only. For use in an ESM module, you must use `import { createRequire } from 'module'; const require = createRequire(import.meta.url);` before requiring the package.

inflate

import { createRequire } from 'module';
const require = createRequire(import.meta.url);
const inflate = require('inflation');

This is the correct pattern for importing 'inflation' (a CJS module) into an ES Module (ESM) context in Node.js.

inflate
```
const inflate = require('inflation');
```
When using TypeScript with CommonJS, `require('inflation')` is the standard way. If `esModuleInterop` is enabled, `import inflate from 'inflation'` might work, but the explicit `require` is more robust for CJS-only libraries.

Quickstart

This quickstart sets up a basic HTTP server that listens for incoming requests. It uses `inflation` to automatically decompress the request body based on the `Content-Encoding` header, then reads the raw content and logs it to the console. This demonstrates how to integrate `inflation` into an HTTP request processing pipeline for handling compressed data. Note that `raw-body` is used here for convenience in reading the stream, but is not a dependency of `inflation` itself.

const inflate = require('inflation');
const raw = require('raw-body');
const http = require('http');

// Minimal HTTP server demonstrating stream decompression
http.createServer(function (req, res) {
  // Assume 'raw-body' is installed for this example: npm i raw-body
  // For simplicity, we are not handling response ending or error cases robustly.
  // In a real application, proper error handling and response management are crucial.
  raw(inflate(req), 'utf-8', function (err, string) {
    if (err) {
      console.error('Error reading inflated body:', err);
      res.statusCode = 500;
      res.end('Error processing request body');
      return;
    }
    console.log('Received inflated body:', string);
    res.statusCode = 200;
    res.setHeader('Content-Type', 'text/plain');
    res.end(`Processed body length: ${string.length}`);
  });
}).listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
  console.log('Send a compressed POST request to test (e.g., with Content-Encoding: gzip)');
});

view raw JSON →