Node.js zlib Compression Guide

The zlib module provides compression and decompression using Gzip, Deflate, and Brotli algorithms. Here's how to use it.

Basic Compression#

import zlib from 'node:zlib';
import { promisify } from 'node:util';

// Promisified versions
const gzip = promisify(zlib.gzip);
const gunzip = promisify(zlib.gunzip);
const deflate = promisify(zlib.deflate);
const inflate = promisify(zlib.inflate);
const brotliCompress = promisify(zlib.brotliCompress);
const brotliDecompress = promisify(zlib.brotliDecompress);

// Gzip compression
async function compressGzip(data) {
  const compressed = await gzip(data);
  console.log(`Original: ${data.length}, Compressed: ${compressed.length}`);
  return compressed;
}

// Gzip decompression
async function decompressGzip(compressed) {
  const decompressed = await gunzip(compressed);
  return decompressed.toString();
}

// Usage
const text = 'Hello, World!'.repeat(100);
const compressed = await compressGzip(text);
const decompressed = await decompressGzip(compressed);

Stream-Based Compression#

import zlib from 'node:zlib';
import fs from 'node:fs';
import { pipeline } from 'node:stream/promises';

// Compress file with streams
async function compressFile(input, output) {
  await pipeline(
    fs.createReadStream(input),
    zlib.createGzip(),
    fs.createWriteStream(output)
  );
  console.log(`Compressed ${input} to ${output}`);
}

// Decompress file with streams
async function decompressFile(input, output) {
  await pipeline(
    fs.createReadStream(input),
    zlib.createGunzip(),
    fs.createWriteStream(output)
  );
  console.log(`Decompressed ${input} to ${output}`);
}

// Usage
await compressFile('data.txt', 'data.txt.gz');
await decompressFile('data.txt.gz', 'data-restored.txt');

HTTP Compression#

import http from 'node:http';
import zlib from 'node:zlib';
import fs from 'node:fs';

const server = http.createServer((req, res) => {
  const acceptEncoding = req.headers['accept-encoding'] || '';

  const raw = fs.createReadStream('large-file.html');

  // Check supported encodings
  if (acceptEncoding.includes('br')) {
    res.setHeader('Content-Encoding', 'br');
    raw.pipe(zlib.createBrotliCompress()).pipe(res);
  } else if (acceptEncoding.includes('gzip')) {
    res.setHeader('Content-Encoding', 'gzip');
    raw.pipe(zlib.createGzip()).pipe(res);
  } else if (acceptEncoding.includes('deflate')) {
    res.setHeader('Content-Encoding', 'deflate');
    raw.pipe(zlib.createDeflate()).pipe(res);
  } else {
    raw.pipe(res);
  }
});

server.listen(3000);

Compression Options#

import zlib from 'node:zlib';

// Gzip with options
const gzipOptions = {
  level: 9, // 0-9, higher = better compression, slower
  memLevel: 8, // 1-9, memory usage
  strategy: zlib.constants.Z_DEFAULT_STRATEGY,
};

const gzipStream = zlib.createGzip(gzipOptions);

// Brotli with options
const brotliOptions = {
  params: {
    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
    [zlib.constants.BROTLI_PARAM_QUALITY]: 11, // 0-11
    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: 1000000,
  },
};

const brotliStream = zlib.createBrotliCompress(brotliOptions);

// Deflate with options
const deflateOptions = {
  level: zlib.constants.Z_BEST_COMPRESSION,
  windowBits: 15,
};

const deflateStream = zlib.createDeflate(deflateOptions);

Comparing Algorithms#

import zlib from 'node:zlib';
import { promisify } from 'node:util';

const gzip = promisify(zlib.gzip);
const deflate = promisify(zlib.deflate);
const brotli = promisify(zlib.brotliCompress);

async function compareCompression(data) {
  const buffer = Buffer.from(data);

  console.log(`Original size: ${buffer.length} bytes`);

  // Gzip
  const gzipped = await gzip(buffer);
  console.log(`Gzip: ${gzipped.length} bytes (${ratio(buffer, gzipped)}%)`);

  // Deflate
  const deflated = await deflate(buffer);
  console.log(`Deflate: ${deflated.length} bytes (${ratio(buffer, deflated)}%)`);

  // Brotli
  const brotlied = await brotli(buffer);
  console.log(`Brotli: ${brotlied.length} bytes (${ratio(buffer, brotlied)}%)`);
}

function ratio(original, compressed) {
  return ((compressed.length / original.length) * 100).toFixed(2);
}

// Test with different data types
const text = 'Hello World '.repeat(10000);
const json = JSON.stringify(Array(1000).fill({ name: 'Test', value: 123 }));

await compareCompression(text);
await compareCompression(json);

Incremental Compression#

import zlib from 'node:zlib';

// Compress data incrementally
class IncrementalCompressor {
  constructor(algorithm = 'gzip') {
    this.chunks = [];

    switch (algorithm) {
      case 'gzip':
        this.compressor = zlib.createGzip();
        break;
      case 'deflate':
        this.compressor = zlib.createDeflate();
        break;
      case 'brotli':
        this.compressor = zlib.createBrotliCompress();
        break;
    }

    this.compressor.on('data', (chunk) => {
      this.chunks.push(chunk);
    });
  }

  write(data) {
    this.compressor.write(data);
  }

  end() {
    return new Promise((resolve) => {
      this.compressor.on('end', () => {
        resolve(Buffer.concat(this.chunks));
      });
      this.compressor.end();
    });
  }
}

// Usage
const compressor = new IncrementalCompressor('gzip');
compressor.write('First chunk of data\n');
compressor.write('Second chunk of data\n');
compressor.write('Third chunk of data\n');
const result = await compressor.end();

Memory-Efficient Processing#

import zlib from 'node:zlib';
import { Transform } from 'node:stream';

// Process large data without loading into memory
class ChunkProcessor extends Transform {
  _transform(chunk, encoding, callback) {
    // Process each chunk
    const processed = chunk.toString().toUpperCase();
    callback(null, processed);
  }
}

async function processLargeFile(input, output) {
  await pipeline(
    fs.createReadStream(input),
    zlib.createGunzip(),
    new ChunkProcessor(),
    zlib.createGzip(),
    fs.createWriteStream(output)
  );
}

Compression Utilities#

import zlib from 'node:zlib';
import { promisify } from 'node:util';

// Utility class for compression
class Compressor {
  static async gzip(data, options = {}) {
    const gzip = promisify(zlib.gzip);
    return gzip(Buffer.from(data), options);
  }

  static async gunzip(data) {
    const gunzip = promisify(zlib.gunzip);
    return (await gunzip(data)).toString();
  }

  static async brotli(data, options = {}) {
    const compress = promisify(zlib.brotliCompress);
    return compress(Buffer.from(data), options);
  }

  static async unbrotli(data) {
    const decompress = promisify(zlib.brotliDecompress);
    return (await decompress(data)).toString();
  }

  static async compress(data, algorithm = 'gzip') {
    switch (algorithm) {
      case 'gzip':
        return this.gzip(data);
      case 'brotli':
        return this.brotli(data);
      default:
        throw new Error(`Unknown algorithm: ${algorithm}`);
    }
  }

  static async decompress(data, algorithm = 'gzip') {
    switch (algorithm) {
      case 'gzip':
        return this.gunzip(data);
      case 'brotli':
        return this.unbrotli(data);
      default:
        throw new Error(`Unknown algorithm: ${algorithm}`);
    }
  }
}

JSON Compression#

import zlib from 'node:zlib';
import { promisify } from 'node:util';

const gzip = promisify(zlib.gzip);
const gunzip = promisify(zlib.gunzip);

// Compress JSON for storage or transmission
async function compressJson(obj) {
  const json = JSON.stringify(obj);
  const compressed = await gzip(json);
  return compressed.toString('base64');
}

async function decompressJson(base64String) {
  const compressed = Buffer.from(base64String, 'base64');
  const decompressed = await gunzip(compressed);
  return JSON.parse(decompressed.toString());
}

// Usage
const data = {
  users: Array(1000).fill({ name: 'John', email: 'john@example.com' }),
};

const compressed = await compressJson(data);
console.log(`Compressed length: ${compressed.length}`);

const restored = await decompressJson(compressed);
console.log(`Restored ${restored.users.length} users`);

Error Handling#

import zlib from 'node:zlib';
import { pipeline } from 'node:stream/promises';

// Handle compression errors
async function safeCompress(input, output) {
  try {
    await pipeline(
      fs.createReadStream(input),
      zlib.createGzip(),
      fs.createWriteStream(output)
    );
    return { success: true };
  } catch (error) {
    if (error.code === 'ENOENT') {
      return { success: false, error: 'File not found' };
    }
    if (error.code === 'Z_DATA_ERROR') {
      return { success: false, error: 'Compression failed' };
    }
    throw error;
  }
}

// Validate compressed data
async function isValidGzip(buffer) {
  return new Promise((resolve) => {
    zlib.gunzip(buffer, (err) => {
      resolve(!err);
    });
  });
}

Express Middleware#

import express from 'express';
import zlib from 'node:zlib';

// Custom compression middleware
function compressionMiddleware(options = {}) {
  const threshold = options.threshold || 1024;

  return (req, res, next) => {
    const acceptEncoding = req.headers['accept-encoding'] || '';
    const originalSend = res.send.bind(res);

    res.send = (body) => {
      if (typeof body === 'string' && body.length > threshold) {
        if (acceptEncoding.includes('br')) {
          zlib.brotliCompress(body, (err, compressed) => {
            if (!err) {
              res.setHeader('Content-Encoding', 'br');
              res.setHeader('Content-Length', compressed.length);
              originalSend(compressed);
            } else {
              originalSend(body);
            }
          });
          return;
        }

        if (acceptEncoding.includes('gzip')) {
          zlib.gzip(body, (err, compressed) => {
            if (!err) {
              res.setHeader('Content-Encoding', 'gzip');
              res.setHeader('Content-Length', compressed.length);
              originalSend(compressed);
            } else {
              originalSend(body);
            }
          });
          return;
        }
      }

      originalSend(body);
    };

    next();
  };
}

const app = express();
app.use(compressionMiddleware({ threshold: 1024 }));

Best Practices#

Algorithm Choice:
✓ Brotli for static assets (best ratio)
✓ Gzip for dynamic content (fast)
✓ Deflate for legacy support
✓ Match client Accept-Encoding

Performance:
✓ Use streams for large files
✓ Set appropriate compression level
✓ Cache compressed assets
✓ Set minimum size threshold

Implementation:
✓ Handle errors properly
✓ Validate before decompressing
✓ Use pipeline for streams
✓ Promisify callback APIs

Avoid:
✗ Compressing already compressed data
✗ High compression for real-time
✗ Ignoring Content-Encoding header
✗ Memory issues with large buffers

The zlib module provides efficient compression for Node.js applications. Use Brotli for best compression ratios on static assets, Gzip for dynamic content, and streams for large files. Always check Accept-Encoding headers in HTTP responses and handle errors appropriately. Set compression thresholds to avoid overhead on small responses.