brot

Brotli is a general-purpose compression algorithm developed by Google that offers compression ratios comparable to the best currently available methods. It’s particularly effective for web content and is supported natively by all modern browsers.

Brotli compression is most effective for data larger than ~1KB. For very small data, the compression overhead may result in larger output.

Examples

Simple decompression:

simplifile.read_bits("payload.br")
|> result.replace_error(Nil)
|> result.try(brot.decode)

Encoding with custom options:

brot.Options(..brot.default_options, quality: 3, window: 10)
|> brot.encode_with(payload, _)
|> result.map(simplifile.write_bits("payload.br", _))

Working with streaming data:

let encoder = brot.new_encoder()
list.map(chunks, brot.append_encoder(encoder, _))
brot.finish_encoder(encoder)

Types

Decoder

</>

Represents a streaming Brotli decoder. Use this for incremental decompression of data that arrives in chunks or when processing compressed streams.

pub type Decoder

Encoder

</>

Represents a streaming Brotli encoder. Use this for incremental compression of data that arrives in chunks or when you want to compress data without loading it all into memory at once.

pub type Encoder

Mode

</>

Tunes the encoder for different types of content, affecting how Brotli analyzes and compresses the input data

pub type Mode {
  Generic
  Text
  Font
}

Constructors

```
Generic
```
General-purpose compression suitable for any type of data. Use this when you’re unsure or have mixed content types.
```
Text
```
Optimized for UTF-8 text compression. Provides better compression ratios for natural language text.
```
Font
```
Optimized for font file compression, for example WOFF2 format. Specifically tuned for the structure of font files.

Options

</>

Controls the trade-offs between compression ratio, speed, and memory usage.

pub type Options {
  Options(
    mode: Mode,
    quality: Int,
    window: Int,
    block_size: Int,
    literal_context_modeling: Bool,
    size_hint: Int,
    large_window: Bool,
    npostfix: Int,
    ndirect: Int,
    stream_offset: Int,
  )
}

Constructors

```
Options(
  mode: Mode,
  quality: Int,
  window: Int,
  block_size: Int,
  literal_context_modeling: Bool,
  size_hint: Int,
  large_window: Bool,
  npostfix: Int,
  ndirect: Int,
  stream_offset: Int,
)
```
Arguments

mode

Compression mode optimized for content type.

quality

Compression quality level, from 0 to 11. Higher values produce better compression but are slower. Levels 0-4 are fast, 5-9 are balanced, 10-11 are for maximum compression.

window

Base-2 logarithm of the sliding window size, from 10 to 24. Larger windows can improve compression ratio but use more memory. Default is 22 (4MB window). If large_window is True, can go up to 30 (1GB).

block_size

Maximum input block size, use 0 for automatic. If non-zero, splits input into blocks of this size for processing.

literal_context_modeling

Enable literal context modeling for better text compression. Slightly slower but improves compression ratio for text.

size_hint

Estimated total input size in bytes, use 0 if unknown. Helps the encoder optimize memory allocation and compression strategy.

large_window

Enable large window support. When True, allows the window parameter to exceed the standard maximum of 24, up to 30 (1GB).

npostfix

Number of postfix bits for distance codes, from 0 to 3. Advanced tuning parameter. Use 0 unless you know what you’re doing.

ndirect

Number of direct distance codes, from 0 to 120, must be divisible by 1 << npostfix. Advanced tuning parameter. Use 0 unless you know what you’re doing.

stream_offset

Starting byte offset for the stream, used in streaming compression. Typically set to 0 for fresh compression.

StreamOutcome

</>

Result type for streaming decompression operations.

pub type StreamOutcome {
  Done(BitArray)
  More(BitArray)
}

Constructors

```
Done(BitArray)
```
Decompression is complete. Contains the final decompressed output. No more input data is expected.
```
More(BitArray)
```
More input data is needed to continue decompression. Contains any decompressed output produced so far. May be empty.

Values

append_encoder

</>

pub fn append_encoder(
  encoder: Encoder,
  data: BitArray,
) -> Result(BitArray, Nil)

Appends data to a streaming encoder and returns any available compressed output. The encoder may buffer data internally, so compressed output might not be available immediately for small inputs. Returns an error if encoding fails.

decode

</>

pub fn decode(data: BitArray) -> Result(BitArray, Nil)

Decompresses Brotli-compressed data. Returns the decompressed original data or an error if decompression fails.

default_options

</>

pub const default_options: Options

Default compression options matching the Brotli reference implementation. Uses maximum compression, 4MB window, and generic mode.

Reference: https://github.com/google/brotli/blob/master/c/enc/encode.c#L681

encode

</>

pub fn encode(data: BitArray) -> Result(BitArray, Nil)

Compresses data using Brotli with default settings. For custom compression settings, use encode_with. Returns the compressed data or an error if compression fails.

encode_with

</>

pub fn encode_with(
  data: BitArray,
  options: Options,
) -> Result(BitArray, Nil)

Compresses data using Brotli with custom options. This allows fine-tuned control over compression parameters. Returns the compressed data, or an error if compression fails.

finish_encoder

</>

pub fn finish_encoder(encoder: Encoder) -> Result(BitArray, Nil)

Finalizes the encoder and returns any remaining compressed output. This flushes all internal buffers and completes the compression stream. After calling this, the encoder is finished and should not be used further. Returns an error if finishing fails.

finish_encoder_with

</>

pub fn finish_encoder_with(
  encoder: Encoder,
  data: BitArray,
) -> Result(BitArray, Nil)

Appends final data to the encoder and immediately finishes compression. This is a convenience function that combines append_encoder and finish_encoder. Returns all remaining compressed output, or an error if encoding or finishing fails.

is_decoder_finished

</>

pub fn is_decoder_finished(decoder: Decoder) -> Bool

Checks if the decoder has finished decompressing all data. Returns True if decompression is complete, False if more data is expected.

is_encoder_finished

</>

pub fn is_encoder_finished(encoder: Encoder) -> Bool

Checks if the encoder has finished processing and flushed all output. Returns True if encoding is complete and all output has been flushed, False otherwise.

new_decoder

</>

pub fn new_decoder() -> Decoder

Creates a new streaming decoder.

new_encoder

</>

pub fn new_encoder() -> Encoder

Creates a new streaming encoder with default settings.

new_encoder_with

</>

pub fn new_encoder_with(options: Options) -> Encoder

Creates a new streaming encoder with custom options.

stream_decoder

</>

pub fn stream_decoder(
  decoder: Decoder,
  data: BitArray,
) -> Result(StreamOutcome, Nil)

Feeds compressed data to a streaming decoder and returns decompressed output. The decoder processes data incrementally and indicates whether more input is needed. Returns an error if decompression fails.

Examples

Constructors

Constructors

Arguments

Constructors