Zlib

[Стабильно: 2 - Стабильно]

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

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

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

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

ESMCJS

import os from 'node:zlib'

const zlib = require('node:zlib')

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

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

ESMCJS

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 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 с promise:

ESMCJS

import { createReadStream, createWriteStream } from 'node:fs'
import process from 'node:process'
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 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
})

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

ESMCJS

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())
})

// Или, с использованием промисов

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())
})

// Или, с использованием промисов

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 может привести к значительной фрагментации памяти.

ESMCJS

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

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

// ПРЕДУПРЕЖДЕНИЕ: НЕ ДЕЛАЙТЕ ТАК!
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')

// ПРЕДУПРЕЖДЕНИЕ: НЕ ДЕЛАЙТЕ ТАК!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {})
}

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

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

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

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

Заголовок HTTP Accept-Encoding используется в HTTP-запросе для определения кодировок сжатия, принимаемых клиентом. Заголовок Content-Encoding используется для определения кодировок сжатия, фактически примененных к сообщению.

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

ESMCJS

// Пример клиентского запроса
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('Произошла ошибка:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // Или просто используйте zlib.createUnzip() для обработки обоих следующих случаев:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

// Пример клиентского запроса
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' },
})
request.on('response', response => {
  const output = fs.createWriteStream('example.com_index.html')

  const onError = err => {
    if (err) {
      console.error('Произошла ошибка:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // Или просто используйте zlib.createUnzip() для обработки обоих следующих случаев:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

ESMCJS

// Пример сервера
// Выполнение операции gzip для каждого запроса довольно дорогостояще.
// Гораздо эффективнее кэшировать сжатый буфер.
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')
    // Сохраните как сжатую, так и несжатую версию ресурса.
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // Если возникает ошибка, мы мало что можем сделать, потому что
        // сервер уже отправил код ответа 200 и
        // некоторое количество данных уже было отправлено клиенту.
        // Лучшее, что мы можем сделать, это немедленно завершить ответ
        // и зарегистрировать ошибку.
        response.end()
        console.error('Произошла ошибка:', err)
      }
    }

    // Примечание: это не соответствующий парсер accept-encoding.
    // См. 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)

// Пример сервера
// Выполнение операции gzip для каждого запроса довольно дорогостояще.
// Гораздо эффективнее кэшировать сжатый буфер.
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')
    // Сохраните как сжатую, так и несжатую версию ресурса.
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // Если возникает ошибка, мы мало что можем сделать, потому что
        // сервер уже отправил код ответа 200 и
        // некоторое количество данных уже было отправлено клиенту.
        // Лучшее, что мы можем сделать, это немедленно завершить ответ
        // и зарегистрировать ошибку.
        response.end()
        console.error('Произошла ошибка:', err)
      }
    }

    // Примечание: это не соответствующий парсер accept-encoding.
    // См. 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)

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

// Это усеченная версия буфера из приведенных выше примеров
const buffer = Buffer.from('eJzT0yMA', 'base64')

zlib.unzip(
  buffer,
  // Для Brotli эквивалентом является zlib.constants.BROTLI_OPERATION_FLUSH.
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (err) {
      console.error('Произошла ошибка:', err)
      process.exitCode = 1
    }
    console.log(buffer.toString())
  }
)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. ниже для получения более подробной информации о параметрах Brotli.

Сброс

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

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

ESMCJS

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

http
  .createServer((request, response) => {
    // Для простоты проверки Accept-Encoding опущены.
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // Если возникает ошибка, мы мало что можем сделать, потому что
        // сервер уже отправил код ответа 200 и
        // некоторое количество данных уже отправлено клиенту.
        // Лучшее, что мы можем сделать, это немедленно завершить ответ
        // и зарегистрировать ошибку.
        clearInterval(i)
        response.end()
        console.error('An error occurred:', err)
      }
    })

    i = setInterval(() => {
      output.write(`The current time is ${Date()}\n`, () => {
        // Данные были переданы в zlib, но алгоритм сжатия может
        // решить буферизовать данные для более эффективного сжатия.
        // Вызов .flush() сделает данные доступными, как только клиент
        // будет готов их получить.
        output.flush()
      })
    }, 1000)
  })
  .listen(1337)

const zlib = require('node:zlib')
const http = require('node:http')
const { pipeline } = require('node:stream')

http
  .createServer((request, response) => {
    // Для простоты проверки Accept-Encoding опущены.
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // Если возникает ошибка, мы мало что можем сделать, потому что
        // сервер уже отправил код ответа 200 и
        // некоторое количество данных уже отправлено клиенту.
        // Лучшее, что мы можем сделать, это немедленно завершить ответ
        // и зарегистрировать ошибку.
        clearInterval(i)
        response.end()
        console.error('An error occurred:', err)
      }
    })

    i = setInterval(() => {
      output.write(`The current time is ${Date()}\n`, () => {
        // Данные были переданы в zlib, но алгоритм сжатия может
        // решить буферизовать данные для более эффективного сжатия.
        // Вызов .flush() сделает данные доступными, как только клиент
        // будет готов их получить.
        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_TREES

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

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).

Класс: `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 <целое число> По умолчанию: zlib.constants.Z_NO_FLUSH
finishFlush <целое число> По умолчанию: zlib.constants.Z_FINISH
chunkSize <целое число> По умолчанию: 16 * 1024
windowBits <целое число>
level <целое число> (только сжатие)
memLevel <целое число> (только сжатие)
strategy <целое число> (только сжатие)
dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> (только deflate/inflate, пустой словарь по умолчанию)
info <булево> (Если true, возвращает объект с buffer и engine.)
maxOutputLength <целое число> Ограничивает размер выходных данных при использовании удобных методов. По умолчанию: buffer.kMaxLength

См. документацию по deflateInit2 и inflateInit2 для получения дополнительной информации.

Класс: `BrotliOptions`

[История]

Версия	Изменения
v14.5.0, v12.19.0	Теперь поддерживается параметр `maxOutputLength`.
v11.7.0	Добавлено в: v11.7.0

Каждый класс на основе Brotli принимает объект options. Все параметры являются необязательными.

flush <целое> По умолчанию: zlib.constants.BROTLI_OPERATION_PROCESS
finishFlush <целое> По умолчанию: zlib.constants.BROTLI_OPERATION_FINISH
chunkSize <целое> По умолчанию: 16 * 1024
params <Объект> Объект «ключ-значение», содержащий индексированные параметры Brotli.
maxOutputLength <целое> Ограничивает размер выходных данных при использовании удобных методов. По умолчанию: buffer.kMaxLength

Например:

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,
  },
})

Класс: `zlib.BrotliCompress`

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

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

Класс: `zlib.BrotliDecompress`

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

Разархивирует данные с использованием алгоритма Brotli.

Класс: `zlib.Deflate`

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

Сжимает данные с использованием deflate.

Класс: `zlib.DeflateRaw`

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

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

Класс: `zlib.Gunzip`

[История]

Версия	Изменения
v6.0.0	Хвостовой мусор в конце входного потока теперь приводит к событию `'error'`.
v5.9.0	Теперь поддерживаются несколько объединенных элементов файла gzip.
v5.0.0	Усеченный входной поток теперь приводит к событию `'error'`.
v0.5.8	Добавлено в: v0.5.8

Разархивирует поток gzip.

Класс: `zlib.Gzip`

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

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

Класс: `zlib.Inflate`

[История]

Версия	Изменения
v5.0.0	Усечённый входной поток теперь приведёт к событию `'error'`.
v0.5.8	Добавлено в: v0.5.8

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

Класс: `zlib.InflateRaw`

[История]

Версия	Изменения
v6.8.0	`InflateRaw` теперь поддерживает пользовательские словари.
v5.0.0	Усечённый входной поток теперь приведёт к событию `'error'`.
v0.5.8	Добавлено в: v0.5.8

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

Класс: `zlib.Unzip`

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

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

Класс: `zlib.ZlibBase`

[История]

Версия	Изменения
v11.7.0, v10.16.0	Этот класс был переименован из `Zlib` в `ZlibBase`.
v0.5.8	Добавлено в: v0.5.8

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

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

`zlib.bytesWritten`

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

<число>

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

`zlib.crc32(data[, value])`

Добавлено в: v22.2.0, v20.15.0

data <строка> | <Buffer> | <TypedArray> | <DataView> Если data является строкой, она будет закодирована как UTF-8 перед использованием для вычисления.
value <целое число> Необязательное начальное значение. Должно быть 32-битным беззнаковым целым числом. По умолчанию: 0
Возвращает: <целое число> 32-битное беззнаковое целое число, содержащее контрольную сумму.

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

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

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

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

ESMCJS

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.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.

`zlib.constants`

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

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

`zlib.createBrotliCompress([options])`

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

options <brotli options>

Создает и возвращает новый объект 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 изменило поведение, когда windowBits установлен в 8 для потоков raw deflate. 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.

Удобные методы

Все эти методы принимают 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 ​

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

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

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

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

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

Сброс ​

Константы ​

Константы zlib ​

Константы Brotli ​

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

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

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

Класс: Options ​

Класс: BrotliOptions ​

Класс: zlib.BrotliCompress ​

Класс: zlib.BrotliDecompress ​

Класс: zlib.Deflate ​

Класс: zlib.DeflateRaw ​

Класс: zlib.Gunzip ​

Класс: zlib.Gzip ​

Класс: zlib.Inflate ​

Класс: zlib.InflateRaw ​

Класс: zlib.Unzip ​

Класс: zlib.ZlibBase ​

zlib.bytesWritten ​

zlib.crc32(data[, value]) ​

zlib.close([callback]) ​

zlib.flush([kind, ]callback) ​

zlib.params(level, strategy, callback) ​

zlib.reset() ​

zlib.constants ​

zlib.createBrotliCompress([options]) ​

zlib.createBrotliDecompress([options]) ​

zlib.createDeflate([options]) ​

zlib.createDeflateRaw([options]) ​

zlib.createGunzip([options]) ​

zlib.createGzip([options]) ​

zlib.createInflate([options]) ​

zlib.createInflateRaw([options]) ​

zlib.createUnzip([options]) ​

Удобные методы ​

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

zlib.brotliCompressSync(buffer[, options]) ​

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

zlib.brotliDecompressSync(buffer[, options]) ​

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

zlib.deflateSync(buffer[, options]) ​

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

zlib.deflateRawSync(buffer[, options]) ​

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

zlib.gunzipSync(buffer[, options]) ​

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

zlib.gzipSync(buffer[, options]) ​

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

zlib.inflateSync(buffer[, options]) ​

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

zlib.inflateRawSync(buffer[, options]) ​

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

zlib.unzipSync(buffer[, options]) ​

Zlib

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

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

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

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

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

Сброс

Константы

Константы zlib

Константы Brotli

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

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

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

Класс: `Options`

Класс: `BrotliOptions`

Класс: `zlib.BrotliCompress`

Класс: `zlib.BrotliDecompress`

Класс: `zlib.Deflate`

Класс: `zlib.DeflateRaw`

Класс: `zlib.Gunzip`

Класс: `zlib.Gzip`

Класс: `zlib.Inflate`

Класс: `zlib.InflateRaw`

Класс: `zlib.Unzip`

Класс: `zlib.ZlibBase`

`zlib.bytesWritten`

`zlib.crc32(data[, value])`

`zlib.close([callback])`

`zlib.flush([kind, ]callback)`

`zlib.params(level, strategy, callback)`

`zlib.reset()`

`zlib.constants`

`zlib.createBrotliCompress([options])`

`zlib.createBrotliDecompress([options])`

`zlib.createDeflate([options])`

`zlib.createDeflateRaw([options])`

`zlib.createGunzip([options])`

`zlib.createGzip([options])`

`zlib.createInflate([options])`

`zlib.createInflateRaw([options])`

`zlib.createUnzip([options])`

Удобные методы

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

`zlib.brotliCompressSync(buffer[, options])`

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

`zlib.brotliDecompressSync(buffer[, options])`

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

`zlib.deflateSync(buffer[, options])`

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

`zlib.deflateRawSync(buffer[, options])`

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

`zlib.gunzipSync(buffer[, options])`

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

`zlib.gzipSync(buffer[, options])`

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

`zlib.inflateSync(buffer[, options])`

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

`zlib.inflateRawSync(buffer[, options])`

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

`zlib.unzipSync(buffer[, options])`