Iterable Compression

The node:zlib/iter module provides compression and decompression transforms for use with the node:stream/iter iterable streams API.

This module is available only when the --experimental-stream-iter CLI flag is enabled.

Each algorithm has both an async variant (stateful async generator, for use with pull() and pipeTo()) and a sync variant (stateful sync generator, for use with pullSync() and pipeToSync()).

The async transforms run compression on the libuv threadpool, overlapping I/O with JavaScript execution. The sync transforms run compression directly on the main thread.

Note: The defaults for these transforms are tuned for streaming throughput, and differ from the defaults in node:zlib. In particular, gzip/deflate default to level 4 (not 6) and memLevel 9 (not 8), and Brotli defaults to quality 6 (not 11). These choices match common HTTP server configurations and provide significantly faster compression with only a small reduction in compression ratio. All defaults can be overridden via options.

import { from, pull, bytes, text } from 'node:stream/iter';
import { compressGzip, decompressGzip } from 'node:zlib/iter';

// Async round-trip
const compressed = await bytes(pull(from('hello'), compressGzip()));
const original = await text(pull(from(compressed), decompressGzip()));
console.log(original); // 'hello'

const { from, pull, bytes, text } = require('node:stream/iter');
const { compressGzip, decompressGzip } = require('node:zlib/iter');

async function run() {
  const compressed = await bytes(pull(from('hello'), compressGzip()));
  const original = await text(pull(from(compressed), decompressGzip()));
  console.log(original); // 'hello'
}

run().catch(console.error);

import { fromSync, pullSync, textSync } from 'node:stream/iter';
import { compressGzipSync, decompressGzipSync } from 'node:zlib/iter';

// Sync round-trip
const compressed = pullSync(fromSync('hello'), compressGzipSync());
const original = textSync(pullSync(compressed, decompressGzipSync()));
console.log(original); // 'hello'

const { fromSync, pullSync, textSync } = require('node:stream/iter');
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');

const compressed = pullSync(fromSync('hello'), compressGzipSync());
const original = textSync(pullSync(compressed, decompressGzipSync()));
console.log(original); // 'hello'

compressBrotli(options?): void

compressBrotliSync(options?): Object

Create a Brotli compression transform. Output is compatible with zlib.brotliDecompress() and decompressBrotli()/decompressBrotliSync().

compressDeflate(options?): void

compressDeflateSync(options?): Object

Create a deflate compression transform. Output is compatible with zlib.inflate() and decompressDeflate()/decompressDeflateSync().

compressGzip(options?): void

compressGzipSync(options?): Object

Create a gzip compression transform. Output is compatible with zlib.gunzip() and decompressGzip()/decompressGzipSync().

compressZstd(options?): void

compressZstdSync(options?): Object

Create a Zstandard compression transform. Output is compatible with zlib.zstdDecompress() and decompressZstd()/decompressZstdSync().

decompressBrotli(options?): void

decompressBrotliSync(options?): Object

Create a Brotli decompression transform.

decompressDeflate(options?): void

decompressDeflateSync(options?): Object

Create a deflate decompression transform.

decompressGzip(options?): void

decompressGzipSync(options?): Object

Create a gzip decompression transform.

decompressZstd(options?): void

decompressZstdSync(options?): Object

Create a Zstandard decompression transform.