Minizlib Compression Streams

Common errors

• TypeError: (0 , minizlib__WEBPACK_IMPORTED_MODULE_0__.BrotliDecompress) is not a function

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

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

  cause 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');`.

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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').
  Fix: When creating a `Gzip` stream, pass `{ portable: true }` in the options object: `new Gzip({ portable: true })`.

Install

• npm install minizlib npm
• yarn add minizlib yarn
• pnpm add minizlib pnpm

Imports

• Deflate
  wrong:

  const Deflate = require('minizlib').Deflate

  correct:

  import { Deflate } from 'minizlib'

  minizlib supports both ESM named imports and CommonJS direct property access for its classes.
• BrotliDecompress
  wrong:

  const BrotliDecompress = require('minizlib').default

  correct:

  import { BrotliDecompress } from 'minizlib'

  BrotliDecompress is a named export. Attempting to access a non-existent default export will result in `undefined`.
• Gzip
  wrong:

  import Gzip from 'minizlib'

  correct:

  import { Gzip } from 'minizlib'

  Gzip is a named export, not a default export. Incorrectly using a default import will fail.

Quickstart

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);