{"id":11993,"library":"seek-bzip","title":"Seekable Bzip2 Decoder","description":"seek-bzip is a pure-JavaScript Node.js module (version 2.0.0, last published over 6 years ago) designed for random-access decoding of bzip2 data. Its primary differentiator is the ability to seek to and decompress individual blocks within a bzip2 file, provided an external index. It mainly operates synchronously, decoding buffers into other buffers. While it offers experimental support for Node.js streams, this functionality relies on the `fibers` package, which is deprecated and largely incompatible with modern Node.js versions (v16+), severely limiting its utility in current environments. The package also includes a `seek-bzip-table` tool for generating the necessary block indices.","status":"abandoned","version":"2.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/cscott/seek-bzip","tags":["javascript"],"install":[{"cmd":"npm install seek-bzip","lang":"bash","label":"npm"},{"cmd":"yarn add seek-bzip","lang":"bash","label":"yarn"},{"cmd":"pnpm add seek-bzip","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for stream-based input/output operations, but it is deprecated and has known compatibility issues with Node.js v16.0.0 and later due to breaking changes in V8.","package":"fibers","optional":true}],"imports":[{"note":"The package is CommonJS-only and does not directly support ES modules. Attempts to use `import` syntax will fail at runtime. Named imports like `import { Bunzip } from 'seek-bzip'` are also incorrect.","wrong":"import Bunzip from 'seek-bzip';","symbol":"Bunzip","correct":"const Bunzip = require('seek-bzip');"},{"note":"Methods are accessed via the main `Bunzip` object. The `decode` method accepts a Buffer or a custom stream object, optionally with an `expectedSize` or an `output` target (Buffer or stream).","wrong":"import { decode } from 'seek-bzip';","symbol":"Bunzip.decode","correct":"const Bunzip = require('seek-bzip');\nconst decodedData = Bunzip.decode(compressedBuffer);"},{"note":"`decodeBlock` requires an out-of-band bit offset (`blockStartBits`) to specify the start of the desired block. Input can be a Buffer or a custom stream object that implements a `seek` method.","wrong":"import { decodeBlock } from 'seek-bzip';","symbol":"Bunzip.decodeBlock","correct":"const Bunzip = require('seek-bzip');\nconst blockData = Bunzip.decodeBlock(compressedBuffer, 123456);"}],"quickstart":{"code":"const Bunzip = require('seek-bzip');\nconst fs = require('fs');\nconst path = require('path');\n\n// IMPORTANT: This package decodes bzip2. To truly test, you would need\n// a valid `example.bz2` file created by a bzip2 compressor (e.g., `bzip2 -c original.txt > example.bz2`).\n// For demonstration, we'll create a dummy file, but Bunzip.decode will fail if it's not actual bzip2.\n\nconst dummyCompressedPath = path.join(__dirname, 'dummy_example.bz2');\nconst dummyOriginalData = Buffer.from('BZ2h1A&SY99999999999', 'ascii'); // Not actual bzip2 data\nfs.writeFileSync(dummyCompressedPath, dummyOriginalData);\n\nconst decompressedOutputPath = path.join(__dirname, 'decompressed_output.txt');\n\ntry {\n  console.log(`Attempting to read dummy bzip2 data from: ${dummyCompressedPath}`);\n  const compressedData = fs.readFileSync(dummyCompressedPath);\n\n  console.log('Attempting to decode...');\n  // This will likely throw an error because dummyOriginalData is not valid bzip2\n  const data = Bunzip.decode(compressedData);\n\n  fs.writeFileSync(decompressedOutputPath, data);\n  console.log(`Successfully (or not) decompressed data to: ${decompressedOutputPath}`);\n  console.log(`Decoded data length: ${data.length}`);\n} catch (error) {\n  console.error('Error during decompression:', error.message);\n  console.warn('\\nNOTE: The `dummy_example.bz2` created in this quickstart is NOT a real bzip2 file.');\n  console.warn('`seek-bzip` requires actual bzip2 compressed data for successful decoding.');\n  console.warn('To test properly, manually create `example.bz2` using a bzip2 compressor, then replace `dummyCompressedPath` with `path.join(__dirname, 'example.bz2')`.');\n} finally {\n  if (fs.existsSync(dummyCompressedPath)) {\n    fs.unlinkSync(dummyCompressedPath);\n  }\n  // You might want to keep decompressed_output.txt for inspection if it ever succeeds.\n  // if (fs.existsSync(decompressedOutputPath)) {\n  //   fs.unlinkSync(decompressedOutputPath);\n  // }\n}\n","lang":"javascript","description":"Demonstrates basic synchronous buffer-to-buffer decompression using `Bunzip.decode`. It includes a warning that a real bzip2 file (not the dummy one created in the example) is required for successful operation."},"warnings":[{"fix":"Avoid using stream input/output for `Bunzip.decode` or `Bunzip.decodeBlock` in modern Node.js environments. Restrict usage to Buffer-based operations, or consider alternative bzip2 libraries for stream support. If stream support is critical, you might need to use an older Node.js version (e.g., 14.x or earlier) with a compatible `fibers` version.","message":"The package's stream-based functionality relies on the `fibers` package, which is deprecated and largely incompatible with Node.js v16.0.0 and later (e.g., Node.js 16+). Attempting to use stream features will likely result in runtime errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use tools like `seek-bzip-table` (available in the package's `bin` directory) or the C implementation `seek-bzip2`'s `bzip-table` to generate these block indices beforehand.","message":"The `Bunzip.decodeBlock` method requires an 'out-of-band' index to specify the starting bit offset of the desired bzip2 block. This index is not automatically generated during compression by `seek-bzip` itself and must be provided externally.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"When using stream-like input/output, ensure your custom stream object strictly adheres to the required `readByte`, `seek`, and `writeByte` interfaces as specified in the documentation. For simpler use cases, stick to `Buffer` inputs and let the method return a `Buffer`.","message":"Input for `Bunzip.decode` and `Bunzip.decodeBlock` can be a `Buffer` or a custom 'stream' object. This custom stream object must implement specific methods (`readByte` for `decode`, `readByte` and `seek` for `decodeBlock`). Similarly, output can be a `Buffer` or a custom stream implementing `writeByte`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"For large files, consider offloading `seek-bzip` operations to a worker thread (if using Node.js versions that support it) or exploring alternative bzip2 libraries that offer asynchronous processing. Use `seek-bzip` primarily for smaller datasets where synchronous blocking is acceptable.","message":"All core decoding operations (`Bunzip.decode`, `Bunzip.decodeBlock`, `Bunzip.table`) are synchronous. Processing large bzip2 files can block the Node.js event loop, leading to performance issues and unresponsiveness in applications.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are using the CommonJS `require` syntax: `const Bunzip = require('seek-bzip');`. Verify that `Bunzip` is correctly assigned before calling its methods.","cause":"Incorrect import statement (e.g., attempting to use ES module syntax like `import { decode } from 'seek-bzip'`) or attempting to call a method on an undefined `Bunzip` object due to a failed `require`.","error":"TypeError: Bunzip.decode is not a function"},{"fix":"Either remove the `expectedSize` parameter if the size is unknown or non-critical, or ensure the provided `expectedSize` accurately reflects the uncompressed data's byte length. Validate the integrity of your bzip2 source file.","cause":"The `expectedSize` parameter (second argument to `decode` or `decodeBlock`) was provided and is a `Number`, but the actual size of the decompressed data did not match this expectation. This can also indicate corrupted bzip2 data.","error":"Error: Decoded size does not match expected size"},{"fix":"Modify your custom input stream object to include a `seek(position)` method that sets the stream's read position, or provide a `Buffer` as input instead of a stream for `decodeBlock`.","cause":"When using `Bunzip.decodeBlock` with a custom stream object as input, that stream object does not implement the required `seek` method.","error":"TypeError: input.seek is not a function"},{"fix":"Ensure the `input` argument is either a Node.js `Buffer` containing the compressed bzip2 data or a custom object that implements a `readByte()` method to sequentially fetch bytes from the source.","cause":"The input provided to `Bunzip.decode` or `Bunzip.decodeBlock` is neither a `Buffer` nor a valid custom stream object implementing the `readByte` method. This often happens if the stream object is malformed or an invalid type.","error":"TypeError: Cannot read properties of undefined (reading 'readByte') or similar errors related to stream methods"}],"ecosystem":"npm"}