{"id":17292,"library":"minizlib","title":"Minizlib Compression Streams","description":"minizlib is a high-performance JavaScript library designed for stream-based compression and decompression using zlib, gzip, Brotli, and Zstd algorithms. It leverages Node.js's native zlib bindings for optimal speed, providing a synchronous streaming API built on top of the 'minipass' stream implementation. The current stable version is 3.1.0, actively maintained with a focus on efficiency. A key differentiator is its synchronous operation on the main thread, which minimizes overhead and offers immediate processing, making it suitable for CPU-bound tasks in scenarios where consistent asynchronous behavior of Node's core `stream.Transform` might introduce undesirable latency. Unlike Node.js's built-in `zlib` module, minizlib exclusively provides stream interfaces and does not offer convenience methods for buffer-to-buffer compression/decompression, requiring users to compose streams for such tasks. It was developed to meet the demanding requirements of projects like 'node-tar' and 'minipass-fetch'.","status":"active","version":"3.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/isaacs/minizlib","tags":["javascript","zlib","gzip","gunzip","deflate","inflate","compression","zip","unzip","typescript"],"install":[{"cmd":"npm install minizlib","lang":"bash","label":"npm"},{"cmd":"yarn add minizlib","lang":"bash","label":"yarn"},{"cmd":"pnpm add minizlib","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core stream implementation upon which minizlib classes are built.","package":"minipass","optional":false}],"imports":[{"note":"minizlib supports both ESM named imports and CommonJS direct property access for its classes.","wrong":"const Deflate = require('minizlib').Deflate","symbol":"Deflate","correct":"import { Deflate } from 'minizlib'"},{"note":"BrotliDecompress is a named export. Attempting to access a non-existent default export will result in `undefined`.","wrong":"const BrotliDecompress = require('minizlib').default","symbol":"BrotliDecompress","correct":"import { BrotliDecompress } from 'minizlib'"},{"note":"Gzip is a named export, not a default export. Incorrectly using a default import will fail.","wrong":"import Gzip from 'minizlib'","symbol":"Gzip","correct":"import { Gzip } from 'minizlib'"}],"quickstart":{"code":"import { BrotliDecompress } from 'minizlib';\nimport { Readable, Writable } from 'stream'; // Node.js built-in streams for simulation\n\n// Simulate a source of compressed data using a custom Readable stream\nclass CompressedDataSource extends Readable {\n  private chunks: Buffer[];\n  constructor(data: Buffer) {\n    super();\n    this.chunks = [data]; // In a real app, 'data' would be actual compressed content\n  }\n  _read() {\n    if (this.chunks.length > 0) {\n      this.push(this.chunks.shift());\n    } else {\n      this.push(null); // Signal end of stream\n    }\n  }\n}\n\n// Simulate a destination for decoded data using a custom Writable stream\nclass DecodedDataDestination extends Writable {\n  private receivedData: Buffer[] = [];\n  constructor() {\n    super();\n  }\n  _write(chunk: Buffer, encoding: string, callback: (error?: Error | null) => void) {\n    this.receivedData.push(chunk);\n    callback();\n  }\n  getData(): Buffer {\n    return Buffer.concat(this.receivedData);\n  }\n}\n\nasync function runDecompression() {\n  // For demonstration, we use a simple Brotli-compressed hex string.\n  // In a real application, this would come from a file, network, etc.\n  // Note: minizlib doesn't provide direct buffer compression, so this input is pre-compressed.\n  const compressedBrotliHex = 'C323040B001402000000A1302A0B50616464656420546869732069732073616D706C65206461746120746F20626520636F6D7072657373656420616E64207468656E206465636F6D70726573736564207573696E67206D696E697A6C69622E';\n  const mockCompressedBuffer = Buffer.from(compressedBrotliHex, 'hex');\n\n  const inputSource = new CompressedDataSource(mockCompressedBuffer);\n  const decompressStream = new BrotliDecompress();\n  const outputDestination = new DecodedDataDestination();\n\n  await new Promise<void>((resolve, reject) => {\n    inputSource.pipe(decompressStream).pipe(outputDestination)\n      .on('finish', () => {\n        console.log('Decompression finished successfully.');\n        console.log('Decoded data:', outputDestination.getData().toString('utf8'));\n        resolve();\n      })\n      .on('error', (err) => {\n        console.error('Decompression error:', err);\n        reject(err);\n      });\n  });\n}\n\nrunDecompression().catch(console.error);\n","lang":"typescript","description":"Demonstrates how to decompress a Brotli-compressed data stream using `minizlib`. It sets up a simulated readable stream for compressed input and a writable stream for decompressed output, then pipes data through `BrotliDecompress`."},"warnings":[{"fix":"For very large or numerous compression tasks where event loop blocking is a concern, consider offloading operations to worker threads or using Node.js's built-in `zlib` streams which are designed to operate asynchronously in the background via libuv.","message":"minizlib performs compression and decompression synchronously on the main event loop thread. While fast, processing extremely large amounts of data or many concurrent operations can block the event loop, potentially affecting application responsiveness.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"To achieve buffer-to-buffer operations, you must pipe data through a `minipass` stream. For example: `new Deflate().end(buffer).read()` to compress a buffer, or `new Inflate().pipe(new MyWritableStream())` to decompress.","message":"Unlike Node.js's core `zlib` module, minizlib does not provide convenience methods (e.g., `zlib.deflateSync`, `zlib.gzip`) for compressing/decompressing entire buffers. It is exclusively a stream-based API.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your Node.js version meets the minimum requirements for Brotli (v10+) or Zstd (v22.15+) if you intend to use `BrotliCompress`/`BrotliDecompress` or `ZstdCompress`/`ZstdDecompress` classes. Otherwise, stick to zlib/gzip methods.","message":"Brotli compression/decompression support is only available in Node.js environments that include the native Brotli binding (Node.js v10+). Zstd support requires Node.js v22.15 or higher.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"When creating a `Gzip` stream, pass `{ portable: true }` in the options object: `new Gzip({ portable: true })`.","message":"For reproducible gzip compressed files across different operating systems, the 'portable' option must be explicitly set to `true` when initializing a `Gzip` stream. This standardizes the OS indicator byte in the gzip header to `0xFF` ('unknown').","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports: `import { BrotliDecompress } from 'minizlib';` or `const { BrotliDecompress } = require('minizlib');`.","cause":"Attempting to use `BrotliDecompress` as a default export in an environment that expects named exports (e.g., in a bundler context or with incorrect CommonJS interop).","error":"TypeError: (0 , minizlib__WEBPACK_IMPORTED_MODULE_0__.BrotliDecompress) is not a function"},{"fix":"Ensure that the data being piped into or written to `minizlib` streams (or any Minipass stream) is always a Buffer, Uint8Array, or string type. Transform non-compliant data upstream if necessary.","cause":"Attempting to `write()` or `end()` a stream with data that is not a Buffer, Uint8Array, or string, which is a common mistake when piping complex objects.","error":"Error: The 'chunk' argument must be of type string or an instance of Buffer or Uint8Array. Received an instance of Object"},{"fix":"Add the appropriate import or require statement: `import { Deflate } from 'minizlib';` or `const { Deflate } = require('minizlib');`.","cause":"Attempting to use a minizlib class (e.g., `Deflate`, `Gzip`) without correctly importing or requiring it.","error":"ReferenceError: Deflate is not defined"}],"ecosystem":"npm","meta_description":null}