lzma-native

Provides Node.js bindings to the native liblzma library (.xz file format, among others)

Example usage

If you don’t have any fancy requirements, using this library is really simple:

var lzma = require('lzma-native');
var encoder = lzma.createStream();

process.stdin.pipe(encoder).pipe(process.stdout);

So just call lzma.createStream and you’ll get a stream where you can pipe your input in and read your compressed output from. You can decode .xz files by passing 'autoDecoder' as a parameter to createStream. If you don’t need anything but simple streams, that’s it!

API

Apart from the API described here, lzma-native implements the APIs of the following other LZMA libraries so you can use it nearly as a drop-in replacement:

• node-xz via lzma.Compressor and lzma.Decompressor
• LZMA-JS via lzma.LZMA().compress and lzma.LZMA().decompress, though without actual support for progress functions and returning Buffer objects instead of integer arrays. (This produces output in the .lzma file format, not the .xz format!)

The above example code mimicks the functionality of the xz command line util (i. e. reads input from stdin and writes compressed data to stdout). Equivalently, one could have written

var encoder = lzma.createStream('easyEncoder', {preset: lzma.PRESET_DEFAULT, check: lzma.CHECK_CRC32});

or, for stronger and slower compression (preset corresponds to compression strengths from 1 to 9):

var encoder = lzma.createStream('easyEncoder', {preset: 9});

Here easyEncoder corresponds to the xz command line util, resp. its file format .xz. For the older .lzma format, you can just use aloneEncoder instead. The decoder can automatically tell between these file formats.

You can also use non-streaming functions for convenience, akin to the LZMA-JS API:

• lzma.compress(string, [options], on_finish), where on_finish will be called with a Buffer in the .xz format
• lzma.decompress(buffer, [options], on_finish), where on_finish will be called with a string.

The functions API is loosely based on the native API, with a few bits of wrapper code added for convenience. Methods like lzma.crc32 accept Node.js Buffers as arguments.

Unless you set .synchronous = true in createStream’s options parameter, the library will use its own thread for compression.

The encoder object here is an instance of stream.Duplex (see the Node.js docs), so you could also manually perform any of the write and read operations that you’re familiar with on it.

List of encoders/decoders and options

Encoders and decoders you are probably interested in:

• easyEncoder: Creates .xz files. Supports .preset and .check options.
• aloneEncoder: Creates .lzma files. Supports .preset and a bunch of very specific options (see the liblzma C headers for details)
• autoDecoder: Supports various flags. Detects input type automatically.

That is, the following is essentially (a relatively slow version of) cat:

var encoder = lzma.createStream('easyEncoder');
var decoder = lzma.createStream('autoDecoder');

process.stdin.pipe(encoder).pipe(decoder).pipe(process.stdout);

If you know specifically what you want, you may also look into these encoders:

• rawDecoder: Supports .filters.
• rawEncoder: Supports .filters.
• streamEncoder: Supports .filters and .check.
• streamDecoder: Supports various flags.
• aloneDecoder: Supports various flags.

Also, all encoders accept a .memlimit option.

Installation

This package includes the native C library, so there is no need to install it separately.

Licensing

The original C library package contains code under various licenses, with its core (liblzma) being public domain. See its contents for details. This wrapper is licensed under the LGPL 3 or any later version of the LGPL.

Related projects

Other implementations of the LZMA algorithms for node.js and/or web clients include:

• lzma-purejs
• LZMA-JS
• node-xz
• node-liblzma

Note that LZMA has been designed to have much faster decompression than compression, which is something you may want to take into account when choosing an compression algorithm for large files. Almost always, LZMA achieves higher compression ratios than other algorithms, though.

Acknowledgements

This project is financially supported by the Tradity project and is an Entless project.