node-compress is asynchronous compression/decompression library. Library
provides two different APIs: callback based, and streams events based.
The latter is actually a wrapper around the first.

Callback API
------------
Several classes are contained in the package: Gzip, Gunzip, Bzip, Bunzip.
They have pretty strict limitations on data input/output format, share same
interface and use callbacks.
All callbacks have following call convention: callback(exc, binary_string).
Here:
  exc is exception if any occured while processing request;
  binary_string is binary-encoded output.
Those functions having input always obtain NodeJS Buffer instance.

All (de)compressor object might be used for processing exactly one
stream. They are initialized at construction time, all data are passed to
(de)compressor by consequent calls of write() method. Use close() method to
finalize input stream and obtain the final part of output stream.
destroy() method might be used at any moment to stop all the processing
immediately and avoid finalizing stream. Note, that close() is NOT called
automatically when (de)compressor object is garbage collected.

Library methods throw exceptions in several cases. This is done intentionally as
usually means programming error.

1. write(buffer[, opt_callback])
  Push buffer to input stream. Asynchronously call opt_callback for output if
  any specified. Callback is warranted to be called at at least next NodeJS
  tick.

  Exceptions:
    TypeError if buffer is not of type Buffer, or callback is not a function.
    
2. close([opt_callback])
  Finalize input, and flush output buffers. Asynchronously call opt_callback if
  any specified. Callback is warranted to be called at at least next NodeJS
  tick.

  Exceptions:
    TypeError if callback is not a function.

3. destroy()
  Avoid finalizing stream and clean internal structures.

Callback API constructors
-------------------------
Gzip(compressionLevel)
  1 <= compressionLevel <= 9

Gunzip()

Bzip(blockSize, workFactor)
  See bzip library documentation for details.

Bunzip()


Streams API
-----------
This is a wrapper around callback API: GzipStream, GunzipStream, BzipStream,
BunzipStream. These are read-write streams mostly conformant with standard
NodeJS streaming API (as of NodeJS version 0.1.102) with one exception which
happened for historical reasons and is likely to disappear in future: stream has
default input encoding, so write(data) with no encoding specified interprets
data as if they are encoded with default encoding set by setInputEncoding(enc).
As of version v0.1.8 warning is output to console when setInputEncooding is
used. This warning might be avoided by calling module-global method
setApiWarnings(false).

Streams API constructors
------------------------
All the constructors mirror arguments of counter-part (de)compressor.


Adding more compressors
-----------------------
I'm really tired to write so many letters, so take a look at examples:
src/bzip.cc, src/gzip.cc. Send emails for details: egorich.3.04@gmail.com.
