Spec-Zone.ru › Node.js 22 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');

Сжатие и распаковка реализованы на основе 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' } });
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;
  }
});
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 {
    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

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

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

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

Однако это, как правило, ухудшит сжатие.

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

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

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

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

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

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

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

Дополнительные сведения о параметрах, специфичных для Brotli, см. ниже.

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

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

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

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

Дополнительные сведения о параметрах, специфичных для 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 - Экспериментальный
Добавлено в: 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
    • Задаёт ограничение размера (степень 2), превышение которого заставит 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.bytesRead

Добавлено в: v8.1.0Устарело с: v10.0.0
Стабильность: 0 - Устарело: вместо этого используйте zlib.bytesWritten.
  • <number>

Устаревший псевдоним для zlib.bytesWritten. Это исходное имя было выбрано потому, что значение можно было интерпретировать как количество байтов, прочитанных обработчиком, но оно не согласуется с другими потоками Node.js, которые используют эти имена для своих значений.

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 — экспериментальный
Добавлено в версии: 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 — экспериментальный
Добавлено в версии: v22.15.0

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

Класс: zlib.ZstdDecompress

Стабильность: 1 — экспериментальный
Добавлено в версии: v22.15.0

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

zlib.constants

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

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

zlib.crc32(data[, value])

Добавлено в версии: v22.2.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, если она также там работает. Если для сравнения с контрольной суммой, полученной такой сторонней библиотекой, необходимо использовать 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>

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

zlib.createBrotliDecompress([options])

Добавлено в версиях: v11.7.0, v10.16.0
  • options <параметры brotli>

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

zlib.createDeflate([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

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

zlib.createDeflateRaw([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

Создает и возвращает новый объект 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>

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

zlib.createGzip([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

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

zlib.createInflate([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

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

zlib.createInflateRaw([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

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

zlib.createUnzip([options])

Добавлено в версии: v0.5.8
  • options <параметры zlib>

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

zlib.createZstdCompress([options])

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

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

zlib.createZstdDecompress([options])

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

Создает и возвращает новый объект 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>
  • callback <Function>

zlib.brotliCompressSync(buffer[, options])

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <параметры Brotli>

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

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

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

zlib.brotliDecompressSync(buffer[, options])

Добавлено в: v11.7.0, v10.16.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <параметры Brotli>

Распаковывает фрагмент данных с помощью 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>
  • 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>

Сжимает фрагмент данных с помощью 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>
  • 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>

Сжимает фрагмент данных с помощью 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>
  • 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>

Распаковывает фрагмент данных с помощью 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>
  • 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>

Сжимает фрагмент данных с помощью 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>
  • 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>

Распаковывает фрагмент данных с помощью 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>
  • 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>

Распаковывает фрагмент данных с помощью 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>
  • 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>

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

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

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

zlib.zstdCompressSync(buffer[, options])

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

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

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

Добавлено в: v22.15.0
  • buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
  • options <параметры Zstandard>
  • callback <Function>

zlib.zstdDecompressSync(buffer[, options])

Стабильность: 1 — Экспериментальный
Добавлено в: 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-v22.x/docs/api/zlib.html

Spec-Zone.ru

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