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, fxhash, ahash, smol_str, serde_json)
• Custom derive macros for ergonomic usage
• Feature-gated support for optional dependencies

Binary Format

This library uses magic numbers to distinguish between different serialization formats:

• Encode format: Starts with magic number 0xA55A (2 bytes, little-endian)
  • Used by encode() and encode_to() functions
  • Supports schema evolution with field IDs and type tags
• Pack format: Starts with magic number 0xDADA (2 bytes, little-endian)
  • Used by pack() and pack_to() functions
  • Compact format without schema evolution support

Magic numbers are only added when using the convenience functions in this library. Direct trait method calls (Encoder::encode, Packer::pack) do not include magic numbers.

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:

External Crate Support

• 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.
• fxhash — Enables encoding/decoding of fxhash::FxHashMap and fxhash::FxHashSet (fast hash collections).
• ahash — Enables encoding/decoding of ahash::AHashMap and ahash::AHashSet (high-performance hash collections).
• smol_str — Enables encoding/decoding of smol_str::SmolStr (small string optimization).
• serde_json — Enables encoding/decoding of serde_json::Value (JSON values as dynamic type).
• raw_value — Enables encoding/decoding of Box<serde_json::value::RawValue> (raw JSON strings). Requires serde_json feature.

Modules

core

Type tags used in the senax binary format.

Enums

EncoderError

Errors that can occur during encoding or decoding operations.

EnumDecodeError

Derive-specific error types for enum operations

StructDecodeError

Derive-specific error types for struct operations

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.

Packer

Trait for types that can be packed into a compact binary format.

Unpacker

Trait for types that can be unpacked from a compact binary format.

Functions

decode

Convenience function to decode a value from bytes.

encode

Convenience function to encode a value to bytes with magic number.

encode_to

Convenience function to encode a value to an existing BytesMut buffer with magic number.

pack

Convenience function to pack a value to bytes with magic number.

pack_to

Convenience function to pack a value to an existing BytesMut buffer with magic number.

unpack

Convenience function to unpack a value from bytes.

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

Pack

Derive macro for implementing the Pack trait (Packer only)

Unpack

Derive macro for implementing the Unpack trait (Unpacker only)