Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท crypto

Node.js zlib options explained

Guide to the options shared by Node.js zlib methods and streams: level, memLevel, strategy, windowBits, chunkSize, flush modes, info and maxOutputLength.

Every zlib function and stream in Node.js (gzip, deflate, inflate and their raw and sync forms) accepts the same options object as its second argument. Most options only matter in special cases, but a few decide how fast, how small and how safe your compression is. This page explains each one and what it trades off.

The Brotli and Zstandard classes use a params object instead of level and windowBits; the options that apply to all classes (chunkSize, flush, finishFlush, maxOutputLength) work the same way. The numeric constants all live in zlib.constants.

NODE
import { gzipSync, constants } from 'node:zlib';

const out = gzipSync('data', { level: constants.Z_BEST_SPEED, chunkSize: 64 * 1024 });

Try it

Node.js Level and strategy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js chunkSize, flush and info

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The options

Option Applies to Default Meaning
level compress Z_DEFAULT_COMPRESSION (-1, same as 6) 0 stores without compression, 1 is fastest, 9 is smallest.
memLevel compress 8 Internal memory, 1 to 9. More memory gives slightly better speed and ratio.
strategy compress Z_DEFAULT_STRATEGY Z_FILTERED (data with small differences, like image rows), Z_HUFFMAN_ONLY (no string matching), Z_RLE (run-length matches only), Z_FIXED (fixed Huffman codes).
windowBits both 15 Log2 of the history window. A smaller window uses less memory and compresses worse. The decompressor must use at least the compressor's size.
dictionary deflate, inflate none A preset dictionary; see zlib.deflate() and inflate().
chunkSize all 16384 Size of the buffers the engine fills. Minimum 64 bytes.
flush all Z_NO_FLUSH Flush mode applied to every write.
finishFlush all Z_FINISH Flush mode used when the stream ends.
maxOutputLength buffer helpers Infinity Largest allowed result in bytes.
info buffer helpers false Return { buffer, engine } instead of just the buffer.

Flush modes

The flush constants say what the engine must do with data it is holding.

  • Z_NO_FLUSH: collect more input before producing output (best ratio).
  • Z_PARTIAL_FLUSH: legacy mode, rarely useful.
  • Z_SYNC_FLUSH: emit everything so far, aligned to a byte boundary, so a decoder can read it. The stream stays open. Use it for live message streams.
  • Z_FULL_FLUSH: like sync, but also resets the history, allowing a decoder to start from here. Costs more ratio.
  • Z_FINISH: end the stream and write the trailer.
  • Z_BLOCK: flush at the next deflate block boundary.

Usage notes

  • The default level is a good choice for almost every case. Level 9 can cost several times the CPU of level 6 for a few percent gain.
  • Raising chunkSize to 64 KiB or more reduces overhead for large data. Lowering it has little benefit.
  • finishFlush: Z_SYNC_FLUSH on a decompressor accepts a truncated stream and returns what it could decode, which is useful for logs still being written, but hides real corruption.
  • Use windowBits of 9 or more; the smallest window sizes have historically been unreliable in zlib.
  • Invalid values throw ERR_OUT_OF_RANGE or ERR_INVALID_ARG_TYPE when the object is created.
  • maxOutputLength is covered in Decompression bombs.