Feat/array of objects

README.md

@@ -3,18 +3,21 @@
 [![Documentation](https://docs.rs/sje/badge.svg)](https://docs.rs/sje/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-# sje
+# Simple Json Encoding
 
 Fast JSON deserialisation and serialisation schema based framework.
 
-## Example
+## Examples
 
 Make sure the `derive` feature is enabled.
 
 ```toml
 sje = { version = "0.0.4", features = ["derive"]}
 ```
 
+Simply annotate your struct using `#[sje]` attribute, The `len` field can be used when you know the exact size of the value field which means the
+decoder can handle it more efficiently.
+
 ```rust
 #[derive(Decoder)]
 #[sje(object)]
@@ -46,4 +49,80 @@ assert_eq!("trade", trade.event_type_as_str());
 assert_eq!(1705085312569, trade.event_time());
 ```
 
+We can also handle arrays and tuples. In this case if we want to use generated `PositionDecoder` we need to explicitly mark it with `decoder = true`.
+
+```rust
+#[derive(Decoder)]
+#[sje(object)]
+struct Position {
+    #[sje(rename = "s")]
+    symbol: String,
+    #[sje(rename = "a")]
+    amount: u32,
+}
+
+#[derive(Decoder)]
+#[sje(object)]
+struct PositionUpdate {
+    #[sje(rename = "t")]
+    timestamp: u64,
+    #[sje(rename = "u", decoder = true)]
+    updates: Vec<Position>,
+}
+```
+
+The generated code will contain iterators that already know the length of the array.
+
+```rust
+let update = PositionUpdateDecoder::decode(br#"{"t":1746699621,"u":[{"s":"btcusdt","a":100},{"s":"ethusdt","a":200}]}"#).unwrap();
+assert_eq!(2, update.updates_count());
+
+let mut updates = update.updates().into_iter();
+
+let position = updates.next().unwrap();
+assert_eq!("btcusdt", position.symbol_as_str());
+assert_eq!(100, position.amount());
+
+let position = updates.next().unwrap();
+assert_eq!("ethusdt", position.symbol_as_str());
+assert_eq!(200, position.amount());
 
+assert!(positions.next().is_none());
+```
+
+The framework also handles user defined types that don't require an explicit `Decoder`. In this case, the only requirement is that the type
+implements `FromStr` trait. We also need to tell the parser what is the underlying json type for our user defined type, in this case `ty = "string"`.
+
+```rust
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+struct Price(u64);
+
+impl FromStr for Price {
+    type Err = &'static str;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(s.parse().map_err(|_| "unable to parse the price")?))
+    }
+}
+
+#[derive(Decoder)]
+#[sje(object)]
+pub struct Trade {
+    #[sje(rename = "p", ty = "string")]
+    price: Price,
+}
+
+let trade = TradeDecoder::decode(br#"{"p":"12345"}"#).unwrap();
+assert_eq!(Price(12345), trade.price());
+```
+
+## Benchmarks
+
+There are [benchmarks](sje/benches) against [serde_json](https://crates.io/crates/serde_json) that show an order of magnitude
+speedup. Please note `sje` is not a generic purpose json parser - it's fast because it takes advantage of fixed schema and
+lacks a lot of features you would find in `serde_json` to handle more dynamic content.
+
+```shell
+RUSTFLAGS='-C target-cpu=native' cargo bench --bench=ticker
+```
+![img.png](docs/benchmark.png)

sje/array_of_objects/custom.rs

@@ -0,0 +1,30 @@
+use sje_derive::Decoder;
+use std::str::FromStr;
+
+#[derive(Copy, Clone, Eq, PartialEq, Debug)]
+struct Price(u64);
+
+impl FromStr for Price {
+    type Err = ();
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(s.parse().map_err(|_| ())?))
+    }
+}
+
+#[derive(Decoder)]
+#[sje(object)]
+#[allow(dead_code)]
+pub struct Trade {
+    #[sje(rename = "p", ty = "string")]
+    price: Price,
+}
+
+#[test]
+fn should_parse_custom_field() {
+    let json = r#"{"p":"12345"}"#;
+    let trade = TradeDecoder::decode(json.as_bytes()).unwrap();
+    assert_eq!(&Price(12345), trade.price_as_lazy_field().get_ref().unwrap());
+    assert_eq!(Price(12345), trade.price_as_lazy_field().get().unwrap());
+    assert_eq!(Price(12345), trade.price());
+}

sje/array_of_objects/decoder.rs

@@ -0,0 +1,74 @@
+use sje_derive::Decoder;
+
+#[derive(Decoder)]
+#[sje(object)]
+#[allow(dead_code)]
+pub struct Trade {
+    #[sje(rename = "e", len = 5)]
+    event_type: String,
+    #[sje(rename = "E", len = 13)]
+    event_time: u64,
+    #[sje(rename = "s")]
+    symbol: String,
+    #[sje(rename = "t", len = 10)]
+    trade_id: u64,
+    #[sje(rename = "p")]
+    price: String,
+    #[sje(rename = "q")]
+    quantity: String,
+    #[sje(rename = "b", len = 11)]
+    buyer_order_id: u64,
+    #[sje(rename = "a", len = 11)]
+    seller_order_id: u64,
+    #[sje(rename = "T", len = 13)]
+    transaction_time: u64,
+    #[sje(rename = "m")]
+    is_buyer_maker: bool,
+}
+
+#[derive(Decoder, Debug)]
+#[sje(object)]
+#[allow(dead_code)]
+struct ListenKeyExpired {
+    #[sje(rename = "e", len = 16, offset = 1)]
+    event_type: String,
+    #[sje(rename = "E", ty = "string", len = 13, offset = 1)]
+    event_time: u64,
+    #[sje(rename = "listenKey", offset = 1)]
+    listen_key: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use crate::{ListenKeyExpiredDecoder, Trade, TradeDecoder};
+    use std::str::from_utf8_unchecked;
+
+    #[test]
+    fn should_decode_trade() {
+        let trade = TradeDecoder::decode(br#"{"e":"trade","E":1705085312569,"s":"BTCUSDT","t":3370034463,"p":"43520.00000000","q":"0.00022000","b":24269765071,"a":24269767699,"T":1705085312568,"m":true,"M":true}"#).unwrap();
+        assert_eq!("trade", trade.event_type());
+        assert_eq!("BTCUSDT", unsafe { from_utf8_unchecked(trade.symbol_as_slice()) });
+        assert_eq!("BTCUSDT", trade.symbol_as_str());
+        assert_eq!("BTCUSDT", trade.symbol());
+
+        let trade: Trade = trade.into();
+        assert_eq!("trade", trade.event_type);
+        assert_eq!(1705085312569, trade.event_time);
+        assert_eq!("BTCUSDT", trade.symbol);
+        assert_eq!(3370034463, trade.trade_id);
+        assert_eq!("43520.00000000", trade.price);
+        assert_eq!("0.00022000", trade.quantity);
+        assert_eq!(24269765071, trade.buyer_order_id);
+        assert_eq!(24269767699, trade.seller_order_id);
+        assert_eq!(1705085312568, trade.transaction_time);
+        assert!(trade.is_buyer_maker);
+    }
+
+    #[test]
+    fn should_decode_listen_key_expired() {
+        let listen_key_expired = ListenKeyExpiredDecoder::decode(br#"{"e": "listenKeyExpired","E": "1743606297156","listenKey": "FdffIUjdfd343DtLMw2tKS87iL2HpYRniDWpkoxWCb4fwP2yzJXalBlBNnz471cE"}"#).unwrap();
+        assert_eq!("listenKeyExpired", listen_key_expired.event_type());
+        assert_eq!(1743606297156, listen_key_expired.event_time());
+        assert_eq!("FdffIUjdfd343DtLMw2tKS87iL2HpYRniDWpkoxWCb4fwP2yzJXalBlBNnz471cE", listen_key_expired.listen_key());
+    }
+}

sje/array_of_objects/iter.rs

@@ -0,0 +1,117 @@
+use sje_derive::Decoder;
+use std::str::FromStr;
+
+#[derive(Debug, Copy, Clone, PartialEq)]
+#[repr(transparent)]
+pub struct Price(f64);
+
+impl FromStr for Price {
+    type Err = <f64 as FromStr>::Err;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(s.parse()?))
+    }
+}
+
+#[derive(Debug, Copy, Clone, PartialEq)]
+#[repr(transparent)]
+pub struct Quantity(f64);
+
+impl FromStr for Quantity {
+    type Err = <f64 as FromStr>::Err;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Ok(Self(s.parse()?))
+    }
+}
+
+#[derive(Decoder, Debug)]
+#[sje(object)]
+#[allow(dead_code)]
+pub struct L2Update {
+    #[sje(rename = "e", len = 11)]
+    event_type: String,
+    #[sje(rename = "b")]
+    bids: Vec<(Price, Quantity)>,
+    #[sje(rename = "a")]
+    asks: Vec<(Price, Quantity)>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn should_iterate_over_bids_and_asks() {
+        let update = L2UpdateDecoder::decode(
+            br#"{"e":"depthUpdate","b":[["2.6461","6404.9"],["2.6468","22540.8"]],"a":[["2.6461","6404.9"],["2.6468","22540.8"]]}"#,
+        ).unwrap();
+        let mut bids = update.bids().into_iter();
+        assert_eq!(2, update.bids_count());
+        assert_eq!(2, bids.len());
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), bids.next());
+        assert_eq!(1, bids.len());
+        assert_eq!(Some((Price(2.6468), Quantity(22540.8))), bids.next());
+        assert_eq!(0, bids.len());
+        assert_eq!(None, bids.next());
+        assert_eq!(0, bids.len());
+        let mut asks = update.asks().into_iter();
+        assert_eq!(2, update.asks_count());
+        assert_eq!(2, asks.len());
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), asks.next());
+        assert_eq!(1, asks.len());
+        assert_eq!(Some((Price(2.6468), Quantity(22540.8))), asks.next());
+        assert_eq!(0, asks.len());
+        assert_eq!(None, asks.next());
+        assert_eq!(0, asks.len());
+
+        let update =
+            L2UpdateDecoder::decode(br#"{"e":"depthUpdate","b":[["2.6461","6404.9"]],"a":[["2.6461","6404.9"]]}"#)
+                .unwrap();
+        let mut bids = update.bids().into_iter();
+        assert_eq!(1, update.bids_count());
+        assert_eq!(1, bids.len());
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), bids.next());
+        assert_eq!(0, bids.len());
+        assert_eq!(None, bids.next());
+        assert_eq!(0, bids.len());
+        let mut asks = update.asks().into_iter();
+        assert_eq!(1, update.asks_count());
+        assert_eq!(1, asks.len());
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), asks.next());
+        assert_eq!(0, asks.len());
+        assert_eq!(None, asks.next());
+        assert_eq!(0, asks.len());
+
+        let update = L2UpdateDecoder::decode(br#"{"e":"depthUpdate","b":[],"a":[]}"#).unwrap();
+        let mut bids = update.bids().into_iter();
+        assert_eq!(0, update.bids_count());
+        assert_eq!(0, bids.len());
+        assert_eq!(None, bids.next());
+        assert_eq!(0, bids.len());
+        let mut asks = update.asks().into_iter();
+        assert_eq!(0, update.asks_count());
+        assert_eq!(0, asks.len());
+        assert_eq!(None, asks.next());
+        assert_eq!(0, asks.len());
+    }
+
+    #[test]
+    fn should_convert_to_owned() {
+        let update = L2UpdateDecoder::decode(
+            br#"{"e":"depthUpdate","b":[["2.6461","6404.9"],["2.6468","22540.8"]],"a":[["2.6461","6404.9"],["2.6468","22540.8"]]}"#,
+        ).unwrap();
+        let update: L2Update = update.into();
+        assert_eq!("depthUpdate", update.event_type);
+
+        let mut bids = update.bids.into_iter();
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), bids.next());
+        assert_eq!(Some((Price(2.6468), Quantity(22540.8))), bids.next());
+        assert_eq!(None, bids.next());
+
+        let mut asks = update.asks.into_iter();
+        assert_eq!(Some((Price(2.6461), Quantity(6404.9))), asks.next());
+        assert_eq!(Some((Price(2.6468), Quantity(22540.8))), asks.next());
+        assert_eq!(None, asks.next());
+    }
+}

sje/benches/ticker.rs

@@ -8,7 +8,7 @@ const JSON: &[u8] = br#"{"e":"bookTicker","u":6780157666962,"s":"BTCUSDT","b":"9
 #[sje(object)]
 #[allow(dead_code)]
 pub struct Ticker {
-    #[sje(rename = "e", len = 10, offset = 2)]
+    #[sje(rename = "e", len = 10)]
     #[serde(rename = "e")]
     event_type: String,
     #[sje(rename = "u", len = 13)]