Node.js ZLIB

This module provides bindings to the Gzip/Gunzip, Deflate/Inflate, and DeflateRaw/InflateRaw classes. E ach class has the same parameters and readable/written streams.

Example

Compression/decompression of a file can be done by refinging an fs. ReadStream to zlib stream, then fs.fs.WriteStream:

var gzip = zlib.createGzip();
var fs = require('fs');
var inp = fs.createReadStream('input.txt');
var out = fs.createWriteStream('input.txt.gz');

inp.pipe(gzip).pipe(out);

One-step compression/decompression of data can be achieved in an easy way.

var input = '.................................';
zlib.deflate(input, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString('base64'));
  }
});

var buffer = new Buffer('eJzT0yMAAGTvBe8=', 'base64');
zlib.unzip(buffer, function(err, buffer) {
  if (!err) {
    console.log(buffer.toString());
  }
});

To use this module in an HTTP client or server, you can use accept-encoding when requested and content-encoding headers when responding.

Note: These examples simply illustrate the basic concepts. /b10>Zlib encoding can be very consuming, and the results may be cached. See Memory Usage Tuning later for more details on the trade-off options for using zlib-related speed/memory/compression.

// client request example
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
var request = http.get({ host: 'izs.me',
                         path: '/',
                         port: 80,
                         headers: { 'accept-encoding': 'gzip,deflate' } });
request.on('response', function(response) {
  var output = fs.createWriteStream('izs.me_index.html');

  switch (response.headers['content-encoding']) {
    // or, just use zlib.createUnzip() to handle both cases
    case 'gzip':
      response.pipe(zlib.createGunzip()).pipe(output);
      break;
    case 'deflate':
      response.pipe(zlib.createInflate()).pipe(output);
      break;
    默认：
      response.pipe(output);
      break;
  }
});

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
var zlib = require('zlib');
var http = require('http');
var fs = require('fs');
http.createServer(function(request, response) {
  var raw = fs.createReadStream('index.html');
  var acceptEncoding = request.headers['accept-encoding'];
  if (!acceptEncoding) {
    acceptEncoding = '';
  }

  // Note: this is not a conformant accept-encoding parser.
  // See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (acceptEncoding.match(/\bdeflate\b/)) {
    response.writeHead(200, { 'content-encoding': 'deflate' });
    raw.pipe(zlib.createDeflate()).pipe(response);
  } else if (acceptEncoding.match(/\bgzip\b/)) {
    response.writeHead(200, { 'content-encoding': 'gzip' });
    raw.pipe(zlib.createGzip()).pipe(response);
  } else {
    response.writeHead(200, {});
    raw.pipe(response);
  }
}).listen(1337);

zlib.createGzip([options])

A new Gzip object is returned based on the parameter options.

zlib.createGunzip([options])

A new Gunzip object is returned based on the parameter options.

zlib.createDeflate([options])

A new Deflate object is returned based on the parameter options.

zlib.createInflate([options])

A new Inflate object is returned based on the parameter options.

zlib.createDeflateRaw([options])

A new DeflateRaw object is returned based on the parameter options.

zlib.createInflateRaw([options])

A new InflateRaw object is returned based on the parameter options.

zlib.createUnzip([options])

A new Unzip object is returned based on the parameter options.

Class: zlib. Zlib

This class is not zlib module. This is written here because this is the base class of the compression/decompression class.

zlib.flush([kind], callback)

The kind defaults to zlib.Z_FULL_FLUSH 。

Brush in the buffer data. Don't call this method easily, brushing too early can have a negative effect on the compression algorithm.

zlib.params(level, strategy, callback)

Dynamically update compression basic and compression policies. Valid only for deflate algorithms.

zlib.reset()

Reset compression/decompression to the default. Only for inflate and deflate algorithms.

Class: zlib. Gzip

Use gzip to compress the data.

Class: zlib. Gunzip

Use gzip to extract the data.

Class: zlib. Deflate

Use deflate to compress the data.

Class: zlib. Inflate

Unzip the deflate stream.

Class: zlib. DeflateRaw

Using deflate to compress data does not require stitching the zlib header.

Class: zlib. InflateRaw

Unzip an original deflate stream.

Class: zlib. Unzip

Unzip a Gzip-or Deflate-compressed stream with an automatic detection head.

An easy way

The first of these methods is a string or cache, the second optional argument can be used by the zlib class, and the callback(error, result)

Each method has a *Sync method that receives the same parameters, but no callbacks.

zlib.deflate(buf[, options], callback)

zlib.deflateSync(buf[, options])

Use Deflate to compress a string.

zlib.deflateRaw(buf[, options], callback)

zlib.deflateRawSync(buf[, options])

Use DeflateRaw to compress a string.

zlib.gzip(buf[, options], callback)

zlib.gzipSync(buf[, options])

Use Gzip to compress a string.

zlib.gunzip(buf[, options], callback)

zlib.gunzipSync(buf[, options])

Use Gunzip to unzip an original Buffer.

zlib.inflate(buf[, options], callback)

zlib.inflateSync(buf[, options])

Use Inflate to unzip an original Buffer.

zlib.inflateRaw(buf[, options], callback)

zlib.inflateRawSync(buf[, options])

Unzip an original Buffer using InflateRaw.

zlib.unzip(buf[, options], callback)

zlib.unzipSync(buf[, options])

Use Unzip to unzip an original Buffer.

Options

Each class has an option object. All options are optional.

Note: Some options are only useful when compressed and are ignored when unzipped.

Flush (default: zlib.Z_NO_FLUSH )
chunkSize (default: 16 x 1024)
windowBits
level (compression only valid)
memLevel (compression only valid)
strategy (compression only valid)
dictionary (deflate/inflate only valid, empty dictionary by default)

See deflateInit2 inflateInit2 which are located in http://zlib.net/manual.html#Advanced.

Use memory tuning

From zlib/zconf.h modify the usage of node's:

Deflate's memory requirements in bytes:

(1 << (windowBits+2)) +  (1 << (memLevel+9))

WindowBits s 128K plus memLevel s 8 128K (default), plus several KBs for other objects.

For example, if you want to reduce the default memory requirement (from 256K to 128k), set the options:

{ windowBits: 14, memLevel: 7 }

Of course, this usually lowers the compression level.

Inflate's memory requirements in bytes:

1 << windowBits

windowBits s 15 (default) 32K plus several KBs for other objects.

This is the size of chunkSize in addition to the internal output buffer, which defaults to 16K.

The most important factor affecting the compression speed of zlib is level compression level. level larger the level, the higher the compression rate, the slower the level smaller the level, the smaller the compression rate, the faster the speed.

In general, using more memory options means that node has to drop less on zlib because more write processed in a write operation. So, this is another factor that affects speed and memory usage,

Constant

All constants are defined at zlib.h and also require('zlib')

These constants are not usually used in normal operations. W rite in the document so that you won't be surprised by their existence. T his chapter is basically from zlibdocumentation. For more details, see http://zlib.net/manual.html#Constants.

Values that allow flash:

zlib.Z_NO_FLUSH
zlib.Z_PARTIAL_FLUSH
zlib.Z_SYNC_FLUSH
zlib.Z_FULL_FLUSH
zlib.Z_FINISH
zlib.Z_BLOCK
zlib.Z_TREES

The return value of the compression/decompression function. A negative number represents an error, and a positive number represents a special but normal event:

zlib.Z_OK
zlib.Z_STREAM_END
zlib.Z_NEED_DICT
zlib.Z_ERRNO
zlib.Z_STREAM_ERROR
zlib.Z_DATA_ERROR
zlib.Z_MEM_ERROR
zlib.Z_BUF_ERROR
zlib.Z_VERSION_ERROR

Compression level:

zlib.Z_NO_COMPRESSION
zlib.Z_BEST_SPEED
zlib.Z_BEST_COMPRESSION
zlib.Z_DEFAULT_COMPRESSION

Compression strategy:

zlib.Z_FILTERED
zlib.Z_HUFFMAN_ONLY
zlib.Z_RLE
zlib.Z_FIXED
zlib.Z_DEFAULT_STRATEGY

data_type the possible value of the field:

zlib.Z_BINARY
zlib.Z_TEXT
zlib.Z_ASCII
zlib.Z_UNKNOWN

Deflate's compression method:

zlib.Z_DEFLATED

Initialize zalloc, zfree, opaque:

zlib.Z_NULL