Skip to main content

zero_client/json/
serde_value.rs

1//! [`Value`] and serde, behind the `serde` feature: [`to_value`] writes any
2//! `Serialize` type as a value, [`from_value`] reads one back as any
3//! `Deserialize` type, and `Value` and [`Object`] are both themselves.
4//!
5//! A struct's fields are written in the order they are declared, as a JS
6//! object literal keeps its properties, and a JS-property-order object
7//! keeps integer-like keys first. Numbers are `f64`, as in JS: an integer
8//! field reads a number without a fraction that is exactly an integer, and
9//! one past 2^53 isn't exact.
10
11use super::{Object, Value};
12use serde::de::{self, DeserializeOwned, IntoDeserializer, Visitor};
13use serde::ser::{self, Serialize};
14use serde::{Deserialize, Deserializer, Serializer, forward_to_deserialize_any};
15use std::fmt;
16
17/// Why a value couldn't be written or read.
18#[derive(Clone, Debug, PartialEq, Eq)]
19pub struct SerdeError(pub String);
20
21impl fmt::Display for SerdeError {
22    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
23        f.write_str(&self.0)
24    }
25}
26
27impl std::error::Error for SerdeError {}
28
29impl ser::Error for SerdeError {
30    fn custom<T: fmt::Display>(msg: T) -> Self {
31        SerdeError(msg.to_string())
32    }
33}
34
35impl de::Error for SerdeError {
36    fn custom<T: fmt::Display>(msg: T) -> Self {
37        SerdeError(msg.to_string())
38    }
39}
40
41/// `value` as a JSON value.
42pub fn to_value<T: Serialize + ?Sized>(value: &T) -> Result<Value, SerdeError> {
43    value.serialize(ValueSerializer)
44}
45
46/// `value` read as a `T`.
47pub fn from_value<T: DeserializeOwned>(value: &Value) -> Result<T, SerdeError> {
48    T::deserialize(value)
49}
50
51// MARK: Writing
52
53struct ValueSerializer;
54
55/// The largest integer a `f64` holds exactly, 2^53.
56const MAX_EXACT: f64 = 9_007_199_254_740_992.0;
57
58fn variant(name: &str, value: Value) -> Value {
59    let mut o = Object::new();
60    o.insert(name, value);
61    Value::Object(o)
62}
63
64impl Serializer for ValueSerializer {
65    type Ok = Value;
66    type Error = SerdeError;
67    type SerializeSeq = SeqSerializer;
68    type SerializeTuple = SeqSerializer;
69    type SerializeTupleStruct = SeqSerializer;
70    type SerializeTupleVariant = SeqSerializer;
71    type SerializeMap = MapSerializer;
72    type SerializeStruct = MapSerializer;
73    type SerializeStructVariant = MapSerializer;
74
75    fn serialize_bool(self, v: bool) -> Result<Value, SerdeError> {
76        Ok(Value::Bool(v))
77    }
78    fn serialize_i8(self, v: i8) -> Result<Value, SerdeError> {
79        Ok(Value::Number(v.into()))
80    }
81    fn serialize_i16(self, v: i16) -> Result<Value, SerdeError> {
82        Ok(Value::Number(v.into()))
83    }
84    fn serialize_i32(self, v: i32) -> Result<Value, SerdeError> {
85        Ok(Value::Number(v.into()))
86    }
87    fn serialize_i64(self, v: i64) -> Result<Value, SerdeError> {
88        Ok(Value::Number(v as f64))
89    }
90    fn serialize_u8(self, v: u8) -> Result<Value, SerdeError> {
91        Ok(Value::Number(v.into()))
92    }
93    fn serialize_u16(self, v: u16) -> Result<Value, SerdeError> {
94        Ok(Value::Number(v.into()))
95    }
96    fn serialize_u32(self, v: u32) -> Result<Value, SerdeError> {
97        Ok(Value::Number(v.into()))
98    }
99    fn serialize_u64(self, v: u64) -> Result<Value, SerdeError> {
100        Ok(Value::Number(v as f64))
101    }
102    fn serialize_f32(self, v: f32) -> Result<Value, SerdeError> {
103        Ok(Value::Number(v.into()))
104    }
105    fn serialize_f64(self, v: f64) -> Result<Value, SerdeError> {
106        Ok(Value::Number(v))
107    }
108    fn serialize_char(self, v: char) -> Result<Value, SerdeError> {
109        Ok(Value::String(v.to_string()))
110    }
111    fn serialize_str(self, v: &str) -> Result<Value, SerdeError> {
112        Ok(Value::String(v.to_owned()))
113    }
114    fn serialize_bytes(self, v: &[u8]) -> Result<Value, SerdeError> {
115        Ok(Value::Array(
116            v.iter().map(|b| Value::Number((*b).into())).collect(),
117        ))
118    }
119    fn serialize_none(self) -> Result<Value, SerdeError> {
120        Ok(Value::Null)
121    }
122    fn serialize_some<T: Serialize + ?Sized>(self, value: &T) -> Result<Value, SerdeError> {
123        value.serialize(self)
124    }
125    fn serialize_unit(self) -> Result<Value, SerdeError> {
126        Ok(Value::Null)
127    }
128    fn serialize_unit_struct(self, _: &'static str) -> Result<Value, SerdeError> {
129        Ok(Value::Null)
130    }
131    fn serialize_unit_variant(
132        self,
133        _: &'static str,
134        _: u32,
135        variant: &'static str,
136    ) -> Result<Value, SerdeError> {
137        Ok(Value::String(variant.to_owned()))
138    }
139    fn serialize_newtype_struct<T: Serialize + ?Sized>(
140        self,
141        _: &'static str,
142        value: &T,
143    ) -> Result<Value, SerdeError> {
144        value.serialize(self)
145    }
146    fn serialize_newtype_variant<T: Serialize + ?Sized>(
147        self,
148        _: &'static str,
149        _: u32,
150        name: &'static str,
151        value: &T,
152    ) -> Result<Value, SerdeError> {
153        Ok(variant(name, value.serialize(self)?))
154    }
155    fn serialize_seq(self, len: Option<usize>) -> Result<SeqSerializer, SerdeError> {
156        Ok(SeqSerializer {
157            variant: None,
158            items: Vec::with_capacity(len.unwrap_or(0)),
159        })
160    }
161    fn serialize_tuple(self, len: usize) -> Result<SeqSerializer, SerdeError> {
162        self.serialize_seq(Some(len))
163    }
164    fn serialize_tuple_struct(
165        self,
166        _: &'static str,
167        len: usize,
168    ) -> Result<SeqSerializer, SerdeError> {
169        self.serialize_seq(Some(len))
170    }
171    fn serialize_tuple_variant(
172        self,
173        _: &'static str,
174        _: u32,
175        name: &'static str,
176        len: usize,
177    ) -> Result<SeqSerializer, SerdeError> {
178        Ok(SeqSerializer {
179            variant: Some(name),
180            items: Vec::with_capacity(len),
181        })
182    }
183    fn serialize_map(self, _: Option<usize>) -> Result<MapSerializer, SerdeError> {
184        Ok(MapSerializer {
185            variant: None,
186            object: Object::new(),
187            key: None,
188        })
189    }
190    fn serialize_struct(self, _: &'static str, _: usize) -> Result<MapSerializer, SerdeError> {
191        self.serialize_map(None)
192    }
193    fn serialize_struct_variant(
194        self,
195        _: &'static str,
196        _: u32,
197        name: &'static str,
198        _: usize,
199    ) -> Result<MapSerializer, SerdeError> {
200        Ok(MapSerializer {
201            variant: Some(name),
202            object: Object::new(),
203            key: None,
204        })
205    }
206}
207
208struct SeqSerializer {
209    variant: Option<&'static str>,
210    items: Vec<Value>,
211}
212
213impl SeqSerializer {
214    fn push<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
215        self.items.push(value.serialize(ValueSerializer)?);
216        Ok(())
217    }
218
219    fn done(self) -> Value {
220        let array = Value::Array(self.items);
221        match self.variant {
222            Some(name) => variant(name, array),
223            None => array,
224        }
225    }
226}
227
228impl ser::SerializeSeq for SeqSerializer {
229    type Ok = Value;
230    type Error = SerdeError;
231    fn serialize_element<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
232        self.push(value)
233    }
234    fn end(self) -> Result<Value, SerdeError> {
235        Ok(self.done())
236    }
237}
238
239impl ser::SerializeTuple for SeqSerializer {
240    type Ok = Value;
241    type Error = SerdeError;
242    fn serialize_element<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
243        self.push(value)
244    }
245    fn end(self) -> Result<Value, SerdeError> {
246        Ok(self.done())
247    }
248}
249
250impl ser::SerializeTupleStruct for SeqSerializer {
251    type Ok = Value;
252    type Error = SerdeError;
253    fn serialize_field<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
254        self.push(value)
255    }
256    fn end(self) -> Result<Value, SerdeError> {
257        Ok(self.done())
258    }
259}
260
261impl ser::SerializeTupleVariant for SeqSerializer {
262    type Ok = Value;
263    type Error = SerdeError;
264    fn serialize_field<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
265        self.push(value)
266    }
267    fn end(self) -> Result<Value, SerdeError> {
268        Ok(self.done())
269    }
270}
271
272struct MapSerializer {
273    variant: Option<&'static str>,
274    object: Object,
275    key: Option<String>,
276}
277
278impl MapSerializer {
279    fn done(self) -> Value {
280        let object = Value::Object(self.object);
281        match self.variant {
282            Some(name) => variant(name, object),
283            None => object,
284        }
285    }
286}
287
288impl ser::SerializeMap for MapSerializer {
289    type Ok = Value;
290    type Error = SerdeError;
291    fn serialize_key<T: Serialize + ?Sized>(&mut self, key: &T) -> Result<(), SerdeError> {
292        // A key is a string, as a JS object's property is: a number or a
293        // bool key is written as JS would name it.
294        let key = match key.serialize(ValueSerializer)? {
295            Value::String(s) => s,
296            v @ (Value::Number(_) | Value::Bool(_)) => v.to_string(),
297            v => {
298                return Err(SerdeError(format!(
299                    "a map key must be a string, not {}",
300                    v.type_name()
301                )));
302            }
303        };
304        self.key = Some(key);
305        Ok(())
306    }
307    fn serialize_value<T: Serialize + ?Sized>(&mut self, value: &T) -> Result<(), SerdeError> {
308        let key = self.key.take().expect("serialize_key comes first");
309        self.object.insert(key, value.serialize(ValueSerializer)?);
310        Ok(())
311    }
312    fn end(self) -> Result<Value, SerdeError> {
313        Ok(self.done())
314    }
315}
316
317impl ser::SerializeStruct for MapSerializer {
318    type Ok = Value;
319    type Error = SerdeError;
320    fn serialize_field<T: Serialize + ?Sized>(
321        &mut self,
322        key: &'static str,
323        value: &T,
324    ) -> Result<(), SerdeError> {
325        self.object.insert(key, value.serialize(ValueSerializer)?);
326        Ok(())
327    }
328    fn end(self) -> Result<Value, SerdeError> {
329        Ok(self.done())
330    }
331}
332
333impl ser::SerializeStructVariant for MapSerializer {
334    type Ok = Value;
335    type Error = SerdeError;
336    fn serialize_field<T: Serialize + ?Sized>(
337        &mut self,
338        key: &'static str,
339        value: &T,
340    ) -> Result<(), SerdeError> {
341        ser::SerializeStruct::serialize_field(self, key, value)
342    }
343    fn end(self) -> Result<Value, SerdeError> {
344        Ok(self.done())
345    }
346}
347
348impl Serialize for Value {
349    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
350        match self {
351            Value::Null => s.serialize_unit(),
352            Value::Bool(b) => s.serialize_bool(*b),
353            // An integer as an integer, so a format with integers keeps it
354            // one.
355            Value::Number(n) if n.fract() == 0.0 && n.abs() < MAX_EXACT => {
356                s.serialize_i64(*n as i64)
357            }
358            Value::Number(n) => s.serialize_f64(*n),
359            Value::String(v) => s.serialize_str(v),
360            Value::Array(a) => s.collect_seq(a),
361            Value::Object(o) => o.serialize(s),
362        }
363    }
364}
365
366impl Serialize for Object {
367    fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
368        s.collect_map(self.iter())
369    }
370}
371
372// MARK: Reading
373
374impl<'de> Deserializer<'de> for &'de Value {
375    type Error = SerdeError;
376
377    fn deserialize_any<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, SerdeError> {
378        match self {
379            Value::Null => visitor.visit_unit(),
380            Value::Bool(b) => visitor.visit_bool(*b),
381            // An exact integer reads as one, so integer fields take it.
382            Value::Number(n) if n.fract() == 0.0 && n.abs() < MAX_EXACT => {
383                if *n < 0.0 {
384                    visitor.visit_i64(*n as i64)
385                } else {
386                    visitor.visit_u64(*n as u64)
387                }
388            }
389            Value::Number(n) => visitor.visit_f64(*n),
390            Value::String(s) => visitor.visit_borrowed_str(s),
391            Value::Array(a) => visitor.visit_seq(de::value::SeqDeserializer::new(a.iter())),
392            Value::Object(o) => visitor.visit_map(de::value::MapDeserializer::new(
393                o.iter().map(|(k, v)| (k.as_str(), v)),
394            )),
395        }
396    }
397
398    fn deserialize_option<V: Visitor<'de>>(self, visitor: V) -> Result<V::Value, SerdeError> {
399        match self {
400            Value::Null => visitor.visit_none(),
401            v => visitor.visit_some(v),
402        }
403    }
404
405    fn deserialize_newtype_struct<V: Visitor<'de>>(
406        self,
407        _: &'static str,
408        visitor: V,
409    ) -> Result<V::Value, SerdeError> {
410        visitor.visit_newtype_struct(self)
411    }
412
413    fn deserialize_enum<V: Visitor<'de>>(
414        self,
415        _: &'static str,
416        _: &'static [&'static str],
417        visitor: V,
418    ) -> Result<V::Value, SerdeError> {
419        match self {
420            // A unit variant, by name.
421            Value::String(s) => visitor.visit_enum(s.as_str().into_deserializer()),
422            // Any other variant, as `{"<name>": <its value>}`.
423            Value::Object(o) if o.len() == 1 => {
424                let (name, value) = o.get_index(0).expect("one entry");
425                visitor.visit_enum(EnumAccess { name, value })
426            }
427            v => Err(SerdeError(format!(
428                "expected an enum variant, a string or an object with one key, got {}",
429                v.type_name()
430            ))),
431        }
432    }
433
434    forward_to_deserialize_any! {
435        bool i8 i16 i32 i64 i128 u8 u16 u32 u64 u128 f32 f64 char str string
436        bytes byte_buf unit unit_struct seq tuple tuple_struct map struct
437        identifier ignored_any
438    }
439}
440
441impl<'de> IntoDeserializer<'de, SerdeError> for &'de Value {
442    type Deserializer = Self;
443    fn into_deserializer(self) -> Self {
444        self
445    }
446}
447
448struct EnumAccess<'de> {
449    name: &'de str,
450    value: &'de Value,
451}
452
453impl<'de> de::EnumAccess<'de> for EnumAccess<'de> {
454    type Error = SerdeError;
455    type Variant = &'de Value;
456    fn variant_seed<V: de::DeserializeSeed<'de>>(
457        self,
458        seed: V,
459    ) -> Result<(V::Value, &'de Value), SerdeError> {
460        let name = seed.deserialize(self.name.into_deserializer())?;
461        Ok((name, self.value))
462    }
463}
464
465impl<'de> de::VariantAccess<'de> for &'de Value {
466    type Error = SerdeError;
467    fn unit_variant(self) -> Result<(), SerdeError> {
468        match self {
469            Value::Null => Ok(()),
470            v => Err(SerdeError(format!(
471                "expected a unit variant, got {}",
472                v.type_name()
473            ))),
474        }
475    }
476    fn newtype_variant_seed<T: de::DeserializeSeed<'de>>(
477        self,
478        seed: T,
479    ) -> Result<T::Value, SerdeError> {
480        seed.deserialize(self)
481    }
482    fn tuple_variant<V: Visitor<'de>>(self, _: usize, visitor: V) -> Result<V::Value, SerdeError> {
483        self.deserialize_seq(visitor)
484    }
485    fn struct_variant<V: Visitor<'de>>(
486        self,
487        _: &'static [&'static str],
488        visitor: V,
489    ) -> Result<V::Value, SerdeError> {
490        self.deserialize_map(visitor)
491    }
492}
493
494impl<'de> Deserialize<'de> for Value {
495    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Value, D::Error> {
496        d.deserialize_any(ValueVisitor)
497    }
498}
499
500impl<'de> Deserialize<'de> for Object {
501    fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Object, D::Error> {
502        match Value::deserialize(d)? {
503            Value::Object(o) => Ok(o),
504            v => Err(de::Error::custom(format!(
505                "expected an object, got {}",
506                v.type_name()
507            ))),
508        }
509    }
510}
511
512struct ValueVisitor;
513
514impl<'de> Visitor<'de> for ValueVisitor {
515    type Value = Value;
516
517    fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
518        f.write_str("a JSON value")
519    }
520    fn visit_bool<E>(self, v: bool) -> Result<Value, E> {
521        Ok(Value::Bool(v))
522    }
523    fn visit_i64<E>(self, v: i64) -> Result<Value, E> {
524        Ok(Value::Number(v as f64))
525    }
526    fn visit_u64<E>(self, v: u64) -> Result<Value, E> {
527        Ok(Value::Number(v as f64))
528    }
529    fn visit_f64<E>(self, v: f64) -> Result<Value, E> {
530        Ok(Value::Number(v))
531    }
532    fn visit_str<E>(self, v: &str) -> Result<Value, E> {
533        Ok(Value::String(v.to_owned()))
534    }
535    fn visit_string<E>(self, v: String) -> Result<Value, E> {
536        Ok(Value::String(v))
537    }
538    fn visit_unit<E>(self) -> Result<Value, E> {
539        Ok(Value::Null)
540    }
541    fn visit_none<E>(self) -> Result<Value, E> {
542        Ok(Value::Null)
543    }
544    fn visit_some<D: Deserializer<'de>>(self, d: D) -> Result<Value, D::Error> {
545        Value::deserialize(d)
546    }
547    fn visit_seq<A: de::SeqAccess<'de>>(self, mut seq: A) -> Result<Value, A::Error> {
548        let mut items = Vec::with_capacity(seq.size_hint().unwrap_or(0));
549        while let Some(v) = seq.next_element()? {
550            items.push(v);
551        }
552        Ok(Value::Array(items))
553    }
554    fn visit_map<A: de::MapAccess<'de>>(self, mut map: A) -> Result<Value, A::Error> {
555        let mut o = Object::new();
556        while let Some((k, v)) = map.next_entry::<String, Value>()? {
557            o.insert(k, v);
558        }
559        Ok(Value::Object(o))
560    }
561}
562
563#[cfg(test)]
564mod tests {
565    use super::*;
566    use crate::json;
567
568    #[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
569    #[serde(rename_all = "camelCase")]
570    struct Args {
571        project_name: String,
572        #[serde(rename = "issueID")]
573        issue_id: Option<String>,
574        #[serde(skip_serializing_if = "Option::is_none")]
575        limit: Option<i64>,
576        dir: Dir,
577        ratio: f64,
578        tags: Vec<String>,
579        shape: Shape,
580    }
581
582    #[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
583    #[serde(rename_all = "lowercase")]
584    enum Dir {
585        Asc,
586    }
587
588    #[derive(Debug, PartialEq, serde::Serialize, serde::Deserialize)]
589    enum Shape {
590        Circle { r: u32 },
591        Pair(i32, i32),
592    }
593
594    #[test]
595    fn round_trips_in_declared_field_order() {
596        let args = Args {
597            project_name: "Zero".into(),
598            issue_id: None,
599            limit: Some(-3),
600            dir: Dir::Asc,
601            ratio: 0.5,
602            tags: vec!["a".into()],
603            shape: Shape::Circle { r: 2 },
604        };
605        let v = to_value(&args).unwrap();
606        // Fields in the order they are declared, as `JSON.stringify` writes
607        // an object literal with the same properties.
608        assert_eq!(
609            json::stringify(&v),
610            r#"{"projectName":"Zero","issueID":null,"limit":-3,"dir":"asc","ratio":0.5,"tags":["a"],"shape":{"Circle":{"r":2}}}"#
611        );
612        assert_eq!(from_value::<Args>(&v).unwrap(), args);
613        let pair = to_value(&Shape::Pair(1, -2)).unwrap();
614        assert_eq!(json::stringify(&pair), r#"{"Pair":[1,-2]}"#);
615        assert_eq!(from_value::<Shape>(&pair).unwrap(), Shape::Pair(1, -2));
616    }
617
618    #[test]
619    fn integers_read_only_when_exact() {
620        assert_eq!(from_value::<i64>(&Value::Number(4.0)).unwrap(), 4);
621        assert_eq!(from_value::<u8>(&Value::Number(255.0)).unwrap(), 255);
622        assert!(from_value::<i64>(&Value::Number(4.5)).is_err());
623        assert!(from_value::<u8>(&Value::Number(-1.0)).is_err());
624        assert_eq!(from_value::<f64>(&Value::Number(4.0)).unwrap(), 4.0);
625        // A missing optional field and a null one both read as `None`.
626        let v = json::parse(
627            r#"{"projectName":"Zero","dir":"asc","ratio":1,"tags":[],"shape":{"Pair":[0,0]}}"#,
628        )
629        .unwrap();
630        let args: Args = from_value(&v).unwrap();
631        assert_eq!((args.issue_id, args.limit, args.ratio), (None, None, 1.0));
632        assert!(from_value::<Args>(&json::parse(r#"{"projectName":1}"#).unwrap()).is_err());
633    }
634
635    #[test]
636    fn values_are_themselves() {
637        let text = r#"{"b":[1,2.5,null,true,"x"],"10":{},"a":-7}"#;
638        let v = json::parse(text).unwrap();
639        let again: Value = from_value(&to_value(&v).unwrap()).unwrap();
640        assert_eq!(json::stringify(&again), json::stringify(&v));
641    }
642}