Options Reference

This page documents all configuration options available in compressionz.

CompressOptions

Options for compression operations.

pub const CompressOptions = struct {
    /// Compression level
    level: Level = .default,

    /// Include content size in header (LZ4 frame)
    include_size: bool = true,

    /// Include content checksum (LZ4 frame)
    include_checksum: bool = true,

    /// Dictionary for improved small-data compression
    dictionary: ?[]const u8 = null,
};

level

Controls the speed/ratio trade-off.

pub const Level = enum {
    fastest,  // Maximum speed, lower ratio
    fast,     // Good speed, good ratio
    default,  // Balanced (recommended)
    better,   // Better ratio, slower
    best,     // Maximum ratio, slowest
};

Usage:

const fast = try cz.compressWithOptions(.zstd, data, allocator, .{
    .level = .fast,
});

const best = try cz.compressWithOptions(.zstd, data, allocator, .{
    .level = .best,
});

Performance by Level (Zstd):

Level	Compress	Decompress	Ratio
fastest	12+ GB/s	11+ GB/s	99.8%
fast	12 GB/s	11+ GB/s	99.9%
default	12 GB/s	11+ GB/s	99.9%
better	5 GB/s	11+ GB/s	99.9%
best	1.3 GB/s	12 GB/s	99.9%

include_size

LZ4 frame only. Include original content size in frame header.

const with_size = try cz.compressWithOptions(.lz4, data, allocator, .{
    .include_size = true,  // Default
});

const without_size = try cz.compressWithOptions(.lz4, data, allocator, .{
    .include_size = false,  // Smaller header
});

Benefits of including size:

• Decompressor can allocate exact buffer size
• Enables size validation on decompression
• Small overhead (8 bytes in header)

include_checksum

LZ4 frame only. Include content checksum in frame footer.

const with_checksum = try cz.compressWithOptions(.lz4, data, allocator, .{
    .include_checksum = true,  // Default
});

const without_checksum = try cz.compressWithOptions(.lz4, data, allocator, .{
    .include_checksum = false,  // Faster, no verification
});

Trade-offs:

With Checksum	Without Checksum
Data integrity verification	No verification
~4 bytes overhead	Slightly smaller
Recommended for storage/network	OK for trusted pipelines

dictionary

Pre-trained dictionary for improved small-data compression.

const dictionary = @embedFile("my_dictionary.bin");

const compressed = try cz.compressWithOptions(.zstd, data, allocator, .{
    .dictionary = dictionary,
});

Supported codecs: .zstd, .zlib, .deflate

See Dictionary Compression for details.

---

DecompressOptions

Options for decompression operations.

pub const DecompressOptions = struct {
    /// Expected output size (required for lz4_raw)
    expected_size: ?usize = null,

    /// Maximum output size (decompression bomb protection)
    max_output_size: ?usize = null,

    /// Dictionary (must match compression)
    dictionary: ?[]const u8 = null,
};

expected_size

Required for raw block formats that don’t encode size.

// Required for lz4_raw
const decompressed = try cz.decompressWithOptions(.lz4_raw, data, allocator, .{
    .expected_size = 1024,  // Must match original size
});

When required:

Codec	Required?
lz4_raw	✅ Yes
All others	❌ No

Check programmatically:

if (codec.requiresExpectedSize()) {
    return cz.decompressWithOptions(codec, data, allocator, .{
        .expected_size = known_size,
    });
}

max_output_size

Limits decompressed output size. Protection against decompression bombs.

const safe = try cz.decompressWithOptions(.gzip, untrusted_data, allocator, .{
    .max_output_size = 100 * 1024 * 1024,  // 100 MB limit
});

Error on exceed: Returns error.OutputTooLarge

Recommended limits:

Context	Limit
User uploads	10-100 MB
API responses	1-10 MB
Config files	1 MB
Trusted internal	None or large

dictionary

Dictionary for decompression. Must match the dictionary used for compression.

const dictionary = @embedFile("my_dictionary.bin");

// Must use same dictionary as compression
const decompressed = try cz.decompressWithOptions(.zstd, data, allocator, .{
    .dictionary = dictionary,
});

Warning: Using the wrong dictionary produces garbage output or errors.

---

Codec-Specific Options

LZ4 Frame Options

When using cz.lz4.frame directly:

const cz = @import("compressionz");

const compressed = try cz.lz4.frame.compress(data, allocator, .{
    .level = .fast,
    .content_checksum = true,
    .block_checksum = false,
    .content_size = data.len,  // null to omit
    .block_size = .max64KB,    // .max64KB, .max256KB, .max1MB, .max4MB
    .independent_blocks = false,
});

Option	Type	Default	Description
level	Level	.default	Compression level
content_checksum	bool	true	XXH32 checksum of content
block_checksum	bool	false	XXH32 checksum per block
content_size	?usize	null	Original size in header
block_size	BlockSize	.max64KB	Maximum block size
independent_blocks	bool	false	Blocks don’t reference previous

Zstd Options

When using cz.zstd directly:

// Simple
const compressed = try cz.zstd.compress(data, allocator, .fast);

// With dictionary
const dict_compressed = try cz.zstd.compressWithDict(
    data,
    allocator,
    .default,
    dictionary,
);

Brotli Options

Brotli level affects both speed and ratio significantly:

Level	Compress	Ratio	Use Case
fast	1.3 GB/s	Good	Dynamic content
default	1.3 GB/s	Better	General use
best	86 MB/s	Best	Static assets

---

Default Values

Summary of all defaults:

Option	Default	Reason
level	.default	Balance of speed/ratio
include_size	true	Enables optimized decompression
include_checksum	true	Data integrity
dictionary	null	Not commonly needed
expected_size	null	Only needed for lz4_raw
max_output_size	null	No limit (set for untrusted data)

---

Querying Codec Capabilities

Check what a codec supports:

const codec: cz.Codec = .zstd;

// Feature queries
codec.supportsStreaming();    // true
codec.supportsDictionary();   // true
codec.hasBuiltinChecksum();   // true
codec.isFramed();             // true
codec.requiresExpectedSize(); // false

// Metadata
codec.name();       // "Zstandard"
codec.extension();  // ".zst"

See Codec Detection for auto-detection.