Node.js v0.11.11 マニュアル & ドキュメンテーション

Index | View on single page | View as JSON

Zlib

Zlib#

Stability: 3 - Stable

このモジュールは次のようにアクセスできます。

var zlib = require('zlib');

これは Gzip/Gunzip、Deflate/Inflate、そして DeflateRaw/InflateRaw へバインディングするクラスを提供します。どのクラスも同じオプションを持つ、読み込みと書き込みが可能なストリームです。

Examples#

ファイルを圧縮および解凍するには、fs.ReadStream から zlib へ、そして 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);

データの圧縮または解凍は簡易メソッドを使うことにより、ワンステップで行うことができます。

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 クライアントとサーバで使うには、リクエストに accept-encoding ヘッダを、レスポンスに content-encoding ヘッダを使用します。

注意: これらのサンプルは基本コンセプトを見せるためにとても単純化されています。 Zlib エンコーディングは高価なので、結果はキャッシュされるべきです。 zlibの使い方に関する速度／メモリ／圧縮率のトレードオフについてより詳しくは、後述の Memory Usage Tuning を参照してください。

// 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])#

options によって作られた新しい Gzip オブジェクトを返します。

zlib.createGunzip([options])#

options によって作られた新しい Gunzip オブジェクトを返します。

zlib.createDeflate([options])#

options によって作られた新しい Deflate オブジェクトを返します。

zlib.createInflate([options])#

options によって作られた新しい Inflate オブジェクトを返します。

zlib.createDeflateRaw([options])#

options によって作られた新しい DeflateRaw オブジェクトを返します。

zlib.createInflateRaw([options])#

options によって作られた新しい InflateRaw オブジェクトを返します。

zlib.createUnzip([options])#

options によって作られた新しい Unzip オブジェクトを返します。

Class: zlib.Zlib#

zlib モジュールによって公開されてはいません。ここで文書化するのは圧縮／解凍クラスのベースクラスだからです。

zlib.flush([kind], callback)#

kind のデフォルトは zlib.Z_FULL_FLUSH です。

保留中のデータをフラッシュします。これを気軽に呼び出さないでください、性急なフラッシュは圧縮アルゴリズムにネガティブな影響を与えます。

zlib.params(level, strategy, callback)#

圧縮のレベルと戦略を動的に更新します。 deflate アルゴリズムにだけ適用されます。

zlib.reset()#

圧縮／解凍をファクトリのデフォルトにリセットします。 inflate および deflate アルゴリズムにのみ効果があります。

Class: zlib.Gzip#

gzip を使ってデータを圧縮します。

Class: zlib.Gunzip#

gzip ストリームを解凍します。

Class: zlib.Deflate#

deflate を使ってデータを圧縮します。

Class: zlib.Inflate#

deflate ストリームを解凍します。

Class: zlib.DeflateRaw#

deflate を使ってデータを圧縮しますが、zlib ヘッダを付加しません。

Class: zlib.InflateRaw#

生の deflate ストリームを解凍します。

Class: zlib.Unzip#

Gzip または Deflate で圧縮されたストリームをヘッダで自動判別して解凍します。

Convenience Methods#

これらは全て第 1 引数として文字列またはバッファを、任意の第 2 引数で zlib クラスのオプションを受け取り、与えられたコールバック callback(error, result) を呼び出します。

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

Deflate で文字列を圧縮します。

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

DeflateRaw で文字列を圧縮します。

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

Gzip で文字列を圧縮します。

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

Gunzip で生のバッファを解凍します。

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

Inflate で生のバッファを解凍します。

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

InflateRaw で生のバッファを解凍します。

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

Unzip で生のバッファを解凍します。

Options#

どのクラスもオプションオブジェクトを受け取ります。全てのオプションは任意です

いくつかのオプションは圧縮にだけ関連し、解凍するクラスでは無視されることに注意してください。

flush (デフォルト: zlib.Z_NO_FLUSH)
chunkSize (デフォルト: 16*1024)
windowBits
level (圧縮のみ)
memLevel (圧縮のみ)
strategy (圧縮のみ)
dictionary (deflate/inflate のみ、デフォルトは空の辞書です)

これらの詳細は http://zlib.net/manual.html#Advanced の deflateInit2 および inflateInit2 の説明を参照してください。

Memory Usage Tuning#

node は zlib/zconf.h を変更して使っています:

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

すなわち: windowBits = 15 の場合 128K + memLevel = 8 の場合 128K (デフォルト値) に加えて数キロバイトが小さなオブジェクトのために使われます。

たとえば、デフォルトで要求されるメモリを 256K から 128K へ縮小したければ、次のオプションを設定します:

{ windowBits: 14, memLevel: 7 }

もちろん、これは圧縮率を悪化します (ただ飯ははありません)。

1 << windowBits

この場合、windowBits=15 (デフォルト値) の場合 32K に加えて数キロバイトが小さなオブジェクトのために使われます。

これは、デフォルト値 16K の chunkSize で指定されたサイズの内部バッファに加えられます。

zlib の圧縮速度は level の設定で劇的に変化します高レベルにするとより圧縮できますが、完了までの時間が長くなります。低レベルにするとあまり圧縮されませんが、高速になります。

一般的に、メモリをより多く使うオプションにすると node が zlib を呼び出す回数が少なくなることを意味し、一回の write 操作でより多くのデータを処理できることになります。これはあスピードに影響するもう一つのファクタで、メモリ使用量を犠牲にします。

Constants#

zlib.h に定義された定数は require('zlib') でも定義されます。通常の使い方ではこれらを設定する必要はありません。それが存在することで驚かれないように、これらはドキュメント化されます。このセクションのほとんどは zlib documentation から直接得ることができます。より詳細は 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

圧縮／解凍関数のリターンコード。負数はエラー、正数は正常なイベントの特別な場合に使われます。

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

圧縮レベル。

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 の圧縮方法 (このバージョンでは一つだけがサポートされます)。

zlib.Z_DEFLATED

zalloc、zfree、opaque の初期化用。

zlib.Z_NULL

Table of Contents