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.
import { gzipSync, constants } from 'node:zlib'; const out = gzipSync('data', { level: constants.Z_BEST_SPEED, chunkSize: 64 * 1024 });
Try it
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.
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
levelis a good choice for almost every case. Level 9 can cost several times the CPU of level 6 for a few percent gain. - Raising
chunkSizeto 64 KiB or more reduces overhead for large data. Lowering it has little benefit. finishFlush: Z_SYNC_FLUSHon 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
windowBitsof 9 or more; the smallest window sizes have historically been unreliable in zlib. - Invalid values throw
ERR_OUT_OF_RANGEorERR_INVALID_ARG_TYPEwhen the object is created. maxOutputLengthis covered in Decompression bombs.