可迭代物件壓縮#

原始碼：lib/zlib/iter.js

穩定性：1 - 實驗性

node:zlib/iter 模組提供了用於 node:stream/iter 可迭代串流 API 的壓縮與解壓縮轉換功能。

此模組僅在啟用 --experimental-stream-iter CLI 旗標時可用。

每種演算法皆同時具備非同步版本（有狀態的非同步產生器，供 pull() 與 pipeTo() 使用）與同步版本（有狀態的同步產生器，供 pullSync() 與 pipeToSync() 使用）。

非同步轉換會將壓縮運作於 libuv 執行緒池（threadpool）中，使 I/O 操作與 JavaScript 執行重疊。同步轉換則直接在主執行緒上進行壓縮。

注意：這些轉換的預設值皆針對串流傳輸量（streaming throughput）進行調校，與 node:zlib 中的預設值不同。特別是 gzip/deflate 預設為等級 4（而非 6）且 memLevel 為 9（而非 8），而 Brotli 預設為品質 6（而非 11）。這些選擇符合常見的 HTTP 伺服器配置，能在壓縮比僅微幅下降的情況下提供顯著更快的壓縮速度。所有預設值皆可透過選項進行覆寫。

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

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

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

run().catch(console.error);

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

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

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

compressBrotli([options])#

compressBrotliSync([options])#

新增於：v26.0.0
  • 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>
  • 回傳值：<Object> 一個有狀態的轉換器。

建立一個 Brotli 壓縮轉換器。輸出與 zlib.brotliDecompress() 及 decompressBrotli()/decompressBrotliSync() 相容。

compressDeflate([options])#

compressDeflateSync([options])#

新增於：v26.0.0

建立一個 deflate 壓縮轉換器。輸出與 zlib.inflate() 及 decompressDeflate()/decompressDeflateSync() 相容。

compressGzip([options])#

compressGzipSync([options])#

新增於：v26.0.0

建立一個 gzip 壓縮轉換器。輸出與 zlib.gunzip() 及 decompressGzip()/decompressGzipSync() 相容。

compressZstd([options])#

compressZstdSync([options])#

新增於：v26.0.0
  • 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>
  • 回傳值：<Object> 一個有狀態的轉換器。

建立一個 Zstandard 壓縮轉換器。輸出與 zlib.zstdDecompress() 及 decompressZstd()/decompressZstdSync() 相容。

decompressBrotli([options])#

decompressBrotliSync([options])#

新增於：v26.0.0
  • options <Object>
    • chunkSize <number> 輸出緩衝區大小。預設值： 65536 (64 KB)。
    • params <Object> 鍵值對物件，其中鍵與值皆為 zlib.constants 的項目。可用的解壓縮器參數如下：
      • BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION -- 影響內部記憶體配置的布林旗標。
      • BROTLI_DECODER_PARAM_LARGE_WINDOW -- 啟用「大視窗 Brotli (Large Window Brotli)」模式的布林旗標（與 RFC 7932 不相容）。詳細資訊請參閱 zlib 文件中的 Brotli 解壓縮器選項。
    • dictionary <Buffer> | <TypedArray> | <DataView>
  • 回傳值：<Object> 一個有狀態的轉換器。

建立一個 Brotli 解壓縮轉換器。

decompressDeflate([options])#

decompressDeflateSync([options])#

新增於：v26.0.0

建立一個 deflate 解壓縮轉換器。

decompressGzip([options])#

decompressGzipSync([options])#

新增於：v26.0.0

建立一個 gzip 解壓縮轉換器。

decompressZstd([options])#

decompressZstdSync([options])#

新增於：v26.0.0
  • options <Object>
    • chunkSize <number> 輸出緩衝區大小。預設值： 65536 (64 KB)。
    • params <Object> 鍵值對物件，其中鍵與值皆為 zlib.constants 的項目。可用的解壓縮器參數如下：
      • ZSTD_d_windowLogMax -- 解壓縮器將配置的最大視窗大小 (log2)。用於限制惡意輸入對記憶體的使用量。詳細資訊請參閱 zlib 文件中的 Zstd 解壓縮器選項。
    • dictionary <Buffer> | <TypedArray> | <DataView>
  • 回傳值：<Object> 一個有狀態的轉換器。

建立一個 Zstandard 解壓縮轉換器。