ball_protobuf

An Editions-capable, pure-Dart Protocol Buffers runtime.

ball_protobuf is a descriptor-driven protobuf implementation written in Ball-portable Dart: binary wire codecs, binary and proto3-JSON marshal/unmarshal, well-known types, gRPC framing, and the complete protobuf Editions feature model + protoc's canonical feature-resolution algorithm (plus proto2/proto3 legacy inference).

Because it is authored in Ball-portable Dart, the same engine is compiled by the Ball toolchain to every target language — so editions-aware protobuf behaves identically on Dart, TypeScript, and C++ (see the portability matrix).

Editions features honoured

When a field descriptor carries a resolved 'features' map, the codecs honour:

  • field_presence — EXPLICIT / IMPLICIT / LEGACY_REQUIRED
  • enum_type — OPEN / CLOSED (out-of-range CLOSED values routed to unknowns)
  • repeated_field_encoding — PACKED / EXPANDED
  • message_encoding — LENGTH_PREFIXED / DELIMITED (groups, wire types 3/4)
  • utf8_validation — VERIFY / NONE
  • json_format — ALLOW / LEGACY_BEST_EFFORT

A descriptor without a 'features' key behaves as proto3 defaults (zero behavioural change), so existing callers are unaffected.

Conformance

The codecs are validated against the official protobuf conformance_test_runner for the proto2, proto3, and edition2023 TestAllTypes messages — the full registered corpus passes (Well-Known Types incl. Any, oneof, message merge, unknown-field retention, and the full proto3-JSON ruleset), CI-gated on every change. See the conformance harness docs for how to build the runner and run it locally; CI runs it on every change.

Usage

import 'package:ball_protobuf/ball_protobuf.dart';

final bytes = marshal({'x': 7}, [
  {'name': 'x', 'number': 1, 'type': 'TYPE_INT32'},
]);
final decoded = unmarshal(bytes, [
  {'name': 'x', 'number': 1, 'type': 'TYPE_INT32'},
]);

// Resolve editions feature sets:
final features = baseFeaturesForEdition(edition2023);

Status

Part of the Ball language project; versioned in lockstep with the other Ball Dart packages. See the Editions spec for the feature tables and design.

Libraries

ball_protobuf
Ball protobuf library — complete protobuf support written in pure Dart. When encoded to Ball IR, provides protobuf for any target language.
edition
Protobuf Edition identifiers and string/syntax mapping.
editions
Protobuf Editions feature resolution.
extension
Protobuf extension handles + a registry, for codegen.
field_fixed
Field-level encoding for protobuf fixed-width integer and floating-point types.
field_int
Protobuf integer field encoding/decoding.
field_len
Length-delimited (wire type 2) field encoding/decoding for protobuf.
grpc_frame
gRPC Length-Prefixed-Message framing.
json_codec
Descriptor-driven Proto3 JSON marshaling and unmarshaling.
marshal
Descriptor-driven protobuf message marshaling (encoding).
service
Service / method descriptors for gRPC + Connect RPC codegen.
unmarshal
Descriptor-driven protobuf binary unmarshaling (decoding).
well_known
Helpers for working with protobuf well-known types as plain Dart maps.
wire_bytes
wire_fixed
Fixed-width (32-bit / 64-bit) and field tag encoding/decoding for protobuf wire format.
wire_varint
Varint (LEB128) and ZigZag encoding/decoding for protobuf wire format.