libcompress library

Pure Dart implementations of common compression algorithms

This library provides pure Dart implementations of LZ4, Snappy, GZIP, and Zstd compression, with no native dependencies. It supports both in-memory (block) compression and stream-based processing.

Basic Usage

import 'package:libcompress/libcompress.dart';

// Block-based compression
final codec = CodecFactory.codec(CodecType.lz4);
final compressed = codec.compress(data);
final decompressed = codec.decompress(compressed);

// Stream-based compression
final streamCodec = CodecFactory.streaming(CodecType.lz4);
final compressedStream = streamCodec.compress(inputStream);

Available Codecs

  • LZ4: Fast compression with good ratios. Supports levels 1-9 (level 9 uses HC mode).
  • Snappy: Very fast compression. Supports raw block and framing formats.
  • GZIP: Full DEFLATE implementation with GZIP framing (RFC 1952).
  • Zstd: Zstandard (RFC 8878) without dictionaries, including compressed blocks with Huffman/FSE encoding and sequence encoding.

All codecs are CLI-compatible with their respective command-line tools (lz4, snzip, gzip, zstd).

Classes

CodecFactory
Factory for creating compression codecs
CompressionCodec
Base class for compression codecs
CompressionOptions
Base class for compression codec configuration options
CompressionStreamCodec
Base abstract class for streaming compression codecs
Crc32
CRC32 checksum implementation for data integrity verification
Crc32c
CRC32C (Castagnoli) checksum implementation
GzipCodec
GZIP compression codec (RFC 1952)
GzipOptions
GZIP-specific compression options
GzipStreamCodec
Gzip streaming codec
Lz4Codec
LZ4 compression codec
Lz4Options
LZ4-specific compression options
Lz4StreamCodec
LZ4 streaming codec
NoopCodec
Pass-through codec that performs no compression
NoopStreamCodec
Pass-through streaming codec that performs no compression
SnappyCodec
Snappy compression codec Native Dart implementation based on the Snappy specification
SnappyIncrementalDecoder
Incremental Snappy framing decoder: parses and decodes one framing chunk at a time. Chunk-type validation (incl. the leading stream identifier) is enforced by SnappyStreamDecoder.
SnappyOptions
Snappy-specific compression options
SnappyStreamCodec
Snappy streaming codec
ZstdBlockHeader
Parsed Zstd block header information
ZstdCodec
Zstandard (Zstd) compression codec
ZstdFrameHeader
Parsed Zstd frame header information
ZstdFrameHeaderDescriptor
Frame header descriptor flags parsed from first header byte
ZstdOptions
Zstd-specific compression options
ZstdStreamCodec
Zstd streaming codec

Enums

CodecMode
Codec capability modes
CodecType
Supported compression codec types
CompressionLevel
Compression level presets for common use cases
ZstdBlockType
Block types in Zstandard format

Constants

defaultMaxBufferSize → const int
Default maximum buffer size for stream decoders (64MB)
gzipDefaultMaxDecompressedSize → const int
Default maximum decompressed size for GZIP (256 MB)
lz4BlockSize1M → const int
lz4BlockSize256K → const int
lz4BlockSize4M → const int
lz4BlockSize64K → const int
Standard LZ4 frame block sizes
lz4DefaultBlockSize → const int
lz4DefaultMaxBufferSize → const int
Default maximum buffer size for stream decoders (64MB)
snappyDefaultMaxBufferSize → const int
Default maximum buffer size for stream decoders (64MB)
zstdDefaultMaxBufferSize → const int
Default maximum buffer size for stream decoders (64MB)
zstdDefaultMaxDecompressedSize → const int
Default maximum decompressed size (256 MB) Prevents memory exhaustion from malicious contentSize headers
zstdMagicNumber → const int
Zstandard magic number File bytes: 28 B5 2F FD (little-endian) When read as uint32LE: 0xFD2FB528
zstdMaxBlockSize → const int
Maximum block size (128 KB)
zstdSkippableFrameMagicBase → const int
Base magic number for skippable frames (0x184D2A50 + n, where n in 0, 15)
zstdSkippableFrameMagicMask → const int
Mask used to detect skippable magic numbers.

Functions

guardFormat<T>(T body(), CompressionFormatException wrap(String message)) → T
Runs body, converting the input-validation errors a decoder throws on malformed data into a codec-specific CompressionFormatException via wrap: StateError (e.g. exhausted bit reader), ArgumentError (incl. its subtypes RangeError/IndexError, e.g. an out-of-window back-reference), plain FormatException, and OutputLimitException (a size limit was hit).
validateLevel(int level, int min, int max) → void
Validates level is in [min, max], throwing ArgumentError otherwise. Shared by codec constructors so they fail fast at the API boundary rather than later during the first compression.
validateOptionalPositive(int? value, String name) → void
Validates a nullable limit is either null (unlimited) or > 0.
validatePositive(int value, String name) → void
Validates value is > 0.
validateRange(int value, int min, int max, String name) → void
Validates value is in [min, max] (e.g. a block/chunk size).

Exceptions / Errors

CompressionFormatException
Base exception class for compression format errors
DeflateFormatException
Exception thrown during DEFLATE compression/decompression
GzipFormatException
Exception thrown when invalid GZIP data is encountered
Lz4FormatException
Exception thrown when invalid LZ4 data is encountered
SnappyFormatException
Exception thrown when invalid Snappy data is encountered
ZstdFormatException
Exception thrown when invalid Zstandard data is encountered