Skip to main content

zstd 1.0.0-dev.0 copy "zstd: ^1.0.0-dev.0" to clipboard
zstd: ^1.0.0-dev.0 copied to clipboard

Zstandard (zstd) bindings for Dart: fast lossless compression, compiled from the official release sources through native assets build hooks.

zstd #

pub package

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.0) 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.decode on the shared zstd instance, or ZstdCodec, ZstdEncoder, and ZstdDecoder when a specific compression level or dictionary is needed.
  • Streaming — startChunkedConversion converts chunks as they arrive instead of buffering the whole input, and RawZstdFilter exposes the low-level compress/decompress filter for finer control.
  • Compression levels validated against libzstd itself: ZstdOption reports minLevel, maxLevel, and defaultLevel, and ZstdCodec / ZstdEncoder reject out-of-range levels with a RangeError.
  • 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.0 with native assets enabled (the default in recent SDKs).
  • A C toolchain, CMake, and tar for each target platform:
    • Android: the Android NDK.
    • iOS / macOS: Xcode.
    • Windows: Visual Studio with the "Desktop development with C++" workload.
    • Linux: gcc/clang and GNU make.

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:

  1. RepositoryBuilder.tgz downloads the release archive into the shared build directory and verifies the SHA-256 digest before extracting it.
  2. CMakeBuilder configures build/cmake/ with ZSTD_BUILD_PROGRAMS=OFF and builds static or shared according to the link mode, then installs it into the output directory.
  3. The installed library is registered as a code asset under the bindings' default FFI asset ID (src/zstd_bindings_generated.dart), so the @ffi.Native declarations resolve without further configuration.
  4. CLinker statically links the code asset and tree-shakes it using the symbols recorded from Dart (record_use), guided by lib/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.

2
likes
0
points
238
downloads

Publisher

verified publisherinvictus-dart.dev

Weekly Downloads

Zstandard (zstd) bindings for Dart: fast lossless compression, compiled from the official release sources through native assets build hooks.

Repository (GitHub)
View/report issues

Topics

#zstd

License

unknown (license)

Dependencies

code_assets, ffi, hooks, meta, native_toolchain_x, record_use

More

Packages that depend on zstd