CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-compression

Node.js compression middleware providing gzip, deflate, and brotli compression for HTTP responses

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Compression

Compression is a Node.js middleware that provides HTTP response compression for Express.js and other Connect-compatible frameworks. It automatically compresses response bodies using gzip, deflate, or brotli algorithms, improving bandwidth utilization and response times while maintaining compatibility with HTTP standards.

Package Information

  • Package Name: compression
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install compression

Core Imports

const compression = require('compression');

Basic Usage

const compression = require('compression');
const express = require('express');

const app = express();

// Enable compression for all responses
app.use(compression());

// Add routes
app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(3000);

Architecture

The compression middleware operates by:

  • Content Negotiation: Examines client Accept-Encoding headers to determine supported compression algorithms
  • Response Filtering: Uses configurable filter functions to determine which responses should be compressed
  • Stream-based Compression: Creates compression streams (gzip, deflate, or brotli) that process response data in chunks
  • Header Management: Automatically sets appropriate Content-Encoding and Vary headers
  • Threshold Control: Only compresses responses above a configurable size threshold
  • Back-pressure Support: Handles stream back-pressure for optimal memory usage

Capabilities

Main Compression Middleware

Creates compression middleware with configurable options for automatic HTTP response compression.

/**
 * Creates compression middleware for HTTP responses
 * @param {Object} [options] - Configuration options
 * @returns {Function} Express middleware function
 */
function compression(options);

Options Configuration:

interface CompressionOptions {
  /** Custom filter function to determine compression eligibility */
  filter?: (req, res) => boolean;
  /** Minimum response size for compression (default: 1024 bytes) */
  threshold?: number | string;
  /** Default encoding when client doesn't specify (default: 'identity') */
  enforceEncoding?: 'gzip' | 'deflate' | 'br' | 'identity';
  /** Compression level 0-9 (default: -1) */
  level?: number;
  /** Buffer chunk size for compression (default: 16384) */
  chunkSize?: number;
  /** Window bits parameter (default: 15) */
  windowBits?: number;
  /** Memory level 1-9 (default: 8) */
  memLevel?: number;
  /** Compression strategy constant */
  strategy?: number;
  /** Brotli-specific configuration options */
  brotli?: {
    params?: Object;
    [key: string]: any;
  };
  /** Additional zlib options passed through to compression streams */
  [key: string]: any;
}

Usage Examples:

// Basic usage with default options
app.use(compression());

// Custom threshold
app.use(compression({
  threshold: '2kb'
}));

// Custom filter function
app.use(compression({
  filter: (req, res) => {
    if (req.headers['x-no-compression']) {
      return false;
    }
    return compression.filter(req, res);
  }
}));

// Custom compression level
app.use(compression({
  level: 6,  // Balanced compression/speed
  threshold: 1024
}));

// Brotli configuration
app.use(compression({
  brotli: {
    params: {
      [require('zlib').constants.BROTLI_PARAM_QUALITY]: 6
    }
  }
}));

Default Filter Function

The default filter function used to determine if responses should be compressed based on Content-Type.

/**
 * Default filter function for determining compression eligibility
 * @param {Object} req - HTTP request object
 * @param {Object} res - HTTP response object
 * @returns {boolean} True if response should be compressed
 */
compression.filter(req, res);

Usage Example:

// Extend the default filter
function shouldCompress(req, res) {
  if (req.headers['x-no-compression']) {
    // Don't compress responses with this request header
    return false;
  }
  
  // Fallback to standard filter function
  return compression.filter(req, res);
}

app.use(compression({ filter: shouldCompress }));

Response Flush Method

The middleware adds a flush method to response objects for forcing partially-compressed data to be sent to clients.

/**
 * Forces partially-compressed response to be flushed to client
 * Added to response object by compression middleware
 */
res.flush();

Usage Example (Server-Sent Events):

app.use(compression());

app.get('/events', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');

  // Send periodic data
  const timer = setInterval(() => {
    res.write('data: ping\\n\\n');
    
    // Force flush to ensure data reaches client immediately
    res.flush();
  }, 2000);

  res.on('close', () => {
    clearInterval(timer);
  });
});

Compression Algorithms

The middleware supports multiple compression algorithms with automatic negotiation:

  • gzip: Widely supported, good compression ratio
  • deflate: Universal support, slightly less efficient than gzip
  • brotli: Modern algorithm with better compression (Node.js v10.16.0+ and v11.7.0+)
  • identity: No compression (passthrough)

The middleware automatically selects the best algorithm based on:

  1. Client Accept-Encoding header preferences
  2. Server-configured algorithm priorities
  3. Node.js version capabilities (for brotli support)

Behavior and Limitations

Automatic Compression Triggers

Responses are compressed when:

  • Content-Type is compressible (determined by the compressible package)
  • Response size meets or exceeds the threshold (default: 1KB)
  • Client accepts compression via Accept-Encoding header
  • Response doesn't have Cache-Control: no-transform directive
  • Response isn't already encoded (no existing Content-Encoding header)

Automatic Skipping Scenarios

Compression is skipped for:

  • HEAD requests
  • Responses already with Content-Encoding set
  • Responses below the size threshold
  • Content types deemed non-compressible
  • Responses with Cache-Control: no-transform header
  • Clients not accepting any supported compression algorithms

Headers Modified

The middleware automatically manages these headers:

  • Content-Encoding: Set to the chosen compression algorithm
  • Content-Length: Removed (replaced with chunked transfer encoding)
  • Vary: Set to "Accept-Encoding" for proper caching behavior

Error Handling

The compression middleware follows Express.js conventions:

  • Compatible with standard Express error handling middleware
  • Stream errors are handled internally without crashing the application
  • Respects existing error handling patterns in your application
  • Calls next() to continue to the next middleware

Performance Considerations

  • Memory Usage: Configurable via memLevel and chunkSize options
  • CPU vs Bandwidth Trade-off: Adjustable via level option (0-9)
  • Streaming: Processes data in chunks, suitable for large responses
  • Back-pressure: Automatically handles client connection speed variations
  • Threshold: Avoids compression overhead for small responses

Integration Patterns

Express.js Applications

const express = require('express');
const compression = require('compression');

const app = express();

// Apply compression before other middleware
app.use(compression());
app.use(express.static('public'));
app.use(express.json());

Raw HTTP Server

const http = require('http');
const compression = require('compression')({ threshold: 0 });

const server = http.createServer((req, res) => {
  compression(req, res, (err) => {
    if (err) {
      res.statusCode = err.status || 500;
      res.end(err.message);
      return;
    }
    
    // Your application logic
    res.setHeader('Content-Type', 'text/plain');
    res.end('Hello World!');
  });
});

Connect-compatible Frameworks

The middleware works with any Connect-compatible framework:

const connect = require('connect');
const compression = require('compression');

const app = connect();
app.use(compression());
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/compression@1.8.x
Publish Source
CLI
Badge
tessl/npm-compression badge