`cmpz`

In-process multi-algorithm compression - gzip, raw deflate, zlib, brotli, zstandard, LZ4, bzip2, XZ/LZMA, and 7z; streaming compress and decompress; file helpers with compression ratio reporting; magic-number format auto-detection; algorithm benchmark and smart selection.

Load with: use cmpz

What this module does

cmpz provides native in-process compression for all major algorithms through host natives (__cmpz_*). Each algorithm has a simple compress and decompress function pair, an optional level/quality parameter, and sane defaults.

File helpers read a source file, compress or decompress, write the result, and return a stats object including original size, compressed size, and ratio. The auto-detect function inspects magic bytes to identify the format and dispatches to the right decompressor automatically. A benchmark function measures compression time and ratio across gzip, zstd, lz4, and bzip2 on your actual data.

Quick example

use cmpz

data = "hello world " * 1000

# Gzip compress (level 6 default) / decompress
compressed = cmpze(data, nil)
original = cmpzg(compressed)

# Zstandard (better ratio, fast)
zst = cmpzm(data, 3)
prn(cmpza(zst))

# Auto-detect and decompress
fmt = cmpzt(compressed)  # "gzip"
decompressed = cmpzn(compressed)

# File compress
info = cmpzf("large.log", "large.log.zst", "zstd", {lvl: 5})
prn(info.ratio)  # e.g. 0.12

# Benchmark on real data
results = cmpzb(data, 5)
# [{algo: "gzip", cmpms: 2.1, ratio: 0.45, ...}, ...]

# Best algorithm for balanced speed/ratio
packed = cmpzc(data, "balanced")

Functions

Gzip

cmpze(data, level)

Gzip-compress. Level 1–9, default 6. Returns compressed bytes.

cmpzg(data)

Gzip-decompress.

Deflate (raw) and zlib

cmpzd(data, level)

Raw deflate compress. Default level 6.

cmpzz(data, level)

Zlib-wrapped deflate compress. Default level 6.

cmpz7(data)

Zlib-wrapped deflate decompress.

Brotli

cmpzp(data, quality)

Brotli compress. Quality 0–11, default 4.

cmpzi(data)

Brotli decompress.

Zstandard (zstd)

cmpzm(data, level)

Zstd compress. Level 1–22, default 3. Excellent speed/ratio balance.

cmpza(data)

Zstd decompress.

LZ4

cmpzl(data)

LZ4 compress. Extremely fast, moderate ratio.

cmpz9(data)

LZ4 decompress.

Bzip2

cmpzk(data, level)

Bzip2 compress. Level 1–9, default 9. Best ratio of the common algorithms.

cmpz8(data)

Bzip2 decompress.

XZ / LZMA

cmpzx(data, level)

XZ compress. Level 0–9, default 6.

cmpzj(data)

XZ decompress.

7-Zip

cmpzo(data, password)

7z compress. Pass nil for no password encryption.

cmpzh(data, password)

7z decompress.

Streaming

cmpz0(algo)

Creates a new streaming compressor for the given algorithm name. Returns a stream handle.

cmpz4(stream, data)

Feeds data into a compression stream.

cmpz1(stream)

Finalises a compression stream (flush + finish).

cmpz3(stream)

Retrieves the accumulated compressed result from a stream.

cmpzs(algo)

Creates a streaming decompressor.

cmpz5(stream, data) / cmpz2(stream)

Feed data into and finalise a decompression stream.

File helpers

cmpzf(src, dst, algo, opts)

Reads src, compresses with the named algorithm, writes to dst. opts may contain lvl or ql depending on the algorithm. Returns {src, dst, orig, cmp, ratio}.

cmpz6(src, dst, algo)

Reads and decompresses src with the named algorithm to dst. Returns {src, dst, cmp, orig}.

Auto-detect

cmpzt(data)

Detects the compression format by inspecting magic bytes. Returns "gzip", "zstd", "lz4", "bzip2", "xz", or nil if unknown.

cmpzn(data)

Auto-detects the format and decompresses. Errors if the format is unrecognised or unsupported.

Benchmark and selection

cmpzb(data, iters)

Benchmarks gzip, zstd, lz4, and bzip2 on data over iters iterations (default 10). Returns a list of {algo, cmpms, ratio, out} objects - average milliseconds per compression and output size ratio.

cmpzc(data, target)

Selects and applies the best algorithm for the given target: "speed" → LZ4, "ratio" → bzip2, "balanced" → zstd level 3, or gzip as fallback.

Notes

All compression operations delegate to __cmpz_* host natives.
For file-level gzip via the system gzip binary, use cmp instead.
Requires trl, txt, and bin.