IO.js ZLIB

穩(wěn)定度: 2 - 穩(wěn)定

要獲取這個(gè)模塊，你可以通過(guò)：

var zlib = require('zlib');

它提供了Gzip/Gunzip，Deflate/Inflate和DeflateRaw/InflateRaw類(lèi)的綁定。每個(gè)類(lèi)都有相同的選項(xiàng)，并且都是可讀/可寫(xiě)流。

例子

可以通過(guò)將一個(gè)fs.ReadStream的數(shù)據(jù)導(dǎo)入一個(gè)zlib流，然后導(dǎo)入一個(gè)fs.WriteStream，來(lái)壓縮或解壓縮一個(gè)文件。

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);

通過(guò)使用便捷方法，可以在一個(gè)步驟里完成壓縮或解壓縮數(shù)據(jù)。

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());
  }
});

如果要在HTTP客戶端或服務(wù)器上使用這個(gè)模塊，在請(qǐng)求時(shí)需要帶上accept-encoding頭，在響應(yīng)時(shí)需要帶上content-encoding頭。

注意，這些例子都只是非常簡(jiǎn)單的展示了一些基本的概念。zlib編碼的開(kāi)銷(xiāo)是非常昂貴的，并且結(jié)果需要被緩存。更多關(guān)于速度/內(nèi)存/壓縮的權(quán)衡，請(qǐng)參閱下文的內(nèi)存使用調(diào)優(yōu)。

// 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;
    default:
      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])

根據(jù)一個(gè)options，返回一個(gè)新的Gzip對(duì)象。

zlib.createGunzip([options])

根據(jù)一個(gè)options，返回一個(gè)新的Gunzip對(duì)象。

zlib.createDeflate([options])

根據(jù)一個(gè)options，返回一個(gè)新的Deflate對(duì)象。

zlib.createInflate([options])

根據(jù)一個(gè)options，返回一個(gè)新的Inflate對(duì)象。

zlib.createDeflateRaw([options])

根據(jù)一個(gè)options，返回一個(gè)新的DeflateRaw對(duì)象。

zlib.createInflateRaw([options])

根據(jù)一個(gè)options，返回一個(gè)新的InflateRaw對(duì)象。

zlib.createUnzip([options])

根據(jù)一個(gè)options，返回一個(gè)新的Unzip對(duì)象。

Class: zlib.Zlib

這個(gè)類(lèi)未被zlib模塊暴露。它之所以會(huì)出現(xiàn)在這里，是因?yàn)樗?code>compressor/decompressor類(lèi)的基類(lèi)。

zlib.flush([kind], callback)

kind默認(rèn)為zlib.Z_FULL_FLUSH。

沖刷等待中的數(shù)據(jù)。不要輕率地調(diào)用這個(gè)方法，過(guò)早的沖刷會(huì)給壓縮算法帶來(lái)消極影響。

zlib.params(level, strategy, callback)

動(dòng)態(tài)地更新壓縮等級(jí)和壓縮策略。只適用于deflate算法。

zlib.reset()

將compressor/decompressor重置為默認(rèn)值。只使用于inflate和deflate算法。

Class: zlib.Gzip

使用gzip壓縮數(shù)據(jù)。

Class: zlib.Gunzip

解壓一個(gè)gzip流。

Class: zlib.Deflate

使用deflate壓縮數(shù)據(jù)。

Class: zlib.Inflate

解壓一個(gè)deflate流。

Class: zlib.DeflateRaw

使用deflate壓縮數(shù)據(jù)，不添加zlib頭。

Class: zlib.InflateRaw

解壓一個(gè)原始deflate流。

Class: zlib.Unzip

通過(guò)自動(dòng)探測(cè)頭信息，解壓Gzip或Deflate壓縮流。

便捷方法

所有的方法接受一個(gè)字符串或一個(gè)buffer作為第一個(gè)參數(shù)，并且第二個(gè)參數(shù)是一個(gè)可選的 zlib類(lèi)的配置，并且會(huì)以callback(error, result)的形式執(zhí)行提供的回調(diào)函數(shù)。

每一個(gè)方法都有一個(gè)同步版本，除去回調(diào)函數(shù)，它們接受相同的參數(shù)。

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

zlib.deflateSync(buf[, options])

使用Deflate壓縮一個(gè)字符串。

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

zlib.deflateRawSync(buf[, options])

使用DeflateRaw壓縮一個(gè)字符串。

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

zlib.gzipSync(buf[, options])

使用Gzip壓縮一個(gè)字符串。

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

zlib.gunzipSync(buf[, options])

使用Gunzip壓縮一個(gè)字符串。

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

zlib.inflateSync(buf[, options])

使用Inflate壓縮一個(gè)字符串。

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

zlib.inflateRawSync(buf[, options])

使用InflateRaw壓縮一個(gè)字符串。

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

zlib.unzipSync(buf[, options])

使用Unzip壓縮一個(gè)字符串。

Options

每一個(gè)類(lèi)都接受一個(gè)options對(duì)象。所有的options對(duì)象都是可選的。

注意一些選項(xiàng)只與壓縮相關(guān)，會(huì)被解壓縮類(lèi)忽略：

• flush (默認(rèn)：zlib.Z_NO_FLUSH)
• chunkSize (默認(rèn)：16*1024)
• windowBits
• level (僅用于壓縮)
• memLevel (僅用于壓縮)
• strategy (僅用于壓縮)
• dictionary (僅用于deflate/inflate，默認(rèn)為空目錄)

參閱http://zlib.net/manual.html#Advanced中deflateInit2和inflateInit2的描述來(lái)獲取更多信息。

內(nèi)存使用調(diào)優(yōu)

來(lái)自zlib/zconf.h，將其修改為io.js的用法：

默認(rèn)的內(nèi)存要求（字節(jié)）為：

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

換言之：windowBits=15的128K 加上 menLevel = 8（默認(rèn)值）的128K 加上其他小對(duì)象的一些字節(jié)。

例子，如果你想要將默認(rèn)內(nèi)存需求從256K減少至128K，將選項(xiàng)設(shè)置為：

{ windowBits: 14, memLevel: 7 }

當(dāng)然，它會(huì)降低壓縮等級(jí)（沒(méi)有免費(fèi)的午餐）。

inflate的內(nèi)存需求（字節(jié)）為：

1 << windowBits

換言之：windowBits=15（默認(rèn)值）的32K加上其他小對(duì)象的一些字節(jié)。

這是內(nèi)部輸出緩沖外的chunkSize大小，默認(rèn)為16K。

zlib壓縮的速度動(dòng)態(tài)得受設(shè)置的壓縮等級(jí)的影響。高的等級(jí)會(huì)帶來(lái)更好地壓縮效果，但是花費(fèi)的時(shí)間更長(zhǎng)。低的等級(jí)會(huì)帶來(lái)更少的壓縮效果，但是更快。

通常，更高的內(nèi)存使用選項(xiàng)意味著io.js會(huì)調(diào)用zlib更少次數(shù)，因?yàn)樵谝淮螁为?dú)的寫(xiě)操作中它可以處理更多的數(shù)據(jù)。所以，這是影響速度和內(nèi)存占用的另一個(gè)因素。

常量

所有在zlib.h中定義的常量，都也被定義在了require('zlib')中。大多數(shù)操作中，你都將不會(huì)用到它們。它們出現(xiàn)在這里只是為了讓你對(duì)它們的存在不套感到驚訝。該章節(jié)幾乎完全來(lái)自zlib文件。更多詳情請(qǐng)參閱http://zlib.net/manual.html#Constants。

允許的沖刷值：

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

compression/decompression函數(shù)的返回碼。負(fù)值代表錯(cuò)誤，正值代表特殊但是正常的事件：

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

壓縮等級(jí)：

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

壓縮策略：

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

data_type域的可能值：

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

deflate壓縮方法（當(dāng)前版本只支持這一個(gè)）：

zlib.Z_DEFLATED

用于初始化zalloc，zfree，opaque：

zlib.Z_NULL