zstd 1.0.0-dev.1
zstd: ^1.0.0-dev.1 copied to clipboard
Zstandard (zstd) bindings for Dart: fast lossless compression, compiled from the official release sources through native assets build hooks.
zstd #
Dart bindings for Zstandard (zstd), the
fast lossless compression algorithm. The library is compiled from the official
release sources through
native assets build hooks, so nothing
has to be installed or built by hand besides a C toolchain.
Status: Experimental #
NOTE: This package is published as a development prerelease
(1.0.0-dev.1) to solicit feedback. The API surface is expected to change —
potentially in breaking ways — before the stable 1.0.0 release.
Features #
- Codec API —
zstd.encode/zstd.decodeon the sharedzstdinstance, orZstdCodec,ZstdEncoder, andZstdDecoderwhen a specific compression level or dictionary is needed. - Streaming —
startChunkedConversionconverts chunks as they arrive instead of buffering the whole input, andRawZstdFilterexposes the low-level compress/decompress filter for finer control. - Compression levels validated against libzstd itself:
ZstdOptionreportsminLevel,maxLevel, anddefaultLevel, andZstdCodec/ZstdEncoderreject out-of-range levels with aRangeError. - Errors surface as
ZstdError, carrying the libzstd error code and the matching error name. - Static linking with tree-shaking — the link hook trims the library down to the symbols Dart actually calls, and can be told to keep everything.
Getting started #
- Dart SDK
^3.10.0with native assets enabled (the default in recent SDKs). - A C toolchain, CMake, and
tarfor each target platform:- Android: the Android NDK.
- iOS / macOS: Xcode.
- Windows: Visual Studio with the "Desktop development with C++" workload.
- Linux:
gcc/clangand GNUmake.
The first build downloads the zstd 1.5.7 release tarball, verifies its SHA-256
digest, and compiles it for the target — no system-wide zstd installation is
used. The archive can be mirrored or replaced with a different release through
user_defines (see Configuration).
Usage #
import 'dart:convert';
import 'package:zstd/zstd.dart';
void main() {
final input = utf8.encode('hello hello hello hello hello');
final compressed = zstd.encode(input);
final decompressed = zstd.decode(compressed);
print(utf8.decode(decompressed));
}
Pick a compression level, or share a dictionary between the encoder and the decoder:
final codec = ZstdCodec(level: 9, dictionary: dictionaryBytes);
final compressed = codec.encode(input);
final decompressed = codec.decode(compressed);
A complete runnable example, including dictionary compression over a real JSON
document, is available in example/zstd_example.dart.
Supported platforms #
| Target | Static linking (default) | Dynamic loading |
|---|---|---|
| Android | libzstd.a |
libzstd.so |
| iOS | libzstd.a |
libzstd.dylib |
| macOS | libzstd.a |
libzstd.dylib |
| Linux | libzstd.a |
libzstd.so |
| Windows | zstd_static.lib |
zstd.dll |
With linking enabled the static library is linked into the app and the link
hook decides which symbols survive. When the build config does not enable
linking, a shared library is built and bundled instead
(BUILD_SHARED_LIBS=ON, ZSTD_BUILD_SHARED=ON).
Build system #
hook/build.dart fetches and compiles zstd, hook/link.dart links it:
RepositoryBuilder.tgzdownloads the release archive into the shared build directory and verifies the SHA-256 digest before extracting it.CMakeBuilderconfiguresbuild/cmake/withZSTD_BUILD_PROGRAMS=OFFand builds static or shared according to the link mode, then installs it into the output directory.- The installed library is registered as a code asset under the bindings'
default FFI asset ID (
src/zstd_bindings_generated.dart), so the@ffi.Nativedeclarations resolve without further configuration. CLinkerstatically links the code asset and tree-shakes it using the symbols recorded from Dart (record_use), guided bylib/src/zstd_record_use_mapping.dart.
The bindings in lib/src/zstd_bindings_generated.dart are generated by
ffigen (dart run tool/ffigen.dart) from the vendored headers in
src/include/.
Configuration #
Build options are read from the zstd user defines, so a project can point the
build at a mirror, a different zstd release, or turn off tree-shaking:
hooks:
user_defines:
zstd:
url: https://gh-proxy.org/https://github.com/meta/zstd/releases/download/v1.5.7/zstd-1.5.7.tar.gz
sha256: eb33e51f49a15e023950cd7825ca74a4a2b43db8354825ac24fc1b7ee09e6fa3
tree_shake: false
url and sha256 must be changed together. Setting tree_shake to false
skips the symbol trimming and keeps the whole library, which is the right
choice when the library is also consumed by code Dart cannot see.
Bugs and feedback #
Please file issues in the bug tracker.