# pamoja-codec
Serialization and framing for pamoja: pluggable wire formats behind a common Codec trait.
<a href="https://pamoja.molex.cloud/docs/reference/rust/pamoja_codec/index.html"><img height="28" alt="API reference" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg"></a>
<a href="https://pamoja.molex.cloud/docs/guides/codec.html"><img height="28" alt="read the guide" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg"></a>
<a href="https://crates.io/crates/pamoja-codec"><img height="28" alt="crates.io" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-cratesio.svg"></a>
<a href="https://docs.rs/pamoja-codec"><img height="28" alt="docs.rs" src="https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docsrs.svg"></a>
## The same capability in every language
| Rust | [`pamoja-codec`](https://crates.io/crates/pamoja-codec) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_codec/index.html), [docs.rs](https://docs.rs/pamoja-codec), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-codec) |
| TypeScript | [`@pamoja/codec`](https://www.npmjs.com/package/@pamoja/codec) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_codec.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-codec) |
| Python | [`pamoja-codec`](https://pypi.org/project/pamoja-codec/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/codec.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-codec) |
| C# | [`Pamoja.Codec`](https://www.nuget.org/packages/Pamoja.Codec) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Codec.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-codec) |
Pluggable serialization for pamoja payloads.
Concrete wire formats - CBOR for constrained devices, Protocol Buffers, JSON,
or raw framing - implement the `Codec` trait. This crate defines the trait
and provides serde-based implementations behind feature flags:
- `CborCodec` (feature `cbor`, on by default) - compact binary framing for
constrained devices and metered links.
- `JsonCodec` (feature `json`, on by default) - human-readable framing for
interop and debugging.
- `BytesCodec` (always available) - a no-op codec that carries raw bytes.
For metered links it also packs batches of samples into far fewer bytes:
`encode_deltas` delta-encodes a series of integers, and `Quantizer` rounds
`f32` readings to a fixed precision and delta-encodes them.
`json_to_cbor` and `cbor_to_json` convert a whole document between the two
formats without a Rust type for it, which is what a caller holding an untyped
payload needs in order to reach the compact form.
**Examples**
A little-endian codec for `u32` values:
```rust
use pamoja_codec::Codec;
use pamoja_core::{Error, Result};
struct LeU32;
impl Codec<u32> for LeU32 {
fn encode(&self, value: &u32) -> Result<Vec<u8>> {
Ok(value.to_le_bytes().to_vec())
}
fn decode(&self, bytes: &[u8]) -> Result<u32> {
let array = bytes
.try_into()
.map_err(|_| Error::Codec("expected 4 bytes".into()))?;
Ok(u32::from_le_bytes(array))
}
}
let codec = LeU32;
let encoded = codec.encode(&42).unwrap();
assert_eq!(codec.decode(&encoded).unwrap(), 42);
```
## trait `Codec`
Encodes and decodes values of type `T` to and from byte buffers.
A codec is the bridge between in-memory values and the bytes carried by a
`Transport` or persisted by a
`Store`.
### `fn encode(&self, value: &T) -> Result <Vec <u8>>`
Encodes a value into a byte buffer.
**Arguments**
* `value` - the value to serialize.
**Returns**
A byte buffer containing the encoded representation of `value`.
**Errors**
Returns `Error::Codec` if the value cannot
be encoded.
### `fn decode(&self, bytes: &[u8]) -> Result <T>`
Decodes a value from a byte buffer.
**Arguments**
* `bytes` - the encoded representation to deserialize.
**Returns**
The value decoded from `bytes`.
**Errors**
Returns `Error::Codec` if `bytes` is not a
valid encoding of `T`.
## License
MIT - part of the [pamoja](https://github.com/molexxxx/pamoja) workspace: one memory-safe Rust core with bindings for every language.