pro_binary

High-performance binary serialization for Dart. Optimized for speed, zero-copy reads, and Protocol Buffers-compatible encoding.

Key Features

• Zero-Copy Reads: Operations return Uint8List views without allocation.
• One-Pass Strings: Optimized writeVarString with optimistic shift (30% faster).
• Smart Buffering: Exponential growth (×1.5) and object pooling.
• Compact Encoding: VarInt & ZigZag support
• Stream Parsing: StreamBinaryReader and BinaryStreamTransformer for async data.
• Universal: Supports Native & Web (WASM/JS) with consistent API.
• Modern API: Leverages Dart Extension Types for zero-overhead abstractions.

Installation

dependencies:
  pro_binary: ^4.0.0

Quick Start

import 'package:pro_binary/pro_binary.dart';

// Serialize
final writer = BinaryWriter()
  ..writeUint32(42)
  ..writeVarString('Dart 🚀')
  ..writeBool(true);

final bytes = writer.takeBytes();

// Deserialize
final reader = BinaryReader(bytes);
print(reader.readUint32());    // 42
print(reader.readVarString()); // Dart 🚀
print(reader.readBool());      // true

// From List<int>
final bytesList = <int>[0x01, 0x02, 0x03, 0x04];
final reader2 = BinaryReader.fromList(bytesList);

Recipes & Patterns

1. Efficient Object Serialization

class User {
  final int id;
  final String name;

  User(this.id, this.name);

  void encode(BinaryWriter w) => w
    ..writeVarUint(id)
    ..writeVarString(name);

  factory User.decode(BinaryReader r) =>
    User(
      r.readVarUint(), 
      r.readVarString(),
    );
}

2. High-Frequency writes (Pooling)

Avoid GC pressure by reusing writer instances.

Recommended (Safe & Concise):

final data = BinaryWriterPool.withWriter((writer) {
  writer.writeUint32(1);
  writer.writeVarString('Dart Rocks!');
  return writer.toBytes(); // View of the buffer
});

Low-level API:

final writer = BinaryWriterPool.acquire();
try {
  writer.writeUint32(1);
  writer.writeVarString('Dart Rocks!');
  final data = writer.toBytes();
} finally {
  BinaryWriterPool.release(writer);
}

3. Stream Parsing (Async Binary Messages)

Process binary data arriving in chunks over a stream.

Custom Transformer:

class MessageParser extends BinaryStreamTransformer<Message> {
  @override
  Message? parse(StreamBinaryReader reader) {
    // Return null when not enough data yet
    if (!reader.hasBytes(4)) return null;
    final id = reader.readUint32();
    final name = reader.readVarString();
    return Message(id, name);
  }
}

// Usage:
stream.transform(MessageParser()).listen((msg) => print(msg));

Manual Chunk Reading:

final reader = StreamBinaryReader();
reader.addChunk(chunk1);
reader.addChunk(chunk2);

reader.bookmark();
try {
  final id = reader.readUint32();
  final name = reader.readVarString();
  reader.commit(); // Success — consumed
} on NotEnoughDataException {
  reader.rollback(); // Wait for more data
}

4. Binary Packets (Manual navigation)

final reader = BinaryReader(bytes);
final type = reader[0]; // Absolute peek via operator []
reader.skip(1);
if (reader.hasBytes(4)) {
  final payload = reader(4); // Concise call syntax for readBytes.
}

API Overview

Full API documentation: https://pub.dev/documentation/pro_binary/latest/pro_binary/

Class	Description
BinaryWriter	Encode data: fixed types, VarInt/ZigZag, strings, bytes. Supports takeBytes(), toBytes(), reset(), seek().
BinaryReader	Decode data: all fixed/variable types, navigation (skip, seek, rewind, peek), rebind() for reuse.
StreamBinaryReader	Async streaming: chunk-based reading with bookmark/rollback/commit transactional model.
BinaryStreamTransformer<T>	Stream parser: extend and implement parse() to process binary streams.
BinaryWriterPool	Object pool: acquire()/release() or withWriter() for high-frequency writes.
getUtf8Length	Utility: calculate UTF-8 byte length without encoding.

Performance

Run benchmarks to see it in action:

dart run benchmark_harness:bench --flavor aot --target test/performance/serialization_bench.dart

License

MIT License. See LICENSE for details.