packkit/zstd

Zstandard codec — pure-Gleam decoder.

The module parses the Zstandard frame envelope (magic, frame header descriptor, window descriptor, optional dictionary id, optional frame content size, optional trailing content checksum) and walks the block stream. Raw and RLE blocks decode directly; compressed blocks (type 2) decode through the FSE tables in packkit/internal/fse. Sequences with Predefined_Mode, RLE_Mode, and FSE_Compressed_Mode symbol descriptions all decode (LL, OF, ML independently). All four literal block types decode: Raw_Literals_Block, RLE_Literals_Block, Compressed_Literals_Block (Huffman-coded with direct-weight or FSE-weight tree descriptions, 1-stream or 4-stream form), and Treeless_Literals_Block (which reuses the prior block’s Huffman tree via the cross-block tree state threaded through the block loop). A treeless block in the first position of a frame surfaces as a typed CodecInvalidData. Repeat_Mode for sequence-symbol descriptions also threads its FSE tables across blocks (per RFC 8478 §3.1.1.4 the LL / OF / ML tables survive across blocks within a frame), and a Repeat_Mode in the first block of a frame surfaces as a typed CodecInvalidData.

Values

codec

</>

pub fn codec() -> codec.Codec

Zstandard codec smart constructor.

decode

</>

pub fn decode(
  bytes bytes: BitArray,
) -> Result(BitArray, error.CodecError)

Decode a Zstandard frame using default limits.

decode_with_limits

</>

pub fn decode_with_limits(
  bytes bytes: BitArray,
  limits limits: limit.Limits,
) -> Result(BitArray, error.CodecError)

Decode a Zstandard frame using explicit limits. Per RFC 8478 §3, a zstd “byte stream” is one or more frames concatenated; the decoder walks the entire input, appending each frame’s payload to the result.

encode

</>

pub fn encode(
  bytes bytes: BitArray,
) -> Result(BitArray, error.CodecError)

Encode bytes as a Zstandard frame. The encoder picks the cheapest of Raw_Block and RLE_Block per chunk — a chunk that repeats a single byte collapses to a 1-byte RLE payload — so inputs like repeat('A', N) compress, but mixed input still passes through as raw bytes. No LZ77 or Huffman compression yet, no content checksum. Output is a valid Zstandard frame any conforming decoder can read.

frame_header_for_size

</>

pub fn frame_header_for_size(
  size: Int,
) -> Result(BitArray, error.CodecError)

Build the Zstandard frame header for a payload of size bytes. Exposed for tests that need to assert on the FCS layout for sizes too large to materialise in memory (e.g. 4 GiB+ frames where the header used to silently truncate the FCS field to its low 32 bits).