Zlib

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice sorgente: lib/zlib.js

Il modulo node:zlib fornisce funzionalità di compressione implementate usando Gzip, Deflate/Inflate e Brotli.

Per accedervi:

ESM

import os from 'node:zlib'

CJS

const zlib = require('node:zlib')

La compressione e la decompressione sono basate sull'API Stream di Node.js.

La compressione o decompressione di un flusso (come un file) può essere eseguita passando il flusso sorgente attraverso un flusso zlib Transform in un flusso di destinazione:

ESM

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('Si è verificato un errore:', err)
    process.exitCode = 1
  }
})

CJS

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('Si è verificato un errore:', err)
    process.exitCode = 1
  }
})

Oppure, usando l'API pipeline promise:

ESM

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

CJS

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('Si è verificato un errore:', err)
  process.exitCode = 1
})

È anche possibile comprimere o decomprimere i dati in un singolo passaggio:

ESM

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('Si è verificato un errore:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString('base64'))
})

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64')
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('Si è verificato un errore:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString())
})

// Oppure, Promessificato

import { promisify } from 'node:util'
const do_unzip = promisify(unzip)

const unzippedBuffer = await do_unzip(buffer)
console.log(unzippedBuffer.toString())

CJS

const { deflate, unzip } = require('node:zlib')

const input = '.................................'
deflate(input, (err, buffer) => {
  if (err) {
    console.error('Si è verificato un errore:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString('base64'))
})

const buffer = Buffer.from('eJzT0yMAAGTvBe8=', 'base64')
unzip(buffer, (err, buffer) => {
  if (err) {
    console.error('Si è verificato un errore:', err)
    process.exitCode = 1
  }
  console.log(buffer.toString())
})

// Oppure, Promessificato

const { promisify } = require('node:util')
const do_unzip = promisify(unzip)

do_unzip(buffer)
  .then(buf => console.log(buf.toString()))
  .catch(err => {
    console.error('Si è verificato un errore:', err)
    process.exitCode = 1
  })

Utilizzo del pool di thread e considerazioni sulle prestazioni

Tutte le API zlib, eccetto quelle esplicitamente sincronizzate, utilizzano il pool di thread interno di Node.js. Questo può portare a effetti sorprendenti e limitazioni di prestazioni in alcune applicazioni.

Creare e utilizzare contemporaneamente un gran numero di oggetti zlib può causare una significativa frammentazione della memoria.

ESM

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

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

// ATTENZIONE: NON FARE QUESTO!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {})
}

CJS

const zlib = require('node:zlib')

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

// ATTENZIONE: NON FARE QUESTO!
for (let i = 0; i < 30000; ++i) {
  zlib.deflate(payload, (err, buffer) => {})
}

Nell'esempio precedente, vengono create contemporaneamente 30.000 istanze di deflate. A causa del modo in cui alcuni sistemi operativi gestiscono l'allocazione e la deallocazione della memoria, ciò può portare a una significativa frammentazione della memoria.

Si consiglia vivamente di memorizzare nella cache i risultati delle operazioni di compressione per evitare la duplicazione degli sforzi.

Compressione di richieste e risposte HTTP

Il modulo node:zlib può essere utilizzato per implementare il supporto per i meccanismi di codifica del contenuto gzip, deflate e br definiti da HTTP.

L'intestazione HTTP Accept-Encoding viene utilizzata all'interno di una richiesta HTTP per identificare le codifiche di compressione accettate dal client. L'intestazione Content-Encoding viene utilizzata per identificare le codifiche di compressione effettivamente applicate a un messaggio.

Gli esempi riportati di seguito sono drasticamente semplificati per mostrare il concetto di base. L'utilizzo della codifica zlib può essere costoso e i risultati dovrebbero essere memorizzati nella cache. Vedere Ottimizzazione dell'utilizzo della memoria per ulteriori informazioni sui compromessi velocità/memoria/compressione coinvolti nell'utilizzo di zlib.

ESM

// Esempio di richiesta client
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('Si è verificato un errore:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // Oppure, utilizzare semplicemente zlib.createUnzip() per gestire entrambi i casi seguenti:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

CJS

// Esempio di richiesta client
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('Si è verificato un errore:', err)
      process.exitCode = 1
    }
  }

  switch (response.headers['content-encoding']) {
    case 'br':
      pipeline(response, zlib.createBrotliDecompress(), output, onError)
      break
    // Oppure, utilizzare semplicemente zlib.createUnzip() per gestire entrambi i casi seguenti:
    case 'gzip':
      pipeline(response, zlib.createGunzip(), output, onError)
      break
    case 'deflate':
      pipeline(response, zlib.createInflate(), output, onError)
      break
    default:
      pipeline(response, output, onError)
      break
  }
})

ESM

// Esempio server
// Eseguire un'operazione gzip su ogni richiesta è piuttosto costoso.
// Sarebbe molto più efficiente memorizzare nella cache il buffer compresso.
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')
    // Memorizzare sia una versione compressa che una non compressa della risorsa.
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // Se si verifica un errore, non c'è molto che possiamo fare perché
        // il server ha già inviato il codice di risposta 200 e
        // una certa quantità di dati è già stata inviata al client.
        // La cosa migliore che possiamo fare è terminare immediatamente la risposta
        // e registrare l'errore.
        response.end()
        console.error('Si è verificato un errore:', err)
      }
    }

    // Nota: questo non è un parser accept-encoding conforme.
    // Vedere 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)

CJS

// Esempio server
// Eseguire un'operazione gzip su ogni richiesta è piuttosto costoso.
// Sarebbe molto più efficiente memorizzare nella cache il buffer compresso.
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')
    // Memorizzare sia una versione compressa che una non compressa della risorsa.
    response.setHeader('Vary', 'Accept-Encoding')
    const acceptEncoding = request.headers['accept-encoding'] || ''

    const onError = err => {
      if (err) {
        // Se si verifica un errore, non c'è molto che possiamo fare perché
        // il server ha già inviato il codice di risposta 200 e
        // una certa quantità di dati è già stata inviata al client.
        // La cosa migliore che possiamo fare è terminare immediatamente la risposta
        // e registrare l'errore.
        response.end()
        console.error('Si è verificato un errore:', err)
      }
    }

    // Nota: questo non è un parser accept-encoding conforme.
    // Vedere 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)

Per impostazione predefinita, i metodi zlib genereranno un errore durante la decompressione di dati troncati. Tuttavia, se è noto che i dati sono incompleti o se si desidera ispezionare solo l'inizio di un file compresso, è possibile sopprimere la gestione degli errori predefinita modificando il metodo di flushing utilizzato per decomprimere l'ultimo blocco di dati di input:

// Questa è una versione troncata del buffer dagli esempi precedenti
const buffer = Buffer.from('eJzT0yMA', 'base64')

zlib.unzip(
  buffer,
  // Per Brotli, l'equivalente è zlib.constants.BROTLI_OPERATION_FLUSH.
  { finishFlush: zlib.constants.Z_SYNC_FLUSH },
  (err, buffer) => {
    if (err) {
      console.error('Si è verificato un errore:', err)
      process.exitCode = 1
    }
    console.log(buffer.toString())
  }
)

Ciò non modificherà il comportamento in altre situazioni di generazione di errori, ad esempio quando i dati di input hanno un formato non valido. Utilizzando questo metodo, non sarà possibile determinare se l'input è terminato prematuramente o se mancano i controlli di integrità, rendendo necessario verificare manualmente che il risultato decompresso sia valido.

Ottimizzazione dell'utilizzo della memoria

Per flussi basati su zlib

Da zlib/zconf.h, modificato per l'utilizzo con Node.js:

I requisiti di memoria per deflate sono (in byte):

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

Cioè: 128K per windowBits = 15 + 128K per memLevel = 8 (valori predefiniti) più alcuni kilobyte per oggetti di piccole dimensioni.

Ad esempio, per ridurre i requisiti di memoria predefiniti da 256K a 128K, le opzioni devono essere impostate su:

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

Questo, tuttavia, degraderà generalmente la compressione.

I requisiti di memoria per inflate sono (in byte) 1 << windowBits. Cioè, 32K per windowBits = 15 (valore predefinito) più alcuni kilobyte per oggetti di piccole dimensioni.

Questo si aggiunge a un singolo buffer interno di slab di output di dimensione chunkSize, che di default è 16K.

La velocità di compressione zlib è influenzata in modo più drammatico dall'impostazione level. Un livello più alto si tradurrà in una migliore compressione, ma richiederà più tempo per il completamento. Un livello inferiore si tradurrà in una minore compressione, ma sarà molto più veloce.

In generale, opzioni di utilizzo della memoria maggiori significheranno che Node.js dovrà effettuare meno chiamate a zlib perché sarà in grado di elaborare più dati per ogni operazione write. Quindi, questo è un altro fattore che influisce sulla velocità, a costo dell'utilizzo della memoria.

Per flussi basati su Brotli

Esistono equivalenti alle opzioni zlib per i flussi basati su Brotli, sebbene queste opzioni abbiano intervalli diversi da quelli zlib:

• L'opzione level di zlib corrisponde all'opzione BROTLI_PARAM_QUALITY di Brotli.
• L'opzione windowBits di zlib corrisponde all'opzione BROTLI_PARAM_LGWIN di Brotli.

Vedi sotto per maggiori dettagli sulle opzioni specifiche di Brotli.

Flushing

Chiamare .flush() su un flusso di compressione farà sì che zlib restituisca il maggior numero possibile di output. Questo potrebbe comportare una degradazione della qualità della compressione, ma può essere utile quando i dati devono essere disponibili il prima possibile.

Nell'esempio seguente, flush() viene utilizzato per scrivere una risposta HTTP parziale compressa al client:

ESM

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

http
  .createServer((request, response) => {
    // Per semplicità, i controlli Accept-Encoding sono omessi.
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // Se si verifica un errore, non c'è molto che possiamo fare perché
        // il server ha già inviato il codice di risposta 200 e
        // una certa quantità di dati è già stata inviata al client.
        // La cosa migliore che possiamo fare è terminare immediatamente la risposta
        // e registrare l'errore.
        clearInterval(i)
        response.end()
        console.error('Si è verificato un errore:', err)
      }
    })

    i = setInterval(() => {
      output.write(`L'ora attuale è ${Date()}\n`, () => {
        // I dati sono stati passati a zlib, ma l'algoritmo di compressione potrebbe
        // aver deciso di bufferizzare i dati per una compressione più efficiente.
        // Chiamare .flush() renderà i dati disponibili non appena il client
        // sarà pronto a riceverli.
        output.flush()
      })
    }, 1000)
  })
  .listen(1337)

CJS

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

http
  .createServer((request, response) => {
    // Per semplicità, i controlli Accept-Encoding sono omessi.
    response.writeHead(200, { 'content-encoding': 'gzip' })
    const output = zlib.createGzip()
    let i

    pipeline(output, response, err => {
      if (err) {
        // Se si verifica un errore, non c'è molto che possiamo fare perché
        // il server ha già inviato il codice di risposta 200 e
        // una certa quantità di dati è già stata inviata al client.
        // La cosa migliore che possiamo fare è terminare immediatamente la risposta
        // e registrare l'errore.
        clearInterval(i)
        response.end()
        console.error('Si è verificato un errore:', err)
      }
    })

    i = setInterval(() => {
      output.write(`L'ora attuale è ${Date()}\n`, () => {
        // I dati sono stati passati a zlib, ma l'algoritmo di compressione potrebbe
        // aver deciso di bufferizzare i dati per una compressione più efficiente.
        // Chiamare .flush() renderà i dati disponibili non appena il client
        // sarà pronto a riceverli.
        output.flush()
      })
    }, 1000)
  })
  .listen(1337)

Costanti

Aggiunto in: v0.5.8

Costanti zlib

Tutte le costanti definite in zlib.h sono definite anche su require('node:zlib').constants. Nel normale corso delle operazioni, non sarà necessario utilizzare queste costanti. Sono documentate in modo che la loro presenza non sia sorprendente. Questa sezione è tratta quasi direttamente dalla documentazione zlib.

Precedentemente, le costanti erano disponibili direttamente da require('node:zlib'), ad esempio zlib.Z_NO_FLUSH. L'accesso alle costanti direttamente dal modulo è attualmente ancora possibile, ma è deprecato.

Valori di flush consentiti.

• 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

Codici di ritorno per le funzioni di compressione/decompressione. I valori negativi sono errori, i valori positivi vengono utilizzati per eventi speciali ma normali.

• 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

Livelli di compressione.

• zlib.constants.Z_NO_COMPRESSION
• zlib.constants.Z_BEST_SPEED
• zlib.constants.Z_BEST_COMPRESSION
• zlib.constants.Z_DEFAULT_COMPRESSION

Strategia di compressione.

• zlib.constants.Z_FILTERED
• zlib.constants.Z_HUFFMAN_ONLY
• zlib.constants.Z_RLE
• zlib.constants.Z_FIXED
• zlib.constants.Z_DEFAULT_STRATEGY

Costanti Brotli

Aggiunto in: v11.7.0, v10.16.0

Sono disponibili diverse opzioni e altre costanti per i flussi basati su Brotli:

Operazioni di flush

I seguenti valori sono operazioni di flush valide per i flussi basati su Brotli:

• zlib.constants.BROTLI_OPERATION_PROCESS (predefinito per tutte le operazioni)
• zlib.constants.BROTLI_OPERATION_FLUSH (predefinito quando si chiama .flush())
• zlib.constants.BROTLI_OPERATION_FINISH (predefinito per l'ultimo chunk)
• zlib.constants.BROTLI_OPERATION_EMIT_METADATA
  • Questa particolare operazione potrebbe essere difficile da usare in un contesto Node.js, poiché il livello di streaming rende difficile sapere quali dati finiranno in questo frame. Inoltre, attualmente non esiste alcun modo per consumare questi dati tramite l'API Node.js.

Opzioni del compressore

Sono disponibili diverse opzioni che possono essere impostate sugli encoder Brotli, influenzando l'efficienza e la velocità di compressione. Sia le chiavi che i valori possono essere accessibili come proprietà dell'oggetto zlib.constants.

Le opzioni più importanti sono:

• BROTLI_PARAM_MODE

  • BROTLI_MODE_GENERIC (predefinito)
  • BROTLI_MODE_TEXT, ottimizzato per testo UTF-8
  • BROTLI_MODE_FONT, ottimizzato per font WOFF 2.0

• BROTLI_PARAM_QUALITY

  • Varia da BROTLI_MIN_QUALITY a BROTLI_MAX_QUALITY, con un valore predefinito di BROTLI_DEFAULT_QUALITY.

• BROTLI_PARAM_SIZE_HINT

  • Valore intero che rappresenta la dimensione di input prevista; di default è 0 per una dimensione di input sconosciuta.

I seguenti flag possono essere impostati per un controllo avanzato sull'algoritmo di compressione e sulla regolazione dell'utilizzo della memoria:

• BROTLI_PARAM_LGWIN

  • Varia da BROTLI_MIN_WINDOW_BITS a BROTLI_MAX_WINDOW_BITS, con un valore predefinito di BROTLI_DEFAULT_WINDOW, o fino a BROTLI_LARGE_MAX_WINDOW_BITS se è impostato il flag BROTLI_PARAM_LARGE_WINDOW.

• BROTLI_PARAM_LGBLOCK

  • Varia da BROTLI_MIN_INPUT_BLOCK_BITS a BROTLI_MAX_INPUT_BLOCK_BITS.

• BROTLI_PARAM_DISABLE_LITERAL_CONTEXT_MODELING

  • Flag booleano che diminuisce il rapporto di compressione a favore della velocità di decompressione.

• BROTLI_PARAM_LARGE_WINDOW

  • Flag booleano che abilita la modalità "Large Window Brotli" (non compatibile con il formato Brotli come standardizzato in RFC 7932).

• BROTLI_PARAM_NPOSTFIX

  • Varia da 0 a BROTLI_MAX_NPOSTFIX.

• BROTLI_PARAM_NDIRECT

  • Varia da 0 a 15 \<\< NPOSTFIX con incrementi di 1 \<\< NPOSTFIX.

Opzioni del decompressore

Queste opzioni avanzate sono disponibili per controllare la decompressione:

• BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION

  • Flag booleano che influenza i modelli di allocazione di memoria interna.

• BROTLI_DECODER_PARAM_LARGE_WINDOW

  • Flag booleano che abilita la modalità "Large Window Brotli" (non compatibile con il formato Brotli come standardizzato in RFC 7932).

Classe: Options

[Cronologia]

Versione	Modifiche
v14.5.0, v12.19.0	L'opzione maxOutputLength è ora supportata.
v9.4.0	L'opzione dictionary può essere un ArrayBuffer.
v8.0.0	L'opzione dictionary può ora essere un Uint8Array.
v5.11.0	L'opzione finishFlush è ora supportata.
v0.11.1	Aggiunta in: v0.11.1

Ogni classe basata su zlib accetta un oggetto options. Nessuna opzione è richiesta.

Alcune opzioni sono rilevanti solo durante la compressione e vengono ignorate dalle classi di decompressione.

• flush <intero> Default: zlib.constants.Z_NO_FLUSH
• finishFlush <intero> Default: zlib.constants.Z_FINISH
• chunkSize <intero> Default: 16 * 1024
• windowBits <intero>
• level <intero> (solo compressione)
• memLevel <intero> (solo compressione)
• strategy <intero> (solo compressione)
• dictionary <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> (solo deflate/inflate, dizionario vuoto per impostazione predefinita)
• info <booleano> (Se true, restituisce un oggetto con buffer e engine.)
• maxOutputLength <intero> Limita le dimensioni dell'output quando si utilizzano i metodi di convenienza. Default: buffer.kMaxLength

Consulta la documentazione di deflateInit2 e inflateInit2 per maggiori informazioni.

Classe: BrotliOptions

[Cronologia]

Versione	Modifiche
v14.5.0, v12.19.0	L'opzione maxOutputLength è ora supportata.
v11.7.0	Aggiunta in: v11.7.0

Ogni classe basata su Brotli accetta un oggetto options. Tutte le opzioni sono facoltative.

• flush <intero> Default: zlib.constants.BROTLI_OPERATION_PROCESS
• finishFlush <intero> Default: zlib.constants.BROTLI_OPERATION_FINISH
• chunkSize <intero> Default: 16 * 1024
• params <Oggetto> Oggetto chiave-valore contenente i parametri Brotli indicizzati.
• maxOutputLength <intero> Limita le dimensioni dell'output quando si utilizzano i metodi di convenienza. Default: buffer.kMaxLength

Ad esempio:

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

Classe: zlib.BrotliCompress

Aggiunta in: v11.7.0, v10.16.0

Comprime i dati utilizzando l'algoritmo Brotli.

Classe: zlib.BrotliDecompress

Aggiunta in: v11.7.0, v10.16.0

Decomprime i dati utilizzando l'algoritmo Brotli.

Classe: zlib.Deflate

Aggiunta in: v0.5.8

Comprime i dati utilizzando deflate.

Classe: zlib.DeflateRaw

Aggiunta in: v0.5.8

Comprime i dati utilizzando deflate e non aggiunge un'intestazione zlib.

Classe: zlib.Gunzip

[Cronologia]

Versione	Modifiche
v6.0.0	I dati inutili alla fine del flusso di input ora produrranno un evento 'error'.
v5.9.0	Ora sono supportati più membri di file gzip concatenati.
v5.0.0	Un flusso di input troncato ora produrrà un evento 'error'.
v0.5.8	Aggiunta in: v0.5.8

Decomprime un flusso gzip.

Classe: zlib.Gzip

Aggiunto in: v0.5.8

Comprime i dati usando gzip.

Classe: zlib.Inflate

[Cronologia]

Versione	Modifiche
v5.0.0	Un flusso di input troncato ora restituirà un evento 'error'.
v0.5.8	Aggiunto in: v0.5.8

Decomprime un flusso deflate.

Classe: zlib.InflateRaw

[Cronologia]

Versione	Modifiche
v6.8.0	I dizionari personalizzati sono ora supportati da InflateRaw.
v5.0.0	Un flusso di input troncato ora restituirà un evento 'error'.
v0.5.8	Aggiunto in: v0.5.8

Decomprime un flusso deflate raw.

Classe: zlib.Unzip

Aggiunto in: v0.5.8

Decomprime un flusso compresso Gzip o Deflate rilevando automaticamente l'intestazione.

Classe: zlib.ZlibBase

[Cronologia]

Versione	Modifiche
v11.7.0, v10.16.0	Questa classe è stata rinominata da Zlib a ZlibBase.
v0.5.8	Aggiunto in: v0.5.8

Non esportato dal modulo node:zlib. È documentato qui perché è la classe base delle classi di compressore/decompressore.

Questa classe eredita da stream.Transform, permettendo agli oggetti node:zlib di essere usati in pipe e simili operazioni di flusso.

zlib.bytesWritten

Aggiunto in: v10.0.0

• <numero>

La proprietà zlib.bytesWritten specifica il numero di byte scritti nel motore, prima che i byte vengano elaborati (compressi o decompressi, a seconda della classe derivata).

zlib.crc32(data[, value])

Aggiunto in: v22.2.0, v20.15.0

• data <stringa> | <Buffer> | <TypedArray> | <DataView> Quando data è una stringa, verrà codificata come UTF-8 prima di essere utilizzata per il calcolo.
• value <intero> Un valore iniziale opzionale. Deve essere un intero senza segno a 32 bit. Predefinito: 0
• Restituisce: <intero> Un intero senza segno a 32 bit contenente il checksum.

Calcola un checksum Cyclic Redundancy Check a 32 bit di data. Se value è specificato, viene utilizzato come valore iniziale del checksum, altrimenti viene utilizzato 0 come valore iniziale.

L'algoritmo CRC è progettato per calcolare i checksum e rilevare gli errori nella trasmissione dei dati. Non è adatto per l'autenticazione crittografica.

Per essere coerente con altre API, se data è una stringa, verrà codificata con UTF-8 prima di essere utilizzata per il calcolo. Se gli utenti usano solo Node.js per calcolare e confrontare i checksum, questo funziona bene con altre API che usano la codifica UTF-8 per impostazione predefinita.

Alcune librerie JavaScript di terze parti calcolano il checksum su una stringa basata su str.charCodeAt() in modo che possa essere eseguita nei browser. Se gli utenti vogliono confrontare il checksum calcolato con questo tipo di libreria nel browser, è meglio utilizzare la stessa libreria in Node.js se funziona anche in Node.js. Se gli utenti devono utilizzare zlib.crc32() per confrontare il checksum prodotto da tale libreria di terze parti:

ESM

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

CJS

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

Aggiunto in: v0.9.4

• callback <Function>

Chiude l'handle sottostante.

zlib.flush([kind, ]callback)

Aggiunto in: v0.5.8

• kind Default: zlib.constants.Z_FULL_FLUSH per stream basati su zlib, zlib.constants.BROTLI_OPERATION_FLUSH per stream basati su Brotli.
• callback <Function>

Flush dei dati in sospeso. Non chiamare questa funzione inutilmente, i flush prematuri influenzano negativamente l'efficacia dell'algoritmo di compressione.

Chiamando questa funzione vengono scaricati i dati dallo stato interno di zlib, e non viene eseguito alcun tipo di flushing a livello di stream. Piuttosto, si comporta come una normale chiamata a .write(), cioè verrà messo in coda dietro altre scritture in sospeso e produrrà output solo quando i dati vengono letti dallo stream.

zlib.params(level, strategy, callback)

Aggiunto in: v0.11.4

• level <integer>
• strategy <integer>
• callback <Function>

Questa funzione è disponibile solo per stream basati su zlib, ovvero non Brotli.

Aggiorna dinamicamente il livello di compressione e la strategia di compressione. Applicabile solo all'algoritmo deflate.

zlib.reset()

Aggiunto in: v0.7.0

Ripristina il compressore/decompressore alle impostazioni di fabbrica. Applicabile solo agli algoritmi inflate e deflate.

zlib.constants

Aggiunto in: v7.0.0

Fornisce un oggetto che elenca le costanti relative a Zlib.

zlib.createBrotliCompress([options])

Aggiunto in: v11.7.0, v10.16.0

• options <opzioni brotli>

Crea e restituisce un nuovo oggetto BrotliCompress.

zlib.createBrotliDecompress([options])

Aggiunto in: v11.7.0, v10.16.0

• options <opzioni brotli>

Crea e restituisce un nuovo oggetto BrotliDecompress.

zlib.createDeflate([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto Deflate.

zlib.createDeflateRaw([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto DeflateRaw.

Un aggiornamento di zlib da 1.2.8 a 1.2.11 ha modificato il comportamento quando windowBits è impostato su 8 per i flussi di deflate raw. zlib impostava automaticamente windowBits su 9 se inizialmente era impostato su 8. Le versioni più recenti di zlib genereranno un'eccezione, quindi Node.js ha ripristinato il comportamento originale di aggiornamento di un valore di 8 a 9, poiché passare windowBits = 9 a zlib si traduce effettivamente in un flusso compresso che utilizza effettivamente solo una finestra a 8 bit.

zlib.createGunzip([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto Gunzip.

zlib.createGzip([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto Gzip. Vedi esempio.

zlib.createInflate([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto Inflate.

zlib.createInflateRaw([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto InflateRaw.

zlib.createUnzip([options])

Aggiunto in: v0.5.8

• options <opzioni zlib>

Crea e restituisce un nuovo oggetto Unzip.

Metodi di convenienza

Tutti questi metodi accettano un Buffer, TypedArray, DataView, ArrayBuffer o una stringa come primo argomento, un secondo argomento opzionale per fornire opzioni alle classi zlib e chiameranno la callback fornita con callback(error, result).

Ogni metodo ha una controparte *Sync, che accetta gli stessi argomenti, ma senza una callback.

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

Aggiunto in: v11.7.0, v10.16.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni brotli>
• callback <Function>

zlib.brotliCompressSync(buffer[, options])

Aggiunto in: v11.7.0, v10.16.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni brotli>

Comprime un blocco di dati con BrotliCompress.

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

Aggiunto in: v11.7.0, v10.16.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni brotli>
• callback <Function>

zlib.brotliDecompressSync(buffer[, options])

Aggiunto in: v11.7.0, v10.16.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni brotli>

Decomprimi un blocco di dati con BrotliDecompress.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Function>

zlib.deflateSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere un qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Comprime un blocco di dati con Deflate.

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

[Cronologia]

Versione	Modifiche
v8.0.0	Il parametro buffer può essere un qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.deflateRawSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere un qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Comprime un blocco di dati con DeflateRaw.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.gunzipSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Decomprimere un blocco di dati con Gunzip.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.gzipSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Comprime un blocco di dati con Gzip.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.inflateSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Decomprime un blocco di dati con Inflate.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.inflateRawSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Decomprime un blocco di dati con InflateRaw.

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

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.6.0	Aggiunto in: v0.6.0

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>
• callback <Funzione>

zlib.unzipSync(buffer[, options])

[Cronologia]

Versione	Modifiche
v9.4.0	Il parametro buffer può essere un ArrayBuffer.
v8.0.0	Il parametro buffer può essere un qualsiasi TypedArray o DataView.
v8.0.0	Il parametro buffer può ora essere un Uint8Array.
v0.11.12	Aggiunto in: v0.11.12

• buffer <Buffer> | <TypedArray> | <DataView> | <ArrayBuffer> | <string>
• options <opzioni zlib>

Decomprimere un blocco di dati con Unzip.