Skip to content

tyrus:compress ​

tyrus:compress comprime y descomprime buffers y streams de bytes con Gzip, Deflate (zlib), Deflate crudo y Brotli. Toda operación es asíncrona y se ejecuta fuera de los hilos que ejecutan las funciones async del propio programa, así que un buffer grande nunca los bloquea.

La descompresión es segura por defecto: el tamaño de la salida y la razón de expansión se comprueban mientras se producen los datos, así que una entrada pequeña y maliciosa no puede llenar la memoria. Las opciones solo aumentan estos límites, nunca los desactivan.

Imports ​

Importacionesimport { CompressError, CompressFormat, CompressOptions, DecompressOptions, compress, compressionStream, decompress, decompressionStream } from "tyrus:compress";

Funciones ​

ItemFirmaPropósito
compress(data: u8[] | string, format: CompressFormat, options?: CompressOptions) => Promise<Result<u8[], CompressError>>Comprime bytes o los bytes UTF-8 de una cadena.
decompress(data: u8[], options?: DecompressOptions) => Promise<Result<u8[], CompressError>>Descomprime bytes, detectando Gzip y Deflate por los datos.
compressionStream(format: CompressFormat, options?: CompressOptions) => TransformStream<u8[], u8[]>Comprime un stream de bytes de cualquier tamaño con memoria constante.
decompressionStream(options?: DecompressOptions) => TransformStream<u8[], u8[]>Descomprime un stream de bytes de cualquier tamaño con memoria constante.

Formatos ​

CompressFormatFormatoDetectado por decompressNiveles
GzipGzip (.gz), incluidos varios miembros concatenadosSí0 a 9, por defecto 6
Deflatezlib, el deflate del encabezado HTTP Content-EncodingSí0 a 9, por defecto 6
DeflateRawDeflate sin encabezado ni checksumNo0 a 9, por defecto 6
BrotliBrotliNo0 a 11, por defecto 6

La misma entrada, formato y nivel siempre producen los mismos bytes. Brotli y Deflate crudo no tienen firma, así que decompress necesita format para ellos en lugar de adivinar.

Códigos de error ​

Toda función se resuelve con un Result y nunca rechaza: el éxito es Ok con los bytes, y un fallo es Err con un CompressError. Su code es estable y su message es legible. Dentro de una función que retorna un Result con el mismo error, await compress(...)? entrega los bytes o retorna el error, y onfail lo trata en el mismo lugar.

CódigoSignificado
ERR_COMPRESS_INVALID_DATALos datos están malformados, truncados, tienen bytes después del final o no están en el formato indicado.
ERR_COMPRESS_CHECKSUM_MISMATCHLos datos Gzip o zlib no coinciden con su checksum o con el tamaño registrado.
ERR_COMPRESS_UNKNOWN_FORMATSe omitió format y los datos no tienen firma Gzip ni zlib.
ERR_COMPRESS_INVALID_LEVELlevel está fuera del rango del formato.
ERR_COMPRESS_INVALID_OPTIONUna opción tiene un valor inválido, como un límite 0.
ERR_COMPRESS_OUTPUT_LIMITLa salida descomprimida superaría maxOutputBytes.
ERR_COMPRESS_RATIO_LIMITLa salida descomprimida superaría maxRatio veces la entrada.
ERR_COMPRESS_ALLOCATION_FAILEDNo se pudo reservar memoria para la salida.

Ejemplo ​

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!
};