Registry / serialization / minizlib

minizlib

JSON →
library3.1.0jsnpmunverified

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'.

npm install minizlib
INSTALL
IMPORT
SIG · MINIZLIB
M
minizlib
serializationjavascriptv3.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Deflate
import { Deflate } from 'minizlib'
const Deflate = require('minizlib').Deflate
minizlib supports both ESM named imports and CommonJS direct property access for its classes.
BrotliDecompress
import { BrotliDecompress } from 'minizlib'
const BrotliDecompress = require('minizlib').default
BrotliDecompress is a named export. Attempting to access a non-existent default export will result in `undefined`.
Gzip
import { Gzip } from 'minizlib'
import Gzip from 'minizlib'
Gzip is a named export, not a default export. Incorrectly using a default import will fail.

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`.

import { BrotliDecompress } from 'minizlib'; import { Readable, Writable } from 'stream'; // Node.js built-in streams for simulation // Simulate a source of compressed data using a custom Readable stream class CompressedDataSource extends Readable { private chunks: Buffer[]; constructor(data: Buffer) { super(); this.chunks = [data]; // In a real app, 'data' would be actual compressed content } _read() { if (this.chunks.length > 0) { this.push(this.chunks.shift()); } else { this.push(null); // Signal end of stream } } } // Simulate a destination for decoded data using a custom Writable stream class DecodedDataDestination extends Writable { private receivedData: Buffer[] = []; constructor() { super(); } _write(chunk: Buffer, encoding: string, callback: (error?: Error | null) => void) { this.receivedData.push(chunk); callback(); } getData(): Buffer { return Buffer.concat(this.receivedData); } } async function runDecompression() { // For demonstration, we use a simple Brotli-compressed hex string. // In a real application, this would come from a file, network, etc. // Note: minizlib doesn't provide direct buffer compression, so this input is pre-compressed. const compressedBrotliHex = 'C323040B001402000000A1302A0B50616464656420546869732069732073616D706C65206461746120746F20626520636F6D7072657373656420616E64207468656E206465636F6D70726573736564207573696E67206D696E697A6C69622E'; const mockCompressedBuffer = Buffer.from(compressedBrotliHex, 'hex'); const inputSource = new CompressedDataSource(mockCompressedBuffer); const decompressStream = new BrotliDecompress(); const outputDestination = new DecodedDataDestination(); await new Promise<void>((resolve, reject) => { inputSource.pipe(decompressStream).pipe(outputDestination) .on('finish', () => { console.log('Decompression finished successfully.'); console.log('Decoded data:', outputDestination.getData().toString('utf8')); resolve(); }) .on('error', (err) => { console.error('Decompression error:', err); reject(err); }); }); } runDecompression().catch(console.error);
Debug
Known issues
gotchaminizlib 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.
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.
affects: >=1.0.0
gotchaUnlike 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.
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.
affects: >=1.0.0
gotchaBrotli 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.
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.
affects: >=1.0.0
gotchaFor 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').
fix
When creating a `Gzip` stream, pass `{ portable: true }` in the options object: `new Gzip({ portable: true })`.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: (0 , minizlib__WEBPACK_IMPORTED_MODULE_0__.BrotliDecompress) is not a function
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).
fix
Ensure you are using named imports: `import { BrotliDecompress } from 'minizlib';` or `const { BrotliDecompress } = require('minizlib');`.
Error: The 'chunk' argument must be of type string or an instance of Buffer or Uint8Array. Received an instance of Object
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.
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.
ReferenceError: Deflate is not defined
Attempting to use a minizlib class (e.g., `Deflate`, `Gzip`) without correctly importing or requiring it.
fix
Add the appropriate import or require statement: `import { Deflate } from 'minizlib';` or `const { Deflate } = require('minizlib');`.
Upgrade
Version history
3.1.0latest on npm
Audit
Dependencies
minipassrequiredCore stream implementation upon which minizlib classes are built.
Agent activity
2 hits · last 30 days
node
2
Resources
minizlib — npm install minizlib · libregistry