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}