Crate senax_encoder

senax-encoder

A fast, compact, and schema-evolution-friendly binary serialization library for Rust.

• Supports struct/enum encoding with field/variant IDs for forward/backward compatibility
• Efficient encoding for primitives, collections, Option, String, bytes, and popular crates (chrono, uuid, ulid, rust_decimal, indexmap)
• Custom derive macros for ergonomic usage
• Feature-gated support for optional dependencies

Attribute Macros

You can control encoding/decoding behavior using the following attributes:

• #[senax(id = N)] — Assigns a custom field or variant ID (u64). Ensures stable wire format across versions.
• #[senax(default)] — If a field is missing during decoding, its value is set to Default::default() instead of causing an error. For Option<T>, this means None.
• #[senax(skip_encode)] — This field is not written during encoding. On decode, it is set to Default::default().
• #[senax(skip_decode)] — This field is ignored during decoding and always set to Default::default(). It is still encoded if present.
• #[senax(skip_default)] — This field is not written during encoding if its value equals the default value. On decode, missing fields are set to Default::default().
• #[senax(rename = "name")] — Use the given string as the logical field/variant name for ID calculation. Useful for renaming fields/variants while keeping the same wire format.

Feature Flags

The following optional features enable support for popular crates and types:

• chrono — Enables encoding/decoding of chrono::DateTime, NaiveDate, and NaiveTime types.
• uuid — Enables encoding/decoding of uuid::Uuid.
• ulid — Enables encoding/decoding of ulid::Ulid (shares the same tag as UUID for binary compatibility).
• rust_decimal — Enables encoding/decoding of rust_decimal::Decimal.
• indexmap — Enables encoding/decoding of IndexMap and IndexSet collections.
• serde_json — Enables encoding/decoding of serde_json::Value (JSON values as dynamic type).

Example

use senax_encoder::{Encoder, Decoder, Encode, Decode};
use bytes::BytesMut;

#[derive(Encode, Decode, PartialEq, Debug)]
struct MyStruct {
    id: u32,
    name: String,
}

let value = MyStruct { id: 42, name: "hello".to_string() };
let mut buf = BytesMut::new();
value.encode(&mut buf).unwrap();
let decoded = MyStruct::decode(&mut buf.freeze()).unwrap();
assert_eq!(value, decoded);

Enums

EncoderError

Error type for all encoding and decoding operations in this crate.

Constants

TAG_ARRAY_VEC_SET_BASE

< Enum with tuple fields

TAG_ARRAY_VEC_SET_LONG

< Short array/vec/set (length in tag)

TAG_BINARY

< Long string (length encoded)

TAG_CHRONO_DATETIME

< Map (HashMap, BTreeMap, IndexMap)

TAG_CHRONO_NAIVE_DATE

< chrono::DateTime

TAG_CHRONO_NAIVE_TIME

< chrono::NaiveDate

TAG_DECIMAL

< chrono::NaiveTime

TAG_ENUM

< Tuple struct

TAG_ENUM_NAMED

< C-like enum (unit variants)

TAG_ENUM_UNNAMED

< Enum with named fields

TAG_F32

< Negative signed integer (bit-inverted encoding)

TAG_F64

< f32

TAG_JSON_ARRAY

TAG_JSON_BOOL

TAG_JSON_NULL

< uuid::Uuid, ulid::Ulid

TAG_JSON_NUMBER

TAG_JSON_OBJECT

TAG_JSON_STRING

TAG_MAP

< Tuple

TAG_NEGATIVE

< u128

TAG_NONE

Type tags used in the senax binary format.

TAG_ONE

< 0 for numbers, false for bool

TAG_SOME

< Option::None

TAG_STRING_BASE

< f64

TAG_STRING_LONG

< Short string (length in tag)

TAG_STRUCT_NAMED

< Unit struct

TAG_STRUCT_UNIT

< Vec or Bytes

TAG_STRUCT_UNNAMED

< Named struct

TAG_TUPLE

< Long array/vec/set (length encoded)

TAG_U8

TAG_U8_2_BASE

< 1 for numbers, true for bool

TAG_U8_127

TAG_U16

< u8 (full range)

TAG_U32

< u16

TAG_U64

< u32

TAG_U128

< u64

TAG_UUID

< rust_decimal::Decimal

TAG_ZERO

< Option::Some

Traits

Decoder

Trait for types that can be decoded from the senax binary format.

Encoder

Trait for types that can be encoded into the senax binary format.

Functions

read_field_id_optimized

Reads a field ID using optimized encoding.

read_u32_le

Reads a u32 in little-endian format without a tag.

read_u64_le

Reads a u64 in little-endian format without a tag.

skip_value

Skips a value of any type in the senax binary format.

write_field_id_optimized

Writes a u64 in little-endian format without a tag.

write_u32_le

Writes a u32 in little-endian format without a tag.

write_u64_le

Writes a u64 in little-endian format without a tag.

Type Aliases

Result

The result type used throughout this crate for encode/decode operations.

Derive Macros

Decode

Derive macro for implementing the Decode trait

Encode

Derive macro for implementing the Encode trait