Node.js v26.0.0 文档

可迭代压缩#

node:zlib/iter 模块提供了可与 node:stream/iter 可迭代流 API 配合使用的压缩和解压缩转换器。

此模块仅在启用 --experimental-stream-iter CLI 标志时可用。

每种算法都有异步变体（有状态异步生成器，用于 pull() 和 pipeTo()）和同步变体（有状态同步生成器，用于 pullSync() 和 pipeToSync()）。

异步转换器在 libuv 线程池上运行压缩，将 I/O 与 JavaScript 执行重叠。同步转换器直接在主线程上运行压缩。

注意：这些转换器的默认值是针对流吞吐量进行调整的，与 node:zlib 中的默认值不同。特别是，gzip/deflate 默认为等级 4（而非 6）和 memLevel 9（而非 8），Brotli 默认为质量 6（而非 11）。这些选择符合常见的 HTTP 服务器配置，并在压缩率仅有小幅降低的情况下提供了显著更快的压缩速度。所有默认值都可以通过选项进行覆盖。

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

// Async round-trip
const compressed = await bytes(pull(from('hello'), compressGzip()));
const original = await text(pull(from(compressed), decompressGzip()));
console.log(original); // 'hello'
const { from, pull, bytes, text } = require('node:stream/iter');
const { compressGzip, decompressGzip } = require('node:zlib/iter');

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

run().catch(console.error);
copy

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

// Sync round-trip
const compressed = pullSync(fromSync('hello'), compressGzipSync());
const original = textSync(pullSync(compressed, decompressGzipSync()));
console.log(original); // 'hello'
const { fromSync, pullSync, textSync } = require('node:stream/iter');
const { compressGzipSync, decompressGzipSync } = require('node:zlib/iter');

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

compressBrotli([options])#

compressBrotliSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• params <Object> 键值对对象，其中键和值均为 zlib.constants 条目。最重要的压缩器参数包括：
  • BROTLI_PARAM_MODE -- BROTLI_MODE_GENERIC（默认）、BROTLI_MODE_TEXT 或 BROTLI_MODE_FONT。
  • BROTLI_PARAM_QUALITY -- 范围从 BROTLI_MIN_QUALITY 到 BROTLI_MAX_QUALITY。默认值： 6（而非 BROTLI_DEFAULT_QUALITY，即 11）。质量 6 适合流式传输；质量 11 旨在用于离线/构建时压缩。
  • BROTLI_PARAM_SIZE_HINT -- 预期的输入大小。默认值： 0（未知）。
  • BROTLI_PARAM_LGWIN -- 窗口大小（log2）。默认值： 20 (1 MB)。Brotli 库默认值为 22 (4 MB)；减小的默认值可以在不显著影响流式工作负载压缩效果的前提下节省内存。
  • BROTLI_PARAM_LGBLOCK -- 输入块大小（log2）。有关完整列表，请参见 zlib 文档中的 Brotli 压缩器选项。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 Brotli 压缩转换器。输出与 zlib.brotliDecompress() 和 decompressBrotli()/decompressBrotliSync() 兼容。

compressDeflate([options])#

compressDeflateSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• level <number> 压缩等级 (0-9)。默认值： 4。
• windowBits <number> 默认值： Z_DEFAULT_WINDOWBITS (15)。
• memLevel <number> 默认值： 9。
• strategy <number> 默认值： Z_DEFAULT_STRATEGY。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 deflate 压缩转换器。输出与 zlib.inflate() 和 decompressDeflate()/decompressDeflateSync() 兼容。

compressGzip([options])#

compressGzipSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• level <number> 压缩等级 (0-9)。默认值： 4。
• windowBits <number> 默认值： Z_DEFAULT_WINDOWBITS (15)。
• memLevel <number> 默认值： 9。
• strategy <number> 默认值： Z_DEFAULT_STRATEGY。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 gzip 压缩转换器。输出与 zlib.gunzip() 和 decompressGzip()/decompressGzipSync() 兼容。

compressZstd([options])#

compressZstdSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• params <Object> 键值对对象，其中键和值均为 zlib.constants 条目。最重要的压缩器参数包括：
  • ZSTD_c_compressionLevel -- 默认值： ZSTD_CLEVEL_DEFAULT (3)。
  • ZSTD_c_checksumFlag -- 生成校验和。默认值： 0。
  • ZSTD_c_strategy -- 压缩策略。值包括 ZSTD_fast, ZSTD_dfast, ZSTD_greedy, ZSTD_lazy, ZSTD_lazy2, ZSTD_btlazy2, ZSTD_btopt, ZSTD_btultra, ZSTD_btultra2。有关完整列表，请参见 zlib 文档中的 Zstd 压缩器选项。
• pledgedSrcSize <number> 预期未压缩大小（可选提示）。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 Zstandard 压缩转换器。输出与 zlib.zstdDecompress() 和 decompressZstd()/decompressZstdSync() 兼容。

decompressBrotli([options])#

decompressBrotliSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• params <Object> 键值对对象，其中键和值均为 zlib.constants 条目。可用的解压器参数：
  • BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION -- 影响内部内存分配的布尔标志。
  • BROTLI_DECODER_PARAM_LARGE_WINDOW -- 启用“大窗口 Brotli”模式的布尔标志（与 RFC 7932 不兼容）。详情请参见 zlib 文档中的 Brotli 解压器选项。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 Brotli 解压缩转换器。

decompressDeflate([options])#

decompressDeflateSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• windowBits <number> 默认值： Z_DEFAULT_WINDOWBITS (15)。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 deflate 解压缩转换器。

decompressGzip([options])#

decompressGzipSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• windowBits <number> 默认值： Z_DEFAULT_WINDOWBITS (15)。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 gzip 解压缩转换器。

decompressZstd([options])#

decompressZstdSync([options])#

• options <Object>
• chunkSize <number> 输出缓冲区大小。默认值： 65536 (64 KB)。
• params <Object> 键值对对象，其中键和值均为 zlib.constants 条目。可用的解压器参数：
  • ZSTD_d_windowLogMax -- 解压器将分配的最大窗口大小（log2）。用于限制针对恶意输入的内存使用。详情请参见 zlib 文档中的 Zstd 解压器选项。
• dictionary <Buffer> | <TypedArray> | <DataView>

创建一个 Zstandard 解压缩转换器。