Zlib

Модуль node:zlib предоставляет функциональность сжатия, реализованную с использованием Gzip, Deflate/Inflate, Brotli и Zstd.

Для доступа к нему:

import zlib from 'node:zlib';

const zlib = require('node:zlib');

Сжатие и распаковка построены на основе API потоков Node.js.

Сжать или распаковать поток (например, файл) можно, передав исходный поток через поток zlib Transform в поток назначения:

import {
  createReadStream,
  createWriteStream,
} from 'node:fs';
import process from 'node:process';
import { createGzip } from 'node:zlib';
import { pipeline } from 'node:stream';

const gzip = createGzip();
const source = createReadStream('input.txt');
const destination = createWriteStream('input.txt.gz');

pipeline(source, gzip, destination, (err) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
});

const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const { createGzip } = require('node:zlib');
const { pipeline } = require('node:stream');

const gzip = createGzip();
const source = createReadStream('input.txt');
const destination = createWriteStream('input.txt.gz');

pipeline(source, gzip, destination, (err) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
});

Или с помощью API pipeline на основе промисов:

import {
  createReadStream,
  createWriteStream,
} from 'node:fs';
import { createGzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';

async function do_gzip(input, output) {
  const gzip = createGzip();
  const source = createReadStream(input);
  const destination = createWriteStream(output);
  await pipeline(source, gzip, destination);
}

await do_gzip('input.txt', 'input.txt.gz');

const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const { createGzip } = require('node:zlib');
const { pipeline } = require('node:stream/promises');

async function do_gzip(input, output) {
  const gzip = createGzip();
  const source = createReadStream(input);
  const destination = createWriteStream(output);
  await pipeline(source, gzip, destination);
}

do_gzip('input.txt', 'input.txt.gz')
  .catch((err) => {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  });

Также можно сжать или распаковать данные за один шаг:

import process from 'node:process';
import { Buffer } from 'node:buffer';
import { deflate, unzip } from 'node:zlib';

const input = '.................................';
deflate(input, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
  console.log(buffer.toString('base64'));
});

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64');
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
  console.log(buffer.toString());
});

// Or, Promisified

import { promisify } from 'node:util';
const do_unzip = promisify(unzip);

const unzippedBuffer = await do_unzip(buffer);
console.log(unzippedBuffer.toString());

const { deflate, unzip } = require('node:zlib');

const input = '.................................';
deflate(input, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
  console.log(buffer.toString('base64'));
});

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64');
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  }
  console.log(buffer.toString());
});

// Or, Promisified

const { promisify } = require('node:util');
const do_unzip = promisify(unzip);

do_unzip(buffer)
  .then((buf) => console.log(buf.toString()))
  .catch((err) => {
    console.error('An error occurred:', err);
    process.exitCode = 1;
  });

Использование пула потоков и соображения производительности

Все API zlib, за исключением тех, которые явно являются синхронными, используют внутренний пул потоков 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) => {});
}

В приведенном выше примере одновременно создаются 30 000 экземпляров deflate. Из-за особенностей распределения и освобождения памяти в некоторых операционных системах это может привести к значительной фрагментации памяти.

Настоятельно рекомендуется кэшировать результаты операций сжатия, чтобы избежать дублирования работы.

Сжатие HTTP-запросов и ответов

Модуль node:zlib можно использовать для реализации поддержки механизмов кодирования содержимого gzip, deflate, br и zstd, определенных в HTTP.

Заголовок 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,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;
  }
});

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

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

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

По умолчанию методы 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());
  });
jscopy

Это не изменит поведение в других ситуациях, приводящих к ошибкам, например если входные данные имеют неверный формат. При использовании этого метода нельзя будет определить, закончились ли входные данные преждевременно или в них отсутствуют проверки целостности, поэтому потребуется вручную проверить корректность результата распаковки.

Настройка использования памяти

Для потоков на основе zlib

Из zlib/zconf.h, с изменениями для использования в Node.js:

Требования deflate к памяти (в байтах):

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

То есть: 128 КБ для windowBits = 15 + 128 КБ для memLevel = 8 (значения по умолчанию), а также несколько килобайт для небольших объектов.

Например, чтобы уменьшить требования к памяти по умолчанию с 256 КБ до 128 КБ, следует задать параметры:

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

Однако обычно это приводит к ухудшению сжатия.

Требования inflate к памяти (в байтах) составляют 1 << windowBits. То есть 32 КБ для windowBits = 15 (значение по умолчанию), а также несколько килобайт для небольших объектов.

Кроме того, используется один внутренний буфер выходного блока размером chunkSize; по умолчанию его размер составляет 16 КБ.

На скорость сжатия zlib сильнее всего влияет параметр level. Более высокий уровень обеспечивает лучшее сжатие, но увеличивает время выполнения. Более низкий уровень обеспечивает меньшее сжатие, но работает значительно быстрее.

Как правило, параметры, требующие большего объема памяти, позволяют Node.js реже обращаться к zlib, поскольку за одну операцию write можно обработать больше данных. Таким образом, это еще один фактор, влияющий на скорость, но требующий дополнительной памяти.

Для потоков на основе Brotli

Для потоков на основе Brotli существуют аналоги параметров zlib, хотя диапазоны этих параметров отличаются от диапазонов параметров zlib:

• Параметру level в zlib соответствует параметр BROTLI_PARAM_QUALITY в Brotli.
• Параметру windowBits в zlib соответствует параметр BROTLI_PARAM_LGWIN в Brotli.

Подробнее о параметрах Brotli см. ниже.

Для потоков на основе Zstd

Для потоков на основе Zstd существуют аналоги параметров zlib, хотя диапазоны этих параметров отличаются от диапазонов параметров zlib:

• Параметру level в zlib соответствует параметр ZSTD_c_compressionLevel в Zstd.
• Параметру windowBits в zlib соответствует параметр ZSTD_c_windowLog в Zstd.

Подробнее о параметрах Zstd см. ниже.

Сброс

Вызов .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);

Константы

Константы zlib

Все константы, определенные в zlib.h, также определены в require('node:zlib').constants. При обычной работе использовать эти константы не требуется. Они задокументированы, чтобы их наличие не было неожиданностью. Этот раздел почти полностью взят из документации zlib.

Ранее константы были доступны непосредственно из require('node:zlib'), например zlib.Z_NO_FLUSH. Обращаться к константам непосредственно через модуль по-прежнему можно, но это считается устаревшим.

Допустимые значения сброса.

• zlib.constants.Z_NO_FLUSH
• zlib.constants.Z_PARTIAL_FLUSH
• zlib.constants.Z_SYNC_FLUSH
• zlib.constants.Z_FULL_FLUSH
• zlib.constants.Z_FINISH
• zlib.constants.Z_BLOCK

Коды возврата функций сжатия и распаковки. Отрицательные значения обозначают ошибки, положительные используются для особых, но нормальных событий.

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

Уровни сжатия.

• zlib.constants.Z_NO_COMPRESSION
• zlib.constants.Z_BEST_SPEED
• zlib.constants.Z_BEST_COMPRESSION
• zlib.constants.Z_DEFAULT_COMPRESSION

Стратегия сжатия.

• zlib.constants.Z_FILTERED
• zlib.constants.Z_HUFFMAN_ONLY
• zlib.constants.Z_RLE
• zlib.constants.Z_FIXED
• zlib.constants.Z_DEFAULT_STRATEGY

Константы Brotli

Для потоков на основе Brotli доступны различные параметры и другие константы:

Операции сброса

Для потоков на основе Brotli допустимы следующие значения операций сброса:

• zlib.constants.BROTLI_OPERATION_PROCESS (по умолчанию для всех операций)
• zlib.constants.BROTLI_OPERATION_FLUSH (по умолчанию при вызове .flush())
• zlib.constants.BROTLI_OPERATION_FINISH (по умолчанию для последнего фрагмента)
• zlib.constants.BROTLI_OPERATION_EMIT_METADATA
  • Эту операцию может быть сложно использовать в контексте Node.js, поскольку уровень потоковой передачи затрудняет определение того, какие данные попадут в этот кадр. Кроме того, сейчас нет способа использовать эти данные через API Node.js.

Параметры компрессора

Для кодировщиков Brotli можно задать несколько параметров, влияющих на эффективность и скорость сжатия. И ключи, и значения доступны как свойства объекта zlib.constants.

Наиболее важные параметры:

• BROTLI_PARAM_MODE
  • BROTLI_MODE_GENERIC (по умолчанию)
  • BROTLI_MODE_TEXT, оптимизировано для текста UTF-8
  • BROTLI_MODE_FONT, оптимизировано для шрифтов WOFF 2.0
• BROTLI_PARAM_QUALITY
  • Диапазон от BROTLI_MIN_QUALITY до BROTLI_MAX_QUALITY, значение по умолчанию — BROTLI_DEFAULT_QUALITY.
• BROTLI_PARAM_SIZE_HINT
  • Целочисленное значение, обозначающее ожидаемый размер входных данных; если размер неизвестен, по умолчанию используется 0.

Для расширенного управления алгоритмом сжатия и настройки использования памяти можно задать следующие флаги:

• BROTLI_PARAM_LGWIN
  • Диапазон от BROTLI_MIN_WINDOW_BITS до BROTLI_MAX_WINDOW_BITS, значение по умолчанию — BROTLI_DEFAULT_WINDOW, или до BROTLI_LARGE_MAX_WINDOW_BITS, если установлен флаг BROTLI_PARAM_LARGE_WINDOW.
• BROTLI_PARAM_LGBLOCK
  • Диапазон от BROTLI_MIN_INPUT_BLOCK_BITS до BROTLI_MAX_INPUT_BLOCK_BITS.
• BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING
  • Логический флаг, уменьшающий степень сжатия в пользу скорости распаковки.
• BROTLI_PARAM_LARGE_WINDOW
  • Логический флаг, включающий режим «Brotli с большим окном» (несовместим с форматом Brotli, стандартизированным в RFC 7932).
• BROTLI_PARAM_NPOSTFIX
  • Диапазон от 0 до BROTLI_MAX_NPOSTFIX.
• BROTLI_PARAM_NDIRECT
  • Диапазон от 0 до 15 << NPOSTFIX с шагом 1 << NPOSTFIX.

Параметры декомпрессора

Для управления распаковкой доступны следующие расширенные параметры:

• BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION
  • Логический флаг, влияющий на шаблоны внутреннего распределения памяти.
• BROTLI_DECODER_PARAM_LARGE_WINDOW
  • Логический флаг, включающий режим «Brotli с большим окном» (несовместим с форматом Brotli, стандартизированным в RFC 7932).

Константы Zstd

Для потоков на основе Zstd доступны различные параметры и другие константы:

Операции сброса

Для потоков на основе Zstd допустимы следующие значения операций сброса:

• zlib.constants.ZSTD_e_continue (по умолчанию для всех операций)
• zlib.constants.ZSTD_e_flush (по умолчанию при вызове .flush())
• zlib.constants.ZSTD_e_end (по умолчанию для последнего фрагмента)

Параметры компрессора

Для кодировщиков Zstd можно задать несколько параметров, влияющих на эффективность и скорость сжатия. И ключи, и значения доступны как свойства объекта zlib.constants.

Наиболее важные параметры:

• ZSTD_c_compressionLevel
  • Задает параметры сжатия в соответствии с предопределенной таблицей уровней cLevel. Уровень по умолчанию — ZSTD_CLEVEL_DEFAULT==3.
• ZSTD_c_strategy
  • Выбирает стратегию сжатия.
  • Возможные значения перечислены в разделе параметров стратегии ниже.

Параметры стратегии

Следующие константы можно использовать в качестве значений параметра ZSTD_c_strategy:

• zlib.constants.ZSTD_fast
• zlib.constants.ZSTD_dfast
• zlib.constants.ZSTD_greedy
• zlib.constants.ZSTD_lazy
• zlib.constants.ZSTD_lazy2
• zlib.constants.ZSTD_btlazy2
• zlib.constants.ZSTD_btopt
• zlib.constants.ZSTD_btultra
• zlib.constants.ZSTD_btultra2

Пример:

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

Заявленный размер источника

Ожидаемый общий размер несжатых входных данных можно указать с помощью opts.pledgedSrcSize. Если по окончании обработки размер не совпадет, сжатие завершится с кодом ZSTD_error_srcSize_wrong.

Параметры распаковщика

Доступны следующие расширенные параметры управления распаковкой:

• ZSTD_d_windowLogMax
  • Выберите предельный размер (степени двойки), при превышении которого потоковый API откажется выделять буфер памяти, чтобы защитить хост от чрезмерных требований к памяти.

Класс: 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,
  },
});
jscopy

Класс: 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

Распаковывает поток raw deflate.

Класс: zlib.Unzip

• Расширяет: ZlibBase

Распаковывает поток, сжатый с помощью Gzip или Deflate, автоматически определяя заголовок.

Класс: zlib.ZlibBase

• Расширяет: stream.Transform

Не экспортируется модулем node:zlib. Этот класс описан здесь, поскольку он является базовым классом классов сжатия и распаковки.

Этот класс наследует stream.Transform, что позволяет использовать объекты node:zlib в конвейерах и других подобных операциях с потоками.

zlib.bytesWritten

• Тип: <number>

Свойство zlib.bytesWritten указывает количество байтов, записанных в обработчик до их обработки (сжатия или распаковки, в зависимости от производного класса).

zlib.close([callback])

• callback <Function>

Закрывает базовый дескриптор.

zlib.flush([kind, ]callback)

• kind По умолчанию: zlib.constants.Z_FULL_FLUSH для потоков на основе zlib, zlib.constants.BROTLI_OPERATION_FLUSH для потоков на основе Brotli.
• callback <Function>

Сбрасывает ожидающие данные. Не вызывайте этот метод без необходимости: преждевременный сброс отрицательно влияет на эффективность алгоритма сжатия.

При вызове данные сбрасываются только из внутреннего состояния zlib, а на уровне потоков никакой сброс не выполняется. Метод ведёт себя как обычный вызов .write(): он ставится в очередь после других ожидающих операций записи и выдаёт результат только при чтении данных из потока.

zlib.params(level, strategy, callback)

• level <integer>
• strategy <integer>
• callback <Function>

Эта функция доступна только для потоков на основе zlib, то есть не для Brotli.

Динамически обновляет уровень и стратегию сжатия. Применяется только к алгоритму deflate.

zlib.reset()

Сбрасывает компрессор или распаковщик до заводских настроек. Применяется только к алгоритмам inflate и deflate.

Класс: 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,
  },
});
jscopy

Класс: 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-разрядное беззнаковое целое число, содержащее контрольную сумму.

Вычисляет 32-разрядную контрольную сумму циклического избыточного кода для data. Если задано value, оно используется как начальное значение контрольной суммы; в противном случае в качестве начального значения используется 0.

Алгоритм CRC предназначен для вычисления контрольных сумм и обнаружения ошибок при передаче данных. Он не подходит для криптографической аутентификации.

Для совместимости с другими API, если data является строкой, перед вычислением она будет закодирована в UTF-8. Если пользователи используют только Node.js для вычисления и проверки контрольных сумм, это хорошо работает с другими API, которые по умолчанию используют кодировку UTF-8.

Некоторые сторонние библиотеки JavaScript вычисляют контрольную сумму строки на основе str.charCodeAt(), чтобы их можно было запускать в браузерах. Чтобы сопоставить контрольную сумму, вычисленную такой библиотекой в браузере, лучше использовать ту же библиотеку в Node.js, если она также запускается в Node.js. Если для сопоставления контрольной суммы, полученной такой сторонней библиотекой, пользователям необходимо использовать zlib.crc32():

1. Если библиотека принимает Uint8Array в качестве входных данных, используйте TextEncoder в браузере, чтобы закодировать строку в Uint8Array с кодировкой UTF-8, и вычислите контрольную сумму на основе строки, закодированной в 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);  // 4150509955

const 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);  // 4150509955

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 изменилось поведение, когда для потоков raw deflate значение windowBits установлено в 8. zlib автоматически устанавливал windowBits в 9, если изначально оно было установлено в 8. Новые версии 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> или строку, второй необязательный аргумент для передачи параметров классам zlib и вызывают переданную функцию обратного вызова с callback(error, result).

Для каждого метода существует вариант *Sync, который принимает те же аргументы, но без функции обратного вызова.

zlib.brotliCompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliCompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

Сжимает фрагмент данных с помощью BrotliCompress.

zlib.brotliDecompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>
• callback <Function>

zlib.brotliDecompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <brotli options>

Распаковывает фрагмент данных с помощью BrotliDecompress.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.deflateSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Сжать фрагмент данных с помощью Deflate.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.deflateRawSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Сжать фрагмент данных с помощью DeflateRaw.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.gunzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Распаковать фрагмент данных с помощью Gunzip.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.gzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Сжать фрагмент данных с помощью Gzip.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.inflateSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Распаковать фрагмент данных с помощью Inflate.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.inflateRawSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Распаковывает фрагмент данных с помощью InflateRaw.

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

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>
• callback <Function>

zlib.unzipSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zlib options>

Распаковывает фрагмент данных с помощью Unzip.

zlib.zstdCompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zstd options>
• callback <Function>

zlib.zstdCompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zstd options>

Сжимает фрагмент данных с помощью ZstdCompress.

zlib.zstdDecompress(buffer[, options], callback)

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zstd options>
• callback <Function>

zlib.zstdDecompressSync(buffer[, options])

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <zstd options>

Распаковывает фрагмент данных с помощью ZstdDecompress.

Сжатие итерируемых потоков

Модуль node:zlib/iter предоставляет преобразования для сжатия и распаковки, предназначенные для использования с API node:stream/iter итерируемых потоков.

Этот модуль доступен только при включенном флаге командной строки --experimental-stream-iter.

Для каждого алгоритма предусмотрены асинхронный вариант (состоящий из асинхронного генератора с сохранением состояния, предназначенного для использования с pull() и pipeTo()) и синхронный вариант (состоящий из синхронного генератора с сохранением состояния, предназначенного для использования с pullSync() и pipeToSync()).

Асинхронные преобразования выполняют сжатие в пуле потоков libuv, перекрывая операции ввода-вывода с выполнением JavaScript. Синхронные преобразования выполняют сжатие непосредственно в основном потоке.

Примечание. Значения по умолчанию для этих преобразований настроены для пропускной способности потоковой передачи и отличаются от значений по умолчанию в node:zlib. В частности, для gzip/deflate по умолчанию установлен уровень 4 (а не 6) и memLevel 9 (а не 8), а для Brotli — качество 6 (а не 11). Эти значения соответствуют распространенным конфигурациям HTTP-серверов и обеспечивают значительно более быстрое сжатие при лишь небольшом снижении коэффициента сжатия. Все значения по умолчанию можно переопределить с помощью параметров.

import { from, pull, bytes, text } from 'node:stream/iter';
import { compressGzip, decompressGzip } from 'node:zlib/iter';

// Async round-trip
const compressed = await bytes(pull(from('hello'), compressGzip()));
const original = await text(pull(from(compressed), decompressGzip()));
console.log(original); // 'hello'

const { from, pull, bytes, text } = require('node:stream/iter');
const { compressGzip, decompressGzip } = require('node:zlib/iter');

async function run() {
  const compressed = await bytes(pull(from('hello'), compressGzip()));
  const original = await text(pull(from(compressed), decompressGzip()));
  console.log(original); // 'hello'
}

run().catch(console.error);

import { fromSync, pullSync, textSync } from 'node:stream/iter';
import { compressGzipSync, decompressGzipSync } from 'node:zlib/iter';

// Sync round-trip
const compressed = pullSync(fromSync('hello'), compressGzipSync());
const original = textSync(pullSync(compressed, decompressGzipSync()));
console.log(original); // 'hello'

const { fromSync, pullSync, textSync } = require('node:stream/iter');
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');

const compressed = pullSync(fromSync('hello'), compressGzipSync());
const original = textSync(pullSync(compressed, decompressGzipSync()));
console.log(original); // 'hello'

compressBrotli([options])

compressBrotliSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • params <Object> Объект «ключ-значение», где ключи и значения — это элементы zlib.constants. Наиболее важные параметры компрессора:
    • BROTLI_PARAM_MODE — BROTLI_MODE_GENERIC (по умолчанию), BROTLI_MODE_TEXT или BROTLI_MODE_FONT.
    • BROTLI_PARAM_QUALITY — принимает значения от BROTLI_MIN_QUALITY до BROTLI_MAX_QUALITY. По умолчанию: 6 (не BROTLI_DEFAULT_QUALITY, значение которого равно 11). Качество 6 подходит для потоковой передачи; качество 11 предназначено для сжатия в автономном режиме или во время сборки.
    • BROTLI_PARAM_SIZE_HINT — ожидаемый размер входных данных. По умолчанию: 0 (неизвестен).
    • BROTLI_PARAM_LGWIN — размер окна (log2). По умолчанию: 20 (1 МБ). Значение по умолчанию в библиотеке Brotli равно 22 (4 МБ); уменьшенное значение по умолчанию экономит память, не оказывая существенного влияния на сжатие при потоковой обработке.
    • BROTLI_PARAM_LGBLOCK — размер входного блока (log2). Полный список см. в разделе параметров компрессора Brotli в документации по zlib.
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> преобразование с сохранением состояния.

Создает преобразование для сжатия Brotli. Выходные данные совместимы с zlib.brotliDecompress() и decompressBrotli()/decompressBrotliSync().

compressDeflate([options])

compressDeflateSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • level <number> Уровень сжатия (0–9). По умолчанию: 4.
  • windowBits <number> По умолчанию: Z_DEFAULT_WINDOWBITS (15).
  • memLevel <number> По умолчанию: 9.
  • strategy <number> По умолчанию: Z_DEFAULT_STRATEGY.
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> преобразование с сохранением состояния.

Создает преобразование для сжатия deflate. Выходные данные совместимы с zlib.inflate() и decompressDeflate()/decompressDeflateSync().

compressGzip([options])

compressGzipSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • level <number> Уровень сжатия (0-9). По умолчанию: 4.
  • windowBits <number> По умолчанию: Z_DEFAULT_WINDOWBITS (15).
  • memLevel <number> По умолчанию: 9.
  • strategy <number> По умолчанию: Z_DEFAULT_STRATEGY.
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для сжатия gzip. Выходные данные совместимы с zlib.gunzip() и decompressGzip()/decompressGzipSync().

compressZstd([options])

compressZstdSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • params <Object> Объект «ключ-значение», в котором ключи и значения являются записями zlib.constants. Наиболее важные параметры компрессора:
    • ZSTD_c_compressionLevel -- По умолчанию: ZSTD_CLEVEL_DEFAULT (3).
    • ZSTD_c_checksumFlag -- генерировать контрольную сумму. По умолчанию: 0.
    • ZSTD_c_strategy -- стратегия сжатия. Возможные значения: ZSTD_fast, ZSTD_dfast, ZSTD_greedy, ZSTD_lazy, ZSTD_lazy2, ZSTD_btlazy2, ZSTD_btopt, ZSTD_btultra, ZSTD_btultra2. Полный список см. в разделе параметры компрессора Zstd документации по zlib.
  • pledgedSrcSize <number> Ожидаемый размер несжатых данных (необязательная подсказка).
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для сжатия Zstandard. Выходные данные совместимы с zlib.zstdDecompress() и decompressZstd()/decompressZstdSync().

decompressBrotli([options])

decompressBrotliSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • params <Object> Объект «ключ-значение», в котором ключи и значения являются записями zlib.constants. Доступные параметры декомпрессора:
    • BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION -- логический флаг, влияющий на внутреннее выделение памяти.
    • BROTLI_DECODER_PARAM_LARGE_WINDOW -- логический флаг, включающий режим «Brotli с большим окном» (несовместимый с RFC 7932). Подробности см. в разделе параметры декомпрессора Brotli документации по zlib.
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для распаковки Brotli.

decompressDeflate([options])

decompressDeflateSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • windowBits <number> По умолчанию: Z_DEFAULT_WINDOWBITS (15).
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для распаковки deflate.

decompressGzip([options])

decompressGzipSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • windowBits <number> По умолчанию: Z_DEFAULT_WINDOWBITS (15).
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для распаковки gzip.

decompressZstd([options])

decompressZstdSync([options])

• options <Object>
  • chunkSize <number> Размер выходного буфера. По умолчанию: 65536 (64 КБ).
  • params <Object> Объект «ключ-значение», в котором ключи и значения являются записями zlib.constants. Доступные параметры декомпрессора:
    • ZSTD_d_windowLogMax -- максимальный размер окна (log2), выделяемого декомпрессором. Ограничивает использование памяти для защиты от вредоносных входных данных. Подробности см. в разделе параметры декомпрессора Zstd документации по zlib.
  • dictionary <Buffer> | <TypedArray> | <DataView>
• Возвращает: <Object> Преобразователь с сохранением состояния.

Создаёт преобразователь для распаковки Zstandard.