Skip to main content

wabot_core/storable/
mod.rs

1//! Storable — generic, serialization-safe data container.
2//!
3//! In `wabot-ts`, `Storable<D>` exists to enforce that `D` is "JSON-safe"
4//! (no functions, only primitives/arrays/objects), through the recursive
5//! `IStorableData<D>` mapped type. In Rust the equivalent contract is
6//! expressed by the `serde::Serialize` + `serde::DeserializeOwned` bounds —
7//! the type system rejects any `D` that isn't round-trippable.
8//!
9//! ```rust,no_run
10//! use serde::{Deserialize, Serialize};
11//! use wabot_core::storable::Storable;
12//!
13//! #[derive(Debug, Clone, Serialize, Deserialize)]
14//! struct PingData { ts: i64, ok: bool }
15//!
16//! let s = Storable::new(PingData { ts: 0, ok: true });
17//! let json = serde_json::to_string(&s).unwrap();
18//! let back: Storable<PingData> = serde_json::from_str(&json).unwrap();
19//! assert_eq!(back.data().ts, s.data().ts);
20//! ```
21
22use serde::{de::DeserializeOwned, Deserialize, Serialize};
23
24/// The bound a payload type must satisfy to be wrapped in a `Storable`.
25/// `wabot-ts` calls this `IStorableType<T>` — in Rust we lean on `serde`.
26pub trait StorableData: Serialize + DeserializeOwned + Send + Sync + 'static {}
27impl<T> StorableData for T where T: Serialize + DeserializeOwned + Send + Sync + 'static {}
28
29/// Generic data container, serialized transparently as its inner `D`.
30///
31/// The `data` field is `pub(crate)` rather than truly private so subtypes
32/// (notably [`crate::entity::Entity`]) can manipulate it without going
33/// through accessors. External code should use [`Storable::data`] /
34/// [`Storable::data_mut`] / [`Storable::into_data`].
35///
36/// The explicit `#[serde(bound)]` is required because the trait bound on
37/// `D` doesn't, by itself, satisfy serde's "all generics must be
38/// (de)serialize" check on a transparent newtype.
39#[derive(Debug, Clone, Serialize, Deserialize)]
40#[serde(transparent)]
41#[serde(bound(
42    serialize = "D: ::serde::Serialize",
43    deserialize = "D: ::serde::de::DeserializeOwned"
44))]
45pub struct Storable<D: StorableData> {
46    pub(crate) data: D,
47}
48
49impl<D: StorableData> Storable<D> {
50    pub fn new(data: D) -> Self {
51        Self { data }
52    }
53
54    pub fn data(&self) -> &D {
55        &self.data
56    }
57
58    pub fn data_mut(&mut self) -> &mut D {
59        &mut self.data
60    }
61
62    pub fn into_data(self) -> D {
63        self.data
64    }
65}
66
67impl<D: StorableData + Default> Default for Storable<D> {
68    fn default() -> Self {
69        Self { data: D::default() }
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use super::*;
76    use serde::{Deserialize, Serialize};
77
78    #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
79    struct Sample {
80        a: i32,
81        b: String,
82    }
83
84    #[test]
85    fn round_trips_through_json() {
86        let s = Storable::new(Sample {
87            a: 1,
88            b: "hi".into(),
89        });
90        let json = serde_json::to_string(&s).unwrap();
91        // `#[serde(transparent)]` makes the wrapper invisible on the wire —
92        // matches the wabot-ts behaviour where Storable disappears in JSON.
93        assert_eq!(json, r#"{"a":1,"b":"hi"}"#);
94        let back: Storable<Sample> = serde_json::from_str(&json).unwrap();
95        assert_eq!(back.data(), s.data());
96    }
97}