Node.js v25.0.0 ドキュメンテーション

スレッドプールの使用とパフォーマンスに関する考慮事項#

明示的に同期的なものを除き、すべての zlib API は Node.js の内部スレッドプールを使用します。これにより、一部のアプリケーションでは予期しない影響やパフォーマンスの制限が生じる可能性があります。

多数のzlibオブジェクトを同時に作成して使用すると、深刻なメモリ断片化を引き起こす可能性があります。

import zlib from 'node:zlib';
import { Buffer } from 'node:buffer';

const payload = Buffer.from('This is some data');

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {});
}const zlib = require('node:zlib');

const payload = Buffer.from('This is some data');

// WARNING: DO NOT DO THIS!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {});
}copy

上記の例では、30,000個の deflate インスタンスが同時に作成されます。一部のオペレーティングシステムのメモリ割り当てと解放の処理方法により、これは深刻なメモリ断片化につながる可能性があります。

作業の重複を避けるために、圧縮操作の結果をキャッシュすることを強くお勧めします。

HTTPリクエストとレスポンスの圧縮#

node:zlib モジュールは、HTTPで定義されている gzip、deflate、br、および zstd コンテンツエンコーディングメカニズムのサポートを実装するために使用できます。

HTTP の Accept-Encoding ヘッダは、クライアントが受け入れる圧縮エンコーディングを特定するために HTTP リクエスト内で使用されます。Content-Encoding ヘッダは、メッセージに実際に適用された圧縮エンコーディングを特定するために使用されます。

以下に示す例は、基本的な概念を示すために大幅に簡略化されています。zlibエンコーディングの使用はコストがかかる場合があるため、結果はキャッシュされるべきです。zlib の使用に伴う速度/メモリ/圧縮のトレードオフに関する詳細については、メモリ使用量のチューニング を参照してください。

// Client request example
import fs from 'node:fs';
import zlib from 'node:zlib';
import http from 'node:http';
import process from 'node:process';
import { pipeline } from 'node:stream';

const request = http.get({ host: 'example.com',
                           path: '/',
                           port: 80,
                           headers: { 'Accept-Encoding': 'br,gzip,deflate' } });
request.on('response', (response) => {
  const output = fs.createWriteStream('example.com_index.html');

  const onError = (err) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
  };

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError);
      break;
    // Or, just use zlib.createUnzip() to handle both of the following cases:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError);
      break;
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError);
      break;
    default:
      pipeline(response, output, onError);
      break;
  }
});// Client request example
const zlib = require('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node:stream');

const request = http.get({ host: 'example.com',
                           path: '/',
                           port: 80,
                           headers: { 'Accept-Encoding': 'br,gzip,deflate,zstd' } });
request.on('response', (response) => {
  const output = fs.createWriteStream('example.com_index.html');

  const onError = (err) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
  };

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError);
      break;
    // Or, just use zlib.createUnzip() to handle both of the following cases:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError);
      break;
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError);
      break;
    case 'zstd':
      pipeline(response, zlib.createZstdDecompress(), output, onError);
      break;
    default:
      pipeline(response, output, onError);
      break;
  }
});copy

// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
import zlib from 'node:zlib';
import http from 'node:http';
import fs from 'node:fs';
import { pipeline } from 'node:stream';

http.createServer((request, response) => {
  const raw = fs.createReadStream('index.html');
  // Store both a compressed and an uncompressed version of the resource.
  response.setHeader('Vary', 'Accept-Encoding');
  const acceptEncoding = request.headers['accept-encoding'] || '';

  const onError = (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      response.end();
      console.error('An error occurred:', err);
    }
  };

  // Note: This is not a conformant accept-encoding parser.
  // See https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (/\bdeflate\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'deflate' });
    pipeline(raw, zlib.createDeflate(), response, onError);
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'gzip' });
    pipeline(raw, zlib.createGzip(), response, onError);
  } else if (/\bbr\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'br' });
    pipeline(raw, zlib.createBrotliCompress(), response, onError);
  } else {
    response.writeHead(200, {});
    pipeline(raw, response, onError);
  }
}).listen(1337);// server example
// Running a gzip operation on every request is quite expensive.
// It would be much more efficient to cache the compressed buffer.
const zlib = require('node:zlib');
const http = require('node:http');
const fs = require('node:fs');
const { pipeline } = require('node:stream');

http.createServer((request, response) => {
  const raw = fs.createReadStream('index.html');
  // Store both a compressed and an uncompressed version of the resource.
  response.setHeader('Vary', 'Accept-Encoding');
  const acceptEncoding = request.headers['accept-encoding'] || '';

  const onError = (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      response.end();
      console.error('An error occurred:', err);
    }
  };

  // Note: This is not a conformant accept-encoding parser.
  // See https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3
  if (/\bdeflate\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'deflate' });
    pipeline(raw, zlib.createDeflate(), response, onError);
  } else if (/\bgzip\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'gzip' });
    pipeline(raw, zlib.createGzip(), response, onError);
  } else if (/\bbr\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'br' });
    pipeline(raw, zlib.createBrotliCompress(), response, onError);
  } else if (/\bzstd\b/.test(acceptEncoding)) {
    response.writeHead(200, { 'Content-Encoding': 'zstd' });
    pipeline(raw, zlib.createZstdCompress(), response, onError);
  } else {
    response.writeHead(200, {});
    pipeline(raw, response, onError);
  }
}).listen(1337);copy

デフォルトでは、zlib メソッドは切り捨てられたデータを伸張する際にエラーをスローします。しかし、データが不完全であることがわかっている場合や、圧縮ファイルの先頭部分のみを検査したい場合は、入力データの最後のチャンクを伸張するために使用されるフラッシュメソッドを変更することで、デフォルトのエラー処理を抑制することが可能です。

// This is a truncated version of the buffer from the above examples
const buffer = Buffer.from('eJzT0yMA', 'base64');

zlib.unzip(
  buffer,
  // For Brotli, the equivalent is zlib.constants.BROTLI_OPERATION_FLUSH.
  // For Zstd, the equivalent is zlib.constants.ZSTD_e_flush.
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (err) {
      console.error('An error occurred:', err);
      process.exitCode = 1;
    }
    console.log(buffer.toString());
  }); copy

これは、入力データが無効な形式である場合など、他のエラーをスローする状況での動作は変更しません。この方法を使用すると、入力が途中で終了したのか、整合性チェックが欠けているのかを判断できなくなるため、伸張された結果が有効であることを手動で確認する必要があります。

メモリ使用量のチューニング#

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

const options = { windowBits: 14, memLevel: 7 }; copy

フラッシュ#

圧縮ストリームで .flush() を呼び出すと、zlib は現在可能な限り多くの出力を返します。これは圧縮品質の低下を犠牲にする可能性がありますが、データをできるだけ早く利用可能にする必要がある場合に役立ちます。

次の例では、flush() を使用して、圧縮された部分的なHTTPレスポンスをクライアントに書き込みます。

import zlib from 'node:zlib';
import http from 'node:http';
import { pipeline } from 'node:stream';

http.createServer((request, response) => {
  // For the sake of simplicity, the Accept-Encoding checks are omitted.
  response.writeHead(200, { 'content-encoding': 'gzip' });
  const output = zlib.createGzip();
  let i;

  pipeline(output, response, (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      clearInterval(i);
      response.end();
      console.error('An error occurred:', err);
    }
  });

  i = setInterval(() => {
    output.write(`The current time is ${Date()}\n`, () => {
      // The data has been passed to zlib, but the compression algorithm may
      // have decided to buffer the data for more efficient compression.
      // Calling .flush() will make the data available as soon as the client
      // is ready to receive it.
      output.flush();
    });
  }, 1000);
}).listen(1337);const zlib = require('node:zlib');
const http = require('node:http');
const { pipeline } = require('node:stream');

http.createServer((request, response) => {
  // For the sake of simplicity, the Accept-Encoding checks are omitted.
  response.writeHead(200, { 'content-encoding': 'gzip' });
  const output = zlib.createGzip();
  let i;

  pipeline(output, response, (err) => {
    if (err) {
      // If an error occurs, there's not much we can do because
      // the server has already sent the 200 response code and
      // some amount of data has already been sent to the client.
      // The best we can do is terminate the response immediately
      // and log the error.
      clearInterval(i);
      response.end();
      console.error('An error occurred:', err);
    }
  });

  i = setInterval(() => {
    output.write(`The current time is ${Date()}\n`, () => {
      // The data has been passed to zlib, but the compression algorithm may
      // have decided to buffer the data for more efficient compression.
      // Calling .flush() will make the data available as soon as the client
      // is ready to receive it.
      output.flush();
    });
  }, 1000);
}).listen(1337);copy

定数#

const stream = zlib.createZstdCompress({
  params: {
    [zlib.constants.ZSTD_c_strategy]: zlib.constants.ZSTD_btultra,
  },
}); copy

クラス: Options#

各zlibベースのクラスは options オブジェクトを取ります。オプションは必須ではありません。

一部のオプションは圧縮時にのみ関連し、伸張クラスでは無視されます。

• flush <integer> デフォルト: zlib.constants.Z_NO_FLUSH
• finishFlush <integer> デフォルト: zlib.constants.Z_FINISH
• chunkSize <integer> デフォルト: 16 * 1024
• windowBits <integer>
• level <integer> (圧縮のみ)
• memLevel <integer> (圧縮のみ)
• strategy <integer> (圧縮のみ)
• dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> (deflate/inflateのみ、デフォルトは空の辞書)
• info <boolean> (true の場合、buffer と engine を持つオブジェクトを返します。)
• maxOutputLength <integer> 便利なメソッドを使用する際の出力サイズを制限します。デフォルト: buffer.kMaxLength

詳細については、deflateInit2 と inflateInit2 のドキュメントを参照してください。

クラス: BrotliOptions#

各Brotliベースのクラスは options オブジェクトを取ります。すべてのオプションは任意です。

• flush <integer> デフォルト: zlib.constants.BROTLI_OPERATION_PROCESS
• finishFlush <integer> デフォルト: zlib.constants.BROTLI_OPERATION_FINISH
• chunkSize <integer> デフォルト: 16 * 1024
• params <Object> インデックス付けされた Brotliパラメータを含むキーと値のオブジェクト。
• maxOutputLength <integer> 便利なメソッドを使用する際の出力サイズを制限します。デフォルト: buffer.kMaxLength
• info <boolean> true の場合、buffer と engine を持つオブジェクトを返します。デフォルト: false

例:

const stream = zlib.createBrotliCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
    [zlib.constants.BROTLI_PARAM_QUALITY]: 4,
    [zlib.constants.BROTLI_PARAM_SIZE_HINT]: fs.statSync(inputFile).size,
  },
}); copy

クラス: zlib.BrotliCompress#

• 継承: ZlibBase

Brotliアルゴリズムを使用してデータを圧縮します。

クラス: zlib.BrotliDecompress#

• 継承: ZlibBase

Brotliアルゴリズムを使用してデータを伸張します。

クラス: zlib.Deflate#

• 継承: ZlibBase

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

クラス: zlib.DeflateRaw#

• 継承: ZlibBase

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

クラス: zlib.Gunzip#

• 継承: ZlibBase

gzipストリームを伸張します。

クラス: zlib.Gzip#

• 継承: ZlibBase

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

クラス: zlib.Inflate#

• 継承: ZlibBase

deflateストリームを伸張します。

クラス: zlib.InflateRaw#

• 継承: ZlibBase

生のdeflateストリームを伸張します。

クラス: zlib.Unzip#

• 継承: ZlibBase

ヘッダを自動検出して、GzipまたはDeflateで圧縮されたストリームを伸張します。

クラス: zlib.ZlibBase#

• 継承: stream.Transform

node:zlib モジュールによってエクスポートされません。これは圧縮/伸張クラスの基底クラスであるため、ここに文書化されています。

このクラスは stream.Transform を継承しているため、node:zlib オブジェクトをパイプや同様のストリーム操作で使用できます。

クラス: ZstdOptions#

各Zstdベースのクラスは options オブジェクトを取ります。すべてのオプションは任意です。

• flush <integer> デフォルト: zlib.constants.ZSTD_e_continue
• finishFlush <integer> デフォルト: zlib.constants.ZSTD_e_end
• chunkSize <integer> デフォルト: 16 * 1024
• params <Object> インデックス付けされた Zstdパラメータを含むキーと値のオブジェクト。
• maxOutputLength <integer> 便利なメソッドを使用する際の出力サイズを制限します。デフォルト: buffer.kMaxLength
• info <boolean> true の場合、buffer と engine を持つオブジェクトを返します。デフォルト: false
• dictionary <Buffer> 辞書と共通のパターンを共有するデータを圧縮または伸張する際に、圧縮効率を向上させるために使用されるオプションの辞書。

例:

const stream = zlib.createZstdCompress({
  chunkSize: 32 * 1024,
  params: {
    [zlib.constants.ZSTD_c_compressionLevel]: 10,
    [zlib.constants.ZSTD_c_checksumFlag]: 1,
  },
}); copy

クラス: zlib.ZstdCompress#

Zstdアルゴリズムを使用してデータを圧縮します。

クラス: zlib.ZstdDecompress#

Zstdアルゴリズムを使用してデータを伸張します。

zlib.constants#

Zlib関連の定数を列挙したオブジェクトを提供します。

zlib.crc32(data[, value])#

• data <string> | <Buffer> | <TypedArray> | <DataView> data が文字列の場合、計算に使用される前にUTF-8としてエンコードされます。
• value <integer> オプションの開始値。32ビット符号なし整数でなければなりません。デフォルト: 0
• 戻り値: <integer> チェックサムを含む32ビット符号なし整数。

data の32ビット巡回冗長検査チェックサムを計算します。value が指定されている場合、それがチェックサムの開始値として使用されます。それ以外の場合は、0が開始値として使用されます。

CRCアルゴリズムは、チェックサムを計算し、データ送信中のエラーを検出するために設計されています。暗号認証には適していません。

他のAPIとの一貫性を保つため、data が文字列の場合、計算に使用される前にUTF-8でエンコードされます。ユーザーがNode.jsのみを使用してチェックサムを計算し、照合する場合、これはデフォルトでUTF-8エンコーディングを使用する他のAPIとうまく機能します。

一部のサードパーティJavaScriptライブラリは、ブラウザで実行できるように、str.charCodeAt() に基づいて文字列のチェックサムを計算します。ユーザーがブラウザでこの種のライブラリで計算されたチェックサムと一致させたい場合、そのライブラリがNode.jsでも実行可能であれば、Node.jsで同じライブラリを使用する方が良いでしょう。ユーザーがそのようなサードパーティライブラリによって生成されたチェックサムと一致させるために zlib.crc32() を使用する必要がある場合：

1. ライブラリが入力として Uint8Array を受け入れる場合、ブラウザで TextEncoder を使用して文字列をUTF-8エンコーディングの Uint8Array にエンコードし、ブラウザでUTF-8エンコードされた文字列に基づいてチェックサムを計算します。
2. ライブラリが文字列のみを受け入れ、str.charCodeAt() に基づいてデータを計算する場合、Node.js側で、Buffer.from(str, 'utf16le') を使用して文字列をバッファに変換します。

import zlib from 'node:zlib';
import { Buffer } from 'node:buffer';

let crc = zlib.crc32('hello');  // 907060870
crc = zlib.crc32('world', crc);  // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le'));  // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc);  // 4150509955const zlib = require('node:zlib');
const { Buffer } = require('node:buffer');

let crc = zlib.crc32('hello');  // 907060870
crc = zlib.crc32('world', crc);  // 4192936109

crc = zlib.crc32(Buffer.from('hello', 'utf16le'));  // 1427272415
crc = zlib.crc32(Buffer.from('world', 'utf16le'), crc);  // 4150509955copy

zlib.createBrotliCompress([options])#

• options <brotli options>

新しい BrotliCompress オブジェクトを作成して返します。

zlib.createBrotliDecompress([options])#

• options <brotli options>

新しい BrotliDecompress オブジェクトを作成して返します。

zlib.createDeflate([options])#

• options <zlib options>

新しい Deflate オブジェクトを作成して返します。

zlib.createDeflateRaw([options])#

• options <zlib options>

新しい DeflateRaw オブジェクトを作成して返します。

zlibを1.2.8から1.2.11にアップグレードした際、生のdeflateストリームで windowBits が8に設定されたときの動作が変更されました。zlibは、当初8に設定されていた場合、windowBits を自動的に9に設定していました。新しいバージョンのzlibは例外をスローするため、Node.jsは8の値を9にアップグレードするという元の動作を復元しました。これは、windowBits = 9 をzlibに渡すと、実際には8ビットウィンドウを効果的に使用する圧縮ストリームが生成されるためです。

zlib.createGunzip([options])#

• options <zlib options>

新しい Gunzip オブジェクトを作成して返します。

zlib.createGzip([options])#

• options <zlib options>

新しい Gzip オブジェクトを作成して返します。例を参照してください。

zlib.createInflate([options])#

• options <zlib options>

新しい Inflate オブジェクトを作成して返します。

zlib.createInflateRaw([options])#

• options <zlib options>

新しい InflateRaw オブジェクトを作成して返します。

zlib.createUnzip([options])#

• options <zlib options>

新しい Unzip オブジェクトを作成して返します。

zlib.createZstdCompress([options])#

• options <zstd options>

新しい ZstdCompress オブジェクトを作成して返します。

zlib.createZstdDecompress([options])#

• options <zstd options>

新しい ZstdDecompress オブジェクトを作成して返します。

便利なメソッド#

これらはすべて、最初の引数として <Buffer>、<TypedArray>、<DataView>、<ArrayBuffer>、または文字列を受け取り、オプションの2番目の引数で zlib クラスにオプションを提供し、指定されたコールバックを callback(error, result) で呼び出します。

すべてのメソッドには、同じ引数をコールバックなしで受け入れる *Sync 版があります。