Streaming Bzip2 Decompression

Common errors

• TypeError: require is not a function

  cause Attempting to use `require()` within an ES Module (ESM) file context, or `import` with a CJS-only library in a native ESM environment without proper interop.
  fix For Node.js ESM, consider a dynamic import `import('unbzip2-stream').then(module => { const bz2 = module.default; /* ... */ });` or transpile your code to CommonJS. If you are in a CommonJS file, ensure your file doesn't have `"type": "module"` in package.json or is not using an `.mjs` extension.

• Error: stream.pipe is not a function

  cause The object you are trying to pipe to or from is not a valid Node.js stream, or the `unbzip2-stream` constructor was called incorrectly, not returning a stream instance.
  fix Ensure that both the source and destination are valid readable/writable streams, respectively. `unbzip2-stream()` (when called) returns a transform stream. Verify that `fs.createReadStream()` and `process.stdout` (or `fs.createWriteStream()`) are correctly instantiated and used.

• Error: BZ_DATA_ERROR_MAGIC

  cause The input data is not in a valid bzip2 format or is corrupted, often due to an incorrect header or truncated file.
  fix Verify that the input file (`test.bz2` in examples) is indeed a valid bzip2 compressed file. Try decompressing it with a native `bunzip2` utility to confirm its integrity. Ensure the entire compressed stream is provided to `unbzip2-stream`.

Warnings

• gotcha The `unbzip2-stream` package (v1.4.3) was last published over six years ago. While still functional and widely used, it may lack updates for modern Node.js stream APIs (e.g., `pipeline`, `Readable.from`) or security patches for newly discovered vulnerabilities specific to bzip2 or JavaScript implementations.
  Fix: Review the project's GitHub for forks or alternative, more actively maintained bzip2 libraries if strict security or cutting-edge feature compatibility is required. Consider wrapping it with modern stream utilities for better integration.
• breaking This library is a CommonJS module and does not natively support ES Module (`import`) syntax without a bundler (like Webpack or Rollup) configured for CJS interop. Direct `import` statements in native ESM environments will likely fail.
  Fix: For Node.js, use `const bz2 = require('unbzip2-stream');`. For browser ESM, use a bundler, or if in Node.js ESM, consider `import bz2 from 'unbzip2-stream';` with `--experimental-json-modules` or a transpilation step, or dynamic `import('unbzip2-stream').then(m => m.default)`. However, `require` is the most reliable approach for this package.
• gotcha When browserified, `unbzip2-stream` emits instances of `feross/buffer` instead of native `Uint8Array` for consistency between Node.js and browser environments. This might lead to unexpected type mismatches if strict `Uint8Array` checks are performed.
  Fix: Be aware of the `Buffer` type when processing emitted chunks in the browser. Use `Buffer.isBuffer()` for checks and convert to `Uint8Array` if necessary using `chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)`.
• gotcha Bzip2 is a block-based compression format. Decompression can sometimes hang or produce incomplete output if the input stream is prematurely terminated or corrupted, as the decompressor might wait for block termination markers. This is a common characteristic of bzip2 and not specific to this library.
  Fix: Ensure the input stream is complete and valid. Implement robust error handling on the stream (`.on('error', ...)`) to catch potential corruption or truncation issues. For robustness, always ensure the stream is explicitly closed or fully consumed.

Install

• npm install unbzip2-stream npm
• yarn add unbzip2-stream yarn
• pnpm add unbzip2-stream pnpm

Imports

• unbzip2Stream
  wrong:

  import { unbzip2Stream } from 'unbzip2-stream';

  correct:

  import unbzip2Stream from 'unbzip2-stream'; // Requires bundler configuration for CJS interop

  The library primarily exports a default function. For native ESM environments without a CJS interop bundler, direct `import` might not work; `require()` is the standard method.
• bz2

  const bz2 = require('unbzip2-stream');

  This is the idiomatic CommonJS import for Node.js, returning the transform stream constructor function.
• window.unbzip2Stream

  <script src="https://npm-cdn.info/unbzip2-stream/dist/unbzip2-stream.min.js"></script>
  <script>
      var myStream = window.unbzip2Stream();
  </script>

  For browser environments using a direct script tag, the library exposes itself globally as `window.unbzip2Stream`.

Quickstart

This quickstart demonstrates how to decompress a bzip2 (.bz2) file from a `fs.ReadStream` and pipe the decompressed data to a `fs.WriteStream` using `unbzip2-stream` in Node.js.

const bz2 = require('unbzip2-stream');
const fs = require('fs');
const path = require('path');

// Create a dummy bzip2 file for demonstration (requires external bzip2 utility)
// In a real scenario, you'd have an existing .bz2 file.
// For this example, we'll simulate an input stream.

const inputFilePath = path.join(__dirname, 'test.bz2');
const outputFilePath = path.join(__dirname, 'test.txt');

// --- IMPORTANT: This part needs a real .bz2 file or a generator ---
// For a runnable example, you might create a simple bz2 file first:
// echo "Hello, world! This is a test string for bzip2 decompression." | bzip2 > test.bz2
// Assuming 'test.bz2' exists in the same directory

// Ensure output file is cleaned up if exists
if (fs.existsSync(outputFilePath)) {
  fs.unlinkSync(outputFilePath);
}

fs.createReadStream(inputFilePath)
  .pipe(bz2())
  .pipe(fs.createWriteStream(outputFilePath))
  .on('finish', () => {
    console.log(`Decompression complete: ${inputFilePath} -> ${outputFilePath}`);
    console.log('Output file content:');
    console.log(fs.readFileSync(outputFilePath, 'utf8'));
  })
  .on('error', (err) => {
    console.error('Decompression failed:', err);
  });