serde_map_to_array/lib.rs
1//! This crate provides unofficial serde helpers to support converting a map to a sequence of named
2//! key-value pairs for [human-readable encoding formats](Serializer::is_human_readable()).
3//!
4//! This allows for a stable schema in the face of a mutable map.
5//!
6//! For example, let's say we have a map containing the values
7//! `[(1, "one"), (2, "two"), (3, "three")]`. Encoded to JSON this is:
8//! ```json
9//! {"1":"one","2":"two","3":"three"}
10//! ```
11//! We cannot specify a schema for this JSON Object though unless the contents of the map are
12//! guaranteed to always contain three entries under the keys `1`, `2` and `3`.
13//!
14//! This crate allows for such a map to be encoded to a JSON Array of Objects, each containing
15//! exactly two elements with static names:
16//! ```json
17//! [{"key":1,"value":"one"},{"key":2,"value":"two"},{"key":3,"value":"three"}]
18//! ```
19//! for which a schema *can* be generated.
20//!
21//! Furthermore, this avoids encoding the key type of the map to a string.
22//!
23//! By default, the key-value pairs will be given the labels "key" and "value", but this can be
24//! modified by providing your own labels via a struct which implements [`KeyValueLabels`].
25//!
26//! Note that for binary (non-human-readable) encoding formats, default serialization and
27//! deserialization is retained.
28//!
29//! # `no_std`
30//!
31//! By default, the crate is `no_std`, but uses `alloc`. In this case, support for `BTreeMap`s and
32//! `BTreeMap`-like types is provided.
33//!
34//! If feature `std` is enabled then support for `HashMap`s and `HashMap`-like types is also
35//! provided, but `no_std` support is disabled.
36//!
37//! # Examples
38//!
39//! ## Using the default field values "key" and "value"
40//! ```
41//! use std::collections::BTreeMap;
42//! use serde::{Deserialize, Serialize};
43//! use serde_map_to_array::BTreeMapToArray;
44//!
45//! #[derive(Default, Serialize, Deserialize)]
46//! struct Data {
47//! #[serde(with = "BTreeMapToArray::<u64, String>")]
48//! inner: BTreeMap<u64, String>,
49//! }
50//!
51//! let mut data = Data::default();
52//! data.inner.insert(1, "one".to_string());
53//! data.inner.insert(2, "two".to_string());
54//!
55//! assert_eq!(
56//! serde_json::to_string(&data).unwrap(),
57//! r#"{"inner":[{"key":1,"value":"one"},{"key":2,"value":"two"}]}"#
58//! );
59//! ```
60//!
61//! ## Using non-default field labels
62//! ```
63//! # #[cfg(feature = "std")] { // make the doctest a no-op when "std" is disabled
64//! use std::collections::HashMap;
65//! use serde::{Deserialize, Serialize};
66//! use serde_map_to_array::{KeyValueLabels, HashMapToArray};
67//!
68//! struct MyKeyValueLabels;
69//!
70//! impl KeyValueLabels for MyKeyValueLabels {
71//! const KEY: &'static str = "id";
72//! const VALUE: &'static str = "name";
73//! }
74//!
75//! #[derive(Default, Serialize, Deserialize)]
76//! struct Data {
77//! #[serde(with = "HashMapToArray::<u64, String, MyKeyValueLabels>")]
78//! inner: HashMap<u64, String>,
79//! }
80//!
81//! let mut data = Data::default();
82//! data.inner.insert(1, "one".to_string());
83//! data.inner.insert(2, "two".to_string());
84//!
85//! // The hashmap orders the entries randomly.
86//! let expected_json = if *data.inner.keys().next().unwrap() == 1 {
87//! r#"{"inner":[{"id":1,"name":"one"},{"id":2,"name":"two"}]}"#
88//! } else {
89//! r#"{"inner":[{"id":2,"name":"two"},{"id":1,"name":"one"}]}"#
90//! };
91//!
92//! assert_eq!(serde_json::to_string(&data).unwrap(), expected_json);
93//! # }
94//! ```
95//!
96//! ## Using a custom `BTreeMap`-like type
97//! ```
98//! use std::collections::{btree_map, BTreeMap};
99//! use serde::{Deserialize, Serialize};
100//! use serde_map_to_array::{BTreeMapToArray, DefaultLabels};
101//!
102//! #[derive(Serialize, Deserialize)]
103//! struct MyMap(BTreeMap<u64, String>);
104//!
105//! /// We need to implement `IntoIterator` to allow serialization.
106//! impl<'a> IntoIterator for &'a MyMap {
107//! type Item = (&'a u64, &'a String);
108//! type IntoIter = btree_map::Iter<'a, u64, String>;
109//!
110//! fn into_iter(self) -> Self::IntoIter {
111//! self.0.iter()
112//! }
113//! }
114//!
115//! /// We need to implement `From<BTreeMap>` to allow deserialization.
116//! impl From<BTreeMap<u64, String>> for MyMap {
117//! fn from(map: BTreeMap<u64, String>) -> Self {
118//! MyMap(map)
119//! }
120//! }
121//!
122//! #[derive(Serialize, Deserialize)]
123//! struct Data {
124//! #[serde(with = "BTreeMapToArray::<u64, String, DefaultLabels, MyMap>")]
125//! inner: MyMap,
126//! }
127//! ```
128//!
129//! ## Using a `HashMap` with a non-standard hasher
130//! ```
131//! # #[cfg(feature = "std")] { // make the doctest a no-op when "std" is disabled
132//! use std::collections::HashMap;
133//! use serde::{Deserialize, Serialize};
134//! use hash_hasher::HashBuildHasher;
135//! use serde_map_to_array::{DefaultLabels, HashMapToArray};
136//!
137//! #[derive(Serialize, Deserialize)]
138//! struct Data {
139//! #[serde(with = "HashMapToArray::<u64, String, DefaultLabels, HashBuildHasher>")]
140//! inner: HashMap<u64, String, HashBuildHasher>,
141//! }
142//! # }
143//! ```
144//!
145//! ## Using a custom `HashMap`-like type
146//! ```
147//! # #[cfg(feature = "std")] { // make the doctest a no-op when "std" is disabled
148//! use std::collections::{hash_map::{self, RandomState}, HashMap};
149//! use serde::{Deserialize, Serialize};
150//! use serde_map_to_array::{DefaultLabels, HashMapToArray};
151//!
152//! #[derive(Serialize, Deserialize)]
153//! struct MyMap(HashMap<u64, String>);
154//!
155//! /// We need to implement `IntoIterator` to allow serialization.
156//! impl<'a> IntoIterator for &'a MyMap {
157//! type Item = (&'a u64, &'a String);
158//! type IntoIter = hash_map::Iter<'a, u64, String>;
159//!
160//! fn into_iter(self) -> Self::IntoIter {
161//! self.0.iter()
162//! }
163//! }
164//!
165//! /// We need to implement `From<HashMap>` to allow deserialization.
166//! impl From<HashMap<u64, String>> for MyMap {
167//! fn from(map: HashMap<u64, String>) -> Self {
168//! MyMap(map)
169//! }
170//! }
171//!
172//! #[derive(Serialize, Deserialize)]
173//! struct Data {
174//! #[serde(with = "HashMapToArray::<u64, String, DefaultLabels, RandomState, MyMap>")]
175//! inner: MyMap,
176//! }
177//! # }
178//! ```
179//!
180//! # JSON Schema Support
181//!
182//! Support for generating JSON schemas via [`schemars`](https://graham.cool/schemars) can be
183//! enabled by setting the feature `json-schema`.
184//!
185//! By default, the schema name of the KeyValue struct will be set to
186//! `"KeyValue_for_{K::schema_name()}_and_{V::schema_name()}"`, and the struct and its key and value
187//! fields will have no descriptions (normally generated from doc comments for the struct and its
188//! fields). Each of these can be modified by providing your own values via a struct which
189//! implements [`KeyValueJsonSchema`].
190
191#![cfg_attr(not(feature = "std"), no_std)]
192#![warn(missing_docs)]
193#![doc(test(attr(deny(warnings))))]
194#![cfg_attr(docsrs, feature(doc_auto_cfg))]
195
196#[doc = include_str!("../README.md")]
197#[cfg(all(doctest, feature = "std"))]
198pub struct ReadmeDoctests;
199
200#[cfg(test)]
201mod tests;
202
203extern crate alloc;
204
205use alloc::borrow::Cow;
206use alloc::collections::BTreeMap;
207use core::{fmt, marker::PhantomData};
208#[cfg(feature = "std")]
209use std::{
210 collections::{hash_map::RandomState, HashMap},
211 hash::{BuildHasher, Hash},
212};
213
214#[cfg(feature = "json-schema")]
215use schemars::{json_schema, JsonSchema, Schema, SchemaGenerator};
216
217use serde::{
218 de::{Error as SerdeError, MapAccess, SeqAccess, Visitor},
219 ser::{SerializeStruct, Serializer},
220 Deserialize, Deserializer, Serialize,
221};
222
223/// A converter between a `BTreeMap` or `BTreeMap`-like type and a sequence of named key-value pairs
224/// for human-readable encoding formats.
225///
226/// See [top-level docs](index.html) for example usage.
227pub struct BTreeMapToArray<K, V, N = DefaultLabels, T = BTreeMap<K, V>>(PhantomData<(K, V, N, T)>);
228
229impl<K, V, N, T> BTreeMapToArray<K, V, N, T> {
230 /// Serializes the given `map` to an array of named key-values if the serializer is
231 /// human-readable. Otherwise serializes the `map` as a map.
232 pub fn serialize<'a, S>(map: &'a T, serializer: S) -> Result<S::Ok, S::Error>
233 where
234 K: 'a + Serialize,
235 V: 'a + Serialize,
236 N: KeyValueLabels,
237 &'a T: IntoIterator<Item = (&'a K, &'a V)> + Serialize,
238 S: Serializer,
239 {
240 serialize::<K, V, N, T, S>(map, serializer)
241 }
242
243 /// Deserializes from a serialized array of named key-values into a map if the serializer is
244 /// human-readable. Otherwise deserializes from a serialized map.
245 pub fn deserialize<'de, D>(deserializer: D) -> Result<T, D::Error>
246 where
247 K: Deserialize<'de> + Ord,
248 V: Deserialize<'de>,
249 N: KeyValueLabels,
250 BTreeMap<K, V>: Into<T>,
251 T: Deserialize<'de>,
252 D: Deserializer<'de>,
253 {
254 let map = if deserializer.is_human_readable() {
255 deserializer.deserialize_seq(BTreeMapToArrayVisitor::<K, V, N>(PhantomData))
256 } else {
257 BTreeMap::<K, V>::deserialize(deserializer)
258 }?;
259 Ok(map.into())
260 }
261}
262
263#[cfg(feature = "json-schema")]
264impl<K, V, N, T> JsonSchema for BTreeMapToArray<K, V, N, T>
265where
266 K: JsonSchema,
267 V: JsonSchema,
268 N: KeyValueJsonSchema,
269{
270 fn schema_name() -> Cow<'static, str> {
271 Vec::<KeyValue<K, V, N>>::schema_name()
272 }
273
274 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
275 Vec::<KeyValue<K, V, N>>::json_schema(generator)
276 }
277}
278
279fn serialize<'a, K, V, N, T, S>(map: &'a T, serializer: S) -> Result<S::Ok, S::Error>
280where
281 K: 'a + Serialize,
282 V: 'a + Serialize,
283 N: KeyValueLabels,
284 &'a T: IntoIterator<Item = (&'a K, &'a V)> + Serialize,
285 S: Serializer,
286{
287 if serializer.is_human_readable() {
288 serializer.collect_seq(map.into_iter().map(|(key, value)| KeyValue {
289 key,
290 value,
291 _phantom: PhantomData::<N>,
292 }))
293 } else {
294 map.serialize(serializer)
295 }
296}
297
298/// A specifier of the labels to be used for the keys and values.
299pub trait KeyValueLabels {
300 /// The label for the keys.
301 const KEY: &'static str;
302 /// The label for the values.
303 const VALUE: &'static str;
304}
305
306#[cfg(feature = "json-schema")]
307/// A specifier of the JSON schema data to be used for the KeyValue struct.
308pub trait KeyValueJsonSchema: KeyValueLabels {
309 /// The value to use for `Schemars::schema_name()` of the KeyValue struct.
310 ///
311 /// If `None`, then a default of `"KeyValue_for_{K::schema_name()}_and_{V::schema_name()}"` is
312 /// applied.
313 const JSON_SCHEMA_KV_NAME: Option<&'static str> = None;
314 /// The description applied to the KeyValue struct.
315 const JSON_SCHEMA_KV_DESCRIPTION: Option<&'static str> = None;
316 /// The description applied to the key of the KeyValue struct.
317 const JSON_SCHEMA_KEY_DESCRIPTION: Option<&'static str> = None;
318 /// The description applied to the value of the KeyValue struct.
319 const JSON_SCHEMA_VALUE_DESCRIPTION: Option<&'static str> = None;
320}
321
322/// A specifier of the default labels to be used for the keys and values.
323///
324/// This struct implements [`KeyValueLabels`] setting key labels to "key" and value labels to
325/// "value".
326pub struct DefaultLabels;
327
328impl KeyValueLabels for DefaultLabels {
329 const KEY: &'static str = "key";
330 const VALUE: &'static str = "value";
331}
332
333#[cfg(feature = "json-schema")]
334impl KeyValueJsonSchema for DefaultLabels {}
335
336/// A helper to support serialization and deserialization for human-readable encoding formats where
337/// the fields `key` and `value` have their labels replaced by the values specified in `N::KEY` and
338/// `N::VALUE`.
339struct KeyValue<K, V, N> {
340 key: K,
341 value: V,
342 _phantom: PhantomData<N>,
343}
344
345impl<K, V, N> Serialize for KeyValue<K, V, N>
346where
347 K: Serialize,
348 V: Serialize,
349 N: KeyValueLabels,
350{
351 fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
352 let mut state = serializer.serialize_struct("KeyValue", 2)?;
353 state.serialize_field(N::KEY, &self.key)?;
354 state.serialize_field(N::VALUE, &self.value)?;
355 state.end()
356 }
357}
358
359impl<K, V, N: KeyValueLabels> KeyValue<K, V, N> {
360 const FIELDS: &'static [&'static str] = &[N::KEY, N::VALUE];
361}
362
363impl<'de, K, V, N> Deserialize<'de> for KeyValue<K, V, N>
364where
365 K: Deserialize<'de>,
366 V: Deserialize<'de>,
367 N: KeyValueLabels,
368{
369 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
370 enum Field<N: KeyValueLabels> {
371 Key,
372 Value(PhantomData<N>),
373 }
374
375 impl<'de, N: KeyValueLabels> Deserialize<'de> for Field<N> {
376 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Field<N>, D::Error> {
377 struct FieldVisitor<N>(PhantomData<N>);
378
379 impl<'de, N: KeyValueLabels> Visitor<'de> for FieldVisitor<N> {
380 type Value = Field<N>;
381
382 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
383 write!(formatter, "`{}` or `{}`", N::KEY, N::VALUE)
384 }
385
386 fn visit_str<E: SerdeError>(self, value: &str) -> Result<Field<N>, E> {
387 if value == N::KEY {
388 Ok(Field::Key)
389 } else if value == N::VALUE {
390 Ok(Field::Value(PhantomData))
391 } else {
392 Err(SerdeError::unknown_field(value, &[N::KEY, N::VALUE]))
393 }
394 }
395 }
396
397 deserializer.deserialize_identifier(FieldVisitor(PhantomData))
398 }
399 }
400
401 struct KvVisitor<K, V, N>(PhantomData<(K, V, N)>);
402
403 impl<'de, K, V, N> Visitor<'de> for KvVisitor<K, V, N>
404 where
405 K: Deserialize<'de>,
406 V: Deserialize<'de>,
407 N: KeyValueLabels,
408 {
409 type Value = KeyValue<K, V, N>;
410
411 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
412 formatter.write_str("struct KeyValue")
413 }
414
415 fn visit_seq<SeqA: SeqAccess<'de>>(
416 self,
417 mut seq: SeqA,
418 ) -> Result<KeyValue<K, V, N>, SeqA::Error> {
419 let key = seq
420 .next_element()?
421 .ok_or_else(|| SerdeError::invalid_length(0, &self))?;
422 let value = seq
423 .next_element()?
424 .ok_or_else(|| SerdeError::invalid_length(1, &self))?;
425 Ok(KeyValue {
426 key,
427 value,
428 _phantom: PhantomData,
429 })
430 }
431
432 fn visit_map<MapA: MapAccess<'de>>(
433 self,
434 mut map: MapA,
435 ) -> Result<KeyValue<K, V, N>, MapA::Error> {
436 let mut ret_key = None;
437 let mut ret_value = None;
438 while let Some(key) = map.next_key::<Field<N>>()? {
439 match key {
440 Field::Key => {
441 if ret_key.is_some() {
442 return Err(SerdeError::duplicate_field(N::KEY));
443 }
444 ret_key = Some(map.next_value()?);
445 }
446 Field::Value(_) => {
447 if ret_value.is_some() {
448 return Err(SerdeError::duplicate_field(N::VALUE));
449 }
450 ret_value = Some(map.next_value()?);
451 }
452 }
453 }
454 let key = ret_key.ok_or_else(|| SerdeError::missing_field(N::KEY))?;
455 let value = ret_value.ok_or_else(|| SerdeError::missing_field(N::VALUE))?;
456 Ok(KeyValue {
457 key,
458 value,
459 _phantom: PhantomData,
460 })
461 }
462 }
463
464 deserializer.deserialize_struct("KeyValue", Self::FIELDS, KvVisitor::<_, _, N>(PhantomData))
465 }
466}
467
468#[cfg(feature = "json-schema")]
469impl<K, V, N> JsonSchema for KeyValue<K, V, N>
470where
471 K: JsonSchema,
472 V: JsonSchema,
473 N: KeyValueJsonSchema,
474{
475 fn schema_name() -> Cow<'static, str> {
476 match N::JSON_SCHEMA_KV_NAME {
477 Some(name) => Cow::Borrowed(name),
478 None => Cow::Owned(format!(
479 "KeyValue_for_{}_and_{}",
480 K::schema_name(),
481 V::schema_name()
482 )),
483 }
484 }
485
486 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
487 let apply_description_if_set = |schema: &mut Schema, maybe_description: Option<&str>| {
488 if let Some(description) = maybe_description {
489 schema
490 .ensure_object()
491 .insert("description".into(), description.into());
492 }
493 };
494
495 let mut key_schema = generator.subschema_for::<K>();
496 apply_description_if_set(&mut key_schema, N::JSON_SCHEMA_KEY_DESCRIPTION);
497
498 let mut value_schema = generator.subschema_for::<V>();
499 apply_description_if_set(&mut value_schema, N::JSON_SCHEMA_VALUE_DESCRIPTION);
500
501 let mut schema: Schema = json_schema!({
502 "type": "object",
503 "properties": {
504 N::KEY: key_schema,
505 N::VALUE: value_schema,
506 }
507 });
508 apply_description_if_set(&mut schema, N::JSON_SCHEMA_KV_DESCRIPTION);
509
510 let required = schema
511 .ensure_object()
512 .entry("required")
513 .or_insert(serde_json::Value::Array(Vec::new()))
514 .as_array_mut()
515 .expect("`required` should be an array");
516 required.push(N::KEY.into());
517 required.push(N::VALUE.into());
518
519 schema
520 }
521}
522
523struct BTreeMapToArrayVisitor<K, V, N>(PhantomData<(K, V, N)>);
524
525impl<'de, K, V, N> Visitor<'de> for BTreeMapToArrayVisitor<K, V, N>
526where
527 K: Deserialize<'de> + Ord,
528 V: Deserialize<'de>,
529 N: KeyValueLabels,
530{
531 type Value = BTreeMap<K, V>;
532
533 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
534 formatter.write_str("a BTreeMapToArray")
535 }
536
537 fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
538 let mut map = BTreeMap::new();
539 while let Some(entry) = seq.next_element::<KeyValue<K, V, N>>()? {
540 map.insert(entry.key, entry.value);
541 }
542 Ok(map)
543 }
544}
545
546/// A converter between a `HashMap` or `HashMap`-like type and a sequence of named key-value pairs
547/// for human-readable encoding formats.
548///
549/// See [top-level docs](index.html) for example usage.
550#[cfg(feature = "std")]
551pub struct HashMapToArray<K, V, N = DefaultLabels, U = RandomState, T = HashMap<K, V, U>>(
552 PhantomData<(K, V, N, U, T)>,
553);
554
555#[cfg(feature = "std")]
556impl<K, V, N, U, T> HashMapToArray<K, V, N, U, T> {
557 /// Serializes the given `map` to an array of named key-values if the serializer is
558 /// human-readable. Otherwise serializes the `map` as a map.
559 pub fn serialize<'a, S>(map: &'a T, serializer: S) -> Result<S::Ok, S::Error>
560 where
561 K: 'a + Serialize,
562 V: 'a + Serialize,
563 N: KeyValueLabels,
564 &'a T: IntoIterator<Item = (&'a K, &'a V)> + Serialize,
565 S: Serializer,
566 {
567 serialize::<K, V, N, T, S>(map, serializer)
568 }
569
570 /// Deserializes from a serialized array of named key-values into a map if the serializer is
571 /// human-readable. Otherwise deserializes from a serialized map.
572 pub fn deserialize<'de, D>(deserializer: D) -> Result<T, D::Error>
573 where
574 K: Deserialize<'de> + Eq + Hash,
575 V: Deserialize<'de>,
576 N: KeyValueLabels,
577 U: BuildHasher + Default,
578 HashMap<K, V, U>: Into<T>,
579 T: Deserialize<'de>,
580 D: Deserializer<'de>,
581 {
582 let map = if deserializer.is_human_readable() {
583 deserializer.deserialize_seq(HashMapToArrayVisitor::<K, V, N, U>(PhantomData))
584 } else {
585 HashMap::<K, V, U>::deserialize(deserializer)
586 }?;
587 Ok(map.into())
588 }
589}
590
591#[cfg(feature = "json-schema")]
592impl<K, V, N, U, T> JsonSchema for HashMapToArray<K, V, N, U, T>
593where
594 K: JsonSchema,
595 V: JsonSchema,
596 N: KeyValueJsonSchema,
597{
598 fn schema_name() -> Cow<'static, str> {
599 Vec::<KeyValue<K, V, N>>::schema_name()
600 }
601
602 fn json_schema(generator: &mut SchemaGenerator) -> Schema {
603 Vec::<KeyValue<K, V, N>>::json_schema(generator)
604 }
605}
606
607#[cfg(feature = "std")]
608struct HashMapToArrayVisitor<K, V, N, U>(PhantomData<(K, V, N, U)>);
609
610#[cfg(feature = "std")]
611impl<'de, K, V, N, U> Visitor<'de> for HashMapToArrayVisitor<K, V, N, U>
612where
613 K: Deserialize<'de> + Eq + Hash,
614 V: Deserialize<'de>,
615 N: KeyValueLabels,
616 U: BuildHasher + Default,
617{
618 type Value = HashMap<K, V, U>;
619
620 fn expecting(&self, formatter: &mut fmt::Formatter) -> fmt::Result {
621 formatter.write_str("a HashMapToArray")
622 }
623
624 fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Self::Value, A::Error> {
625 let mut map = HashMap::<K, V, U>::default();
626 while let Some(entry) = seq.next_element::<KeyValue<K, V, N>>()? {
627 map.insert(entry.key, entry.value);
628 }
629 Ok(map)
630 }
631}