Spec-Zone.ru › Node.js 24 LTS

Zlib

Стабильность: 2 - Стабильный

Исходный код: lib/zlib.js

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

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

Модули JavaScript
import zlib from 'node:zlib';
CommonJS
const zlib = require('node:zlib');

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

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

Модули JavaScript
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;
  }
});
CommonJS
const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const process = require('node:process');
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 для работы с промисами:

Модули JavaScript
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');
CommonJS
const {
  createReadStream,
  createWriteStream,
} = require('node:fs');
const process = require('node:process');
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;
  });

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

Модули JavaScript
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());
CommonJS
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 может вызвать значительную фрагментацию памяти.

Модули JavaScript
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) => {});
}
CommonJS
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 см. в разделе Настройка использования памяти.

Модули JavaScript
// 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;
  }
});
CommonJS
// 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;
  }
});
Модули JavaScript
// 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);
CommonJS
// 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());
  }); copy

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

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

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

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

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

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

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

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

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

Однако обычно это ухудшает сжатие.

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

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

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

В целом, при увеличении параметров использования памяти Node.js реже обращается к zlib, поскольку за одну операцию write можно обработать больше данных. Это ещё один фактор, влияющий на скорость за счёт увеличения расхода памяти.

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

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

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

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

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

Стабильность: 1 - Экспериментальный

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

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

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

Сброс

Вызов .flush() для потока сжатия заставит zlib вернуть максимально возможный на данный момент объём выходных данных. Это может снизить качество сжатия, но бывает полезно, когда данные необходимо получить как можно скорее.

В следующем примере flush() используется для отправки клиенту частичного сжатого HTTP-ответа:

Модули JavaScript
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);
CommonJS
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);

Константы

Добавлено в: v0.5.8

Константы 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

Добавлено в: v11.7.0, v10.16.0

Для потоков на основе 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
    • Булев флаг, включающий режим «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
    • Булев флаг, включающий режим «Large Window Brotli» (несовместимый с форматом Brotli, стандартизированным в RFC 7932).

Константы Zstd

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0

Для потоков на основе 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,
  },
}); copy
Заявленный размер исходных данных

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

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

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

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

Класс: Options

История
Версия Изменения
v14.5.0, v12.19.0

Теперь поддерживается параметр maxOutputLength.
v9.4.0

Параметр dictionary теперь может быть значением ArrayBuffer.
v8.0.0

Теперь параметр dictionary может быть значением Uint8Array.
v5.11.0

Теперь поддерживается параметр finishFlush.
v0.11.1

Добавлено в: v0.11.1

Каждый класс на основе 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

История
Версия Изменения
v14.5.0, v12.19.0

Теперь поддерживается параметр maxOutputLength.
v11.7.0

Добавлено в: v11.7.0

Каждый класс на основе 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

Добавлено в: v11.7.0, v10.16.0
  • Наследует: ZlibBase

Сжимает данные с помощью алгоритма Brotli.

Класс: zlib.BrotliDecompress

Добавлено в: v11.7.0, v10.16.0
  • Наследует: ZlibBase

Распаковывает данные с помощью алгоритма Brotli.

Класс: zlib.Deflate

Добавлено в: v0.5.8
  • Наследует: ZlibBase

Сжимает данные с помощью deflate.

Класс: zlib.DeflateRaw

Добавлено в: v0.5.8
  • Наследует: ZlibBase

Сжимает данные с помощью deflate без добавления заголовка zlib.

Класс: zlib.Gunzip

История
Версия Изменения
v6.0.0

Теперь наличие посторонних данных в конце входного потока приводит к событию 'error'.
v5.9.0

Теперь поддерживаются несколько объединённых элементов файла gzip.
v5.0.0

Теперь усечённый входной поток приводит к событию 'error'.
v0.5.8

Добавлено в: v0.5.8
  • Наследует: ZlibBase

Распаковывает поток gzip.

Класс: zlib.Gzip

Добавлено в: v0.5.8
  • Наследует: ZlibBase

Сжимает данные с помощью gzip.

Класс: zlib.Inflate

История
Версия Изменения
v5.0.0

Теперь усечённый входной поток приводит к событию 'error'.
v0.5.8

Добавлено в: v0.5.8
  • Наследует: ZlibBase

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

Класс: zlib.InflateRaw

История
Версия Изменения
v6.8.0

Теперь InflateRaw поддерживает пользовательские словари.
v5.0.0

Теперь усечённый входной поток приводит к событию 'error'.
v0.5.8

Добавлено в: v0.5.8
  • Наследует: ZlibBase

Распаковывает необработанный поток deflate.

Класс: zlib.Unzip

Добавлено в: v0.5.8
  • Наследует: ZlibBase

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

Класс: zlib.ZlibBase

История
Версия Изменения
v11.7.0, v10.16.0

Этот класс переименован из Zlib в ZlibBase.
v0.5.8

Добавлено в: v0.5.8
  • Наследует: stream.Transform

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

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

zlib.bytesWritten

Добавлено в: v10.0.0
  • Тип: <number>

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

zlib.close([callback])

Добавлено в: v0.9.4
  • callback <Function>

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

zlib.flush([kind, ]callback)

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

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

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

zlib.params(level, strategy, callback)

Добавлено в: v0.11.4
  • level <integer>
  • strategy <integer>
  • callback <Function>

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

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

zlib.reset()

Добавлено в: v0.7.0

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

Класс: ZstdOptions

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0

Каждый класс на основе 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

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0

Сжимает данные с помощью алгоритма Zstd.

Класс: zlib.ZstdDecompress

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0

Распаковывает данные с помощью алгоритма Zstd.

zlib.constants

Добавлено в: v7.0.0

Предоставляет объект, содержащий перечисление констант, связанных с Zlib.

zlib.crc32(data[, value])

Добавлено в: v22.2.0, v20.15.0
  • 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').
Модули JavaScript
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
CommonJS
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])

Добавлено в: v11.7.0, v10.16.0
  • options <brotli options>

Создаёт и возвращает новый объект BrotliCompress.

zlib.createBrotliDecompress([options])

Добавлено в: v11.7.0, v10.16.0
  • options <brotli options>

Создаёт и возвращает новый объект BrotliDecompress.

zlib.createDeflate([options])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект Deflate.

zlib.createDeflateRaw([options])

Добавлено в: v0.5.8
  • 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])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект Gunzip.

zlib.createGzip([options])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект Gzip. См. пример.

zlib.createInflate([options])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект Inflate.

zlib.createInflateRaw([options])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект InflateRaw.

zlib.createUnzip([options])

Добавлено в: v0.5.8
  • options <zlib options>

Создаёт и возвращает новый объект Unzip.

zlib.createZstdCompress([options])

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0
  • options <zstd options>

Создаёт и возвращает новый объект ZstdCompress.

zlib.createZstdDecompress([options])

Стабильность: 1 - Экспериментальный
Добавлено в: v23.8.0, v22.15.0
  • options <zstd options>

Создаёт и возвращает новый объект ZstdDecompress.

Методы для удобства

Все эти методы принимают в качестве первого аргумента <Buffer>, <TypedArray>, <DataView>, <ArrayBuffer> или строку, необязательный второй аргумент для передачи параметров классам zlib и вызывают переданную функцию обратного вызова с callback(error, result).

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

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

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <brotli options>
  • callback <Function>

zlib.brotliCompressSync(buffer[, options])

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <brotli options>

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

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

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <brotli options>
  • callback <Function>

zlib.brotliDecompressSync(buffer[, options])

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <brotli options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.deflateSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.deflateRawSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.gunzipSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.gzipSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.inflateSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.inflateRawSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.6.0

Добавлено в: v0.6.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>
  • callback <Function>

zlib.unzipSync(buffer[, options])

История
Версия Изменения
v9.4.0

Параметр buffer теперь может быть ArrayBuffer.
v8.0.0

Параметр buffer теперь может быть любым TypedArray или DataView.
v8.0.0

Теперь параметр buffer может быть Uint8Array.
v0.11.12

Добавлено в: v0.11.12
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zlib options>

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

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

Стабильность: 1 — Экспериментальный
Добавлено в: v23.8.0, v22.15.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zstd options>
  • callback <Function>

zlib.zstdCompressSync(buffer[, options])

Стабильность: 1 — Экспериментальный
Добавлено в: v23.8.0, v22.15.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zstd options>

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

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

Добавлено в: v23.8.0, v22.15.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zstd options>
  • callback <Function>

zlib.zstdDecompressSync(buffer[, options])

Стабильность: 1 — Экспериментальный
Добавлено в: v23.8.0, v22.15.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <zstd options>

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

© Joyent, Inc. and other Node contributors
Licensed under the MIT License.
Node.js is a trademark of Joyent, Inc. and is used with its permission.
We are not endorsed by or affiliated with Joyent.
https://nodejs.org/dist/latest-v24.x/docs/api/zlib.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API