Skip to content

tyrus:compress ​

tyrus:compress comprime e descomprime buffers e streams de bytes com Gzip, Deflate (zlib), Deflate cru e Brotli. Toda operação é assíncrona e roda fora das threads que executam as funções async do próprio programa, então um buffer grande nunca as trava.

A descompressão é segura por padrão: o tamanho da saída e a razão de expansão são verificados enquanto os dados são produzidos, então uma entrada pequena e maliciosa não consegue encher a memória. As opções só aumentam esses limites, nunca os desligam.

Imports ​

Importaçõesimport { CompressError, CompressFormat, CompressOptions, DecompressOptions, compress, compressionStream, decompress, decompressionStream } from "tyrus:compress";

Funções ​

ItemAssinaturaFinalidade
compress(data: u8[] | string, format: CompressFormat, options?: CompressOptions) => Promise<Result<u8[], CompressError>>Comprime bytes ou os bytes UTF-8 de uma string.
decompress(data: u8[], options?: DecompressOptions) => Promise<Result<u8[], CompressError>>Descomprime bytes, detectando Gzip e Deflate pelos dados.
compressionStream(format: CompressFormat, options?: CompressOptions) => TransformStream<u8[], u8[]>Comprime uma stream de bytes de qualquer tamanho com memória constante.
decompressionStream(options?: DecompressOptions) => TransformStream<u8[], u8[]>Descomprime uma stream de bytes de qualquer tamanho com memória constante.

Formatos ​

CompressFormatFormatoDetectado por decompressNíveis
GzipGzip (.gz), inclusive vários membros concatenadosSim0 a 9, padrão 6
Deflatezlib, o deflate do cabeçalho HTTP Content-EncodingSim0 a 9, padrão 6
DeflateRawDeflate sem cabeçalho nem checksumNão0 a 9, padrão 6
BrotliBrotliNão0 a 11, padrão 6

A mesma entrada, formato e nível sempre produzem os mesmos bytes. Brotli e Deflate cru não têm assinatura, então decompress precisa de format para eles em vez de adivinhar.

Códigos de erro ​

Toda função resolve com um Result e nunca rejeita: o sucesso é Ok com os bytes, e uma falha é Err com um CompressError. Seu code é estável e sua message é legível. Dentro de uma função que retorna um Result com o mesmo erro, await compress(...)? entrega os bytes ou retorna o erro, e onfail o trata no próprio lugar.

CódigoSignificado
ERR_COMPRESS_INVALID_DATAOs dados estão malformados, truncados, têm bytes depois do fim ou não estão no formato informado.
ERR_COMPRESS_CHECKSUM_MISMATCHOs dados Gzip ou zlib não conferem com o checksum ou com o tamanho registrado.
ERR_COMPRESS_UNKNOWN_FORMATformat foi omitido e os dados não têm assinatura Gzip nem zlib.
ERR_COMPRESS_INVALID_LEVELlevel está fora do intervalo do formato.
ERR_COMPRESS_INVALID_OPTIONUma opção tem valor inválido, como um limite 0.
ERR_COMPRESS_OUTPUT_LIMITA saída descomprimida passaria de maxOutputBytes.
ERR_COMPRESS_RATIO_LIMITA saída descomprimida passaria de maxRatio vezes a entrada.
ERR_COMPRESS_ALLOCATION_FAILEDNão foi possível alocar memória para a saída.

Exemplo ​

tyrus
import { CompressError, CompressFormat, compress, decompress } from "tyrus:compress";
import { utf8 } from "tyrus:encoding";

const main = async (): Promise<void> => {
    const packed = await compress("Hello, Tyrus!", CompressFormat.Gzip) onfail {
        printError(packed.code);
    };
    const restored = await decompress(packed) onfail {
        printError(restored.code);
    };
    print(utf8.decodeLossy(restored)); // Hello, Tyrus!
};