Node.js zlib Module Guide

The zlib module provides compression and decompression using gzip, deflate, and brotli algorithms. Here's how to use it effectively.

Basic Compression#

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

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

// Compress string
async function compressString(input) {
  const buffer = Buffer.from(input);
  const compressed = await gzip(buffer);

  console.log(`Original: ${buffer.length} bytes`);
  console.log(`Compressed: ${compressed.length} bytes`);
  console.log(`Ratio: ${((1 - compressed.length / buffer.length) * 100).toFixed(1)}%`);

  return compressed;
}

// Decompress
async function decompressBuffer(compressed) {
  const decompressed = await gunzip(compressed);
  return decompressed.toString();
}

// Usage
const text = 'Hello World! '.repeat(1000);
const compressed = await compressString(text);
const decompressed = await decompressBuffer(compressed);
console.log(text === decompressed); // true

Stream Compression#

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

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

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

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

Compression Options#

import zlib from 'node:zlib';

// Gzip with options
const gzip = zlib.createGzip({
  level: zlib.constants.Z_BEST_COMPRESSION, // 0-9, default 6
  memLevel: 8,       // 1-9, default 8
  strategy: zlib.constants.Z_DEFAULT_STRATEGY,
  chunkSize: 16 * 1024, // Default 16KB
});

// Compression levels
const levels = {
  none: zlib.constants.Z_NO_COMPRESSION,       // 0
  fast: zlib.constants.Z_BEST_SPEED,           // 1
  default: zlib.constants.Z_DEFAULT_COMPRESSION, // 6
  best: zlib.constants.Z_BEST_COMPRESSION,     // 9
};

// Strategy options
const strategies = {
  default: zlib.constants.Z_DEFAULT_STRATEGY,
  filtered: zlib.constants.Z_FILTERED,
  huffmanOnly: zlib.constants.Z_HUFFMAN_ONLY,
  rle: zlib.constants.Z_RLE,
  fixed: zlib.constants.Z_FIXED,
};

Deflate/Inflate#

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

const deflate = promisify(zlib.deflate);
const inflate = promisify(zlib.inflate);
const deflateRaw = promisify(zlib.deflateRaw);
const inflateRaw = promisify(zlib.inflateRaw);

// Deflate (with zlib header)
async function deflateData(data) {
  return await deflate(Buffer.from(data));
}

async function inflateData(compressed) {
  return (await inflate(compressed)).toString();
}

// Raw deflate (no header)
async function deflateRawData(data) {
  return await deflateRaw(Buffer.from(data));
}

async function inflateRawData(compressed) {
  return (await inflateRaw(compressed)).toString();
}

// Usage
const original = 'Hello, World!';
const deflated = await deflateData(original);
const inflated = await inflateData(deflated);
console.log(inflated); // 'Hello, World!'

Brotli Compression#

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

const brotliCompress = promisify(zlib.brotliCompress);
const brotliDecompress = promisify(zlib.brotliDecompress);

// Compress with Brotli
async function compressBrotli(data) {
  return await brotliCompress(Buffer.from(data), {
    params: {
      [zlib.constants.BROTLI_PARAM_QUALITY]: 11, // 0-11, default 11
      [zlib.constants.BROTLI_PARAM_SIZE_HINT]: data.length,
    },
  });
}

// Decompress
async function decompressBrotli(compressed) {
  return (await brotliDecompress(compressed)).toString();
}

// Stream compression
async function compressFileBrotli(input, output) {
  await pipeline(
    fs.createReadStream(input),
    zlib.createBrotliCompress({
      params: {
        [zlib.constants.BROTLI_PARAM_QUALITY]: 6,
      },
    }),
    fs.createWriteStream(output)
  );
}

HTTP Compression#

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

const server = http.createServer((req, res) => {
  const acceptEncoding = req.headers['accept-encoding'] || '';
  const body = 'Hello World! '.repeat(1000);

  // Check supported encodings
  if (/\bbr\b/.test(acceptEncoding)) {
    res.writeHead(200, {
      'Content-Encoding': 'br',
      'Content-Type': 'text/plain',
    });
    zlib.brotliCompress(body, (err, result) => {
      res.end(result);
    });
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    res.writeHead(200, {
      'Content-Encoding': 'gzip',
      'Content-Type': 'text/plain',
    });
    zlib.gzip(body, (err, result) => {
      res.end(result);
    });
  } else if (/\bdeflate\b/.test(acceptEncoding)) {
    res.writeHead(200, {
      'Content-Encoding': 'deflate',
      'Content-Type': 'text/plain',
    });
    zlib.deflate(body, (err, result) => {
      res.end(result);
    });
  } else {
    res.writeHead(200, {
      'Content-Type': 'text/plain',
    });
    res.end(body);
  }
});

server.listen(3000);

Streaming with Transform#

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

// Custom transform before compression
class UppercaseTransform extends Transform {
  _transform(chunk, encoding, callback) {
    this.push(chunk.toString().toUpperCase());
    callback();
  }
}

// Pipeline: read -> transform -> compress -> write
async function processAndCompress(input, output) {
  await pipeline(
    fs.createReadStream(input),
    new UppercaseTransform(),
    zlib.createGzip(),
    fs.createWriteStream(output)
  );
}

// Pipeline: read -> decompress -> transform -> write
async function decompressAndProcess(input, output) {
  await pipeline(
    fs.createReadStream(input),
    zlib.createGunzip(),
    new UppercaseTransform(),
    fs.createWriteStream(output)
  );
}

Memory-Efficient Processing#

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

// Process large files in chunks
function compressLargeFile(inputPath, outputPath) {
  return new Promise((resolve, reject) => {
    const input = fs.createReadStream(inputPath);
    const output = fs.createWriteStream(outputPath);
    const gzip = zlib.createGzip();

    let bytesRead = 0;
    let bytesWritten = 0;

    input.on('data', (chunk) => {
      bytesRead += chunk.length;
    });

    gzip.on('data', (chunk) => {
      bytesWritten += chunk.length;
    });

    output.on('finish', () => {
      console.log(`Read: ${bytesRead} bytes`);
      console.log(`Written: ${bytesWritten} bytes`);
      console.log(`Compression ratio: ${((1 - bytesWritten / bytesRead) * 100).toFixed(1)}%`);
      resolve();
    });

    input.pipe(gzip).pipe(output);
    input.on('error', reject);
    gzip.on('error', reject);
    output.on('error', reject);
  });
}

Flush Control#

import zlib from 'node:zlib';

const gzip = zlib.createGzip();

// Manual flush for streaming protocols
function sendChunk(data) {
  gzip.write(data);
  gzip.flush(zlib.constants.Z_SYNC_FLUSH); // Flush immediately
}

// Flush types
const flushTypes = {
  noFlush: zlib.constants.Z_NO_FLUSH,
  partialFlush: zlib.constants.Z_PARTIAL_FLUSH,
  syncFlush: zlib.constants.Z_SYNC_FLUSH,
  fullFlush: zlib.constants.Z_FULL_FLUSH,
  finish: zlib.constants.Z_FINISH,
  block: zlib.constants.Z_BLOCK,
  trees: zlib.constants.Z_TREES,
};

Compare Algorithms#

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

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

async function compareAlgorithms(data) {
  const buffer = Buffer.from(data);
  const results = [];

  // Gzip
  const gzipStart = Date.now();
  const gzipped = await gzip(buffer);
  results.push({
    algorithm: 'gzip',
    size: gzipped.length,
    time: Date.now() - gzipStart,
  });

  // Deflate
  const deflateStart = Date.now();
  const deflated = await deflate(buffer);
  results.push({
    algorithm: 'deflate',
    size: deflated.length,
    time: Date.now() - deflateStart,
  });

  // Brotli
  const brotliStart = Date.now();
  const brotlied = await brotliCompress(buffer);
  results.push({
    algorithm: 'brotli',
    size: brotlied.length,
    time: Date.now() - brotliStart,
  });

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

  return results;
}

// Test
const testData = 'Hello World! '.repeat(10000);
await compareAlgorithms(testData);

Best Practices#

Algorithm Selection:
✓ gzip - widely supported, good balance
✓ brotli - better compression, modern browsers
✓ deflate - fast, less overhead
✓ Match client Accept-Encoding

Performance:
✓ Use streams for large files
✓ Choose appropriate compression level
✓ Consider brotli for static assets
✓ Cache compressed versions

Options:
✓ Level 6 for general use
✓ Level 9 for max compression
✓ Level 1-3 for speed priority
✓ Use flush for streaming

Avoid:
✗ Compressing already compressed data
✗ Sync operations on large data
✗ Ignoring errors
✗ Over-compressing small payloads

The zlib module provides comprehensive compression support through gzip, deflate, and brotli algorithms. Use streams for large files, choose appropriate compression levels based on your speed/size tradeoffs, and implement HTTP compression for web servers. Brotli offers better compression ratios but is slower; gzip provides a good balance and universal support. Always use the promisified versions or streams for async operations to avoid blocking the event loop.