Skip to main content

Module serialize

seq_runtime

Module serialize 

Source
Expand description

Serialization of Seq Values

This module provides a serializable representation of Seq runtime values. It enables Value persistence and exchange with external systems.

§Use Cases

  • Actor persistence: Event sourcing and state snapshots
  • Data pipelines: Arrow/Parquet integration
  • IPC: Message passing between processes
  • Storage: Database and file persistence

§Why TypedValue?

The runtime Value type contains arena-allocated strings (SeqString) which aren’t directly serializable. TypedValue uses owned Strings and can be serialized with serde/bincode.

§Why BTreeMap instead of HashMap?

TypedValue::Map uses BTreeMap (not HashMap) for deterministic serialization. This ensures that the same logical map always serializes to identical bytes, which is important for:

  • Content-addressable storage (hashing serialized data)
  • Reproducible snapshots for testing and debugging
  • Consistent behavior across runs

The O(n log n) insertion overhead is acceptable since serialization is typically infrequent (snapshots, persistence) rather than on the hot path.

§Performance

Uses bincode for fast, compact binary serialization. For debugging, use TypedValue::to_debug_string().

§Byte-cleanliness boundary

TypedValue::String and TypedMapKey::String hold owned String — UTF-8 by definition. Conversion from a runtime Value::String (which is byte-clean and may carry arbitrary bytes) goes through as_str_or_empty(): invalid UTF-8 collapses to the empty string. That is the deliberate, narrow contract of this module — it serves the text-shaped payloads of actor persistence, IPC, and Arrow/Parquet pipelines, not arbitrary binary blobs.

Programs that need to persist binary String payloads should base64- or hex-encode them at the Seq layer before handing them to serialize, or use a binary-aware transport (file slurp/spit, HTTP body, channel send) which retains bytes verbatim.

Enums§

SerializeError
Error during serialization/deserialization
TypedMapKey
Serializable map key types
TypedValue
Serializable representation of Seq Values

Traits§

ValueSerialize
Extension trait for Value to add serialization methods