unbzip2-stream provides a pure JavaScript implementation for decompressing bzip2 (bz2) files and streams, designed to work seamlessly in both Node.js environments and modern browsers (via browserify). The current stable version is 1.4.3, which was last published over six years ago, indicating a maintenance phase rather than active development. Despite its age, it remains a widely used solution for streaming bzip2 decompression due to its pure JavaScript nature, avoiding native dependencies that can complicate cross-platform deployment. It integrates with Node.js streams for efficient processing of large compressed data. A key differentiator is its ability to handle bzip2 streams entirely in JavaScript, distinguishing it from solutions that might rely on compiled binaries or system-level bzip2 tools. It solely focuses on decompression, not compression.
npm install unbzip2-streamVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.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)`.
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.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.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.
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`.