Skip to content

tyrus:compress ​

tyrus:compress compresses and decompresses byte buffers and byte streams with Gzip, Deflate (zlib), raw Deflate, and Brotli. Every operation is asynchronous and runs off the threads that run the program's own async functions, so a large buffer never stalls them.

Decompression is safe by default: the output size and the expansion ratio are checked while the data is produced, so a small malicious input cannot fill the memory. Options only raise these limits, they never switch them off.

Imports ​

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

Functions ​

ItemSignaturePurpose
compress(data: u8[] | string, format: CompressFormat, options?: CompressOptions) => Promise<Result<u8[], CompressError>>Compresses bytes or the UTF-8 bytes of a string.
decompress(data: u8[], options?: DecompressOptions) => Promise<Result<u8[], CompressError>>Decompresses bytes, detecting Gzip and Deflate from the data.
compressionStream(format: CompressFormat, options?: CompressOptions) => TransformStream<u8[], u8[]>Compresses a byte stream of any size with constant memory.
decompressionStream(options?: DecompressOptions) => TransformStream<u8[], u8[]>Decompresses a byte stream of any size with constant memory.

Formats ​

CompressFormatFormatDetected by decompressLevels
GzipGzip (.gz), including several members joined one after the otherYes0 to 9, default 6
Deflatezlib, the deflate of the HTTP Content-Encoding headerYes0 to 9, default 6
DeflateRawDeflate without a header or checksumNo0 to 9, default 6
BrotliBrotliNo0 to 11, default 6

The same input, format, and level always produce the same bytes. Brotli and raw Deflate carry no signature, so decompress needs format for them instead of guessing.

Error codes ​

Every function resolves with a Result and never rejects: success is Ok with the bytes, and a failure is Err with a CompressError. Its code is stable and its message is readable. Inside a function that returns a Result with the same error, await compress(...)? hands the bytes over or returns the error, and onfail handles it in place.

CodeMeaning
ERR_COMPRESS_INVALID_DATAThe data is malformed, truncated, has bytes after its end, or is not in the given format.
ERR_COMPRESS_CHECKSUM_MISMATCHThe Gzip or zlib data does not match its checksum or its recorded size.
ERR_COMPRESS_UNKNOWN_FORMATformat was omitted and the data carries no Gzip or zlib signature.
ERR_COMPRESS_INVALID_LEVELlevel is outside the range of the format.
ERR_COMPRESS_INVALID_OPTIONAn option has an invalid value, such as a limit of 0.
ERR_COMPRESS_OUTPUT_LIMITThe decompressed output would exceed maxOutputBytes.
ERR_COMPRESS_RATIO_LIMITThe decompressed output would exceed maxRatio times its input.
ERR_COMPRESS_ALLOCATION_FAILEDMemory could not be allocated for the output.

Example ​

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