RUST-1024 Add serde_with integration for Uuid and DateTime (#323)

Author: patrickfreed

Cargo.toml

@@ -36,6 +36,11 @@ default = []
 chrono-0_4 = []
 # if enabled, include API for interfacing with uuid 0.8
 uuid-0_8 = []
+# if enabled, include serde_with interop.
+# should be used in conjunction with chrono-0_4 or uuid-0_8.
+# it's commented out here because Cargo implicitly adds a feature flag for
+# all optional dependencies.
+# serde_with
 
 [lib]
 name = "bson"
@@ -52,6 +57,7 @@ base64 = "0.13.0"
 lazy_static = "1.4.0"
 uuid = { version = "0.8.1", features = ["serde", "v4"] }
 serde_bytes = "0.11.5"
+serde_with = { version = "1", optional = true }
 
 [dev-dependencies]
 assert_matches = "1.2"

README.md

@@ -44,10 +44,11 @@ Note that if you are using `bson` through the `mongodb` crate, you do not need t
 
 #### Feature Flags
 
-| Feature      | Description                                                                            | Extra dependencies | Default |
-|:-------------|:---------------------------------------------------------------------------------------|:-------------------|:--------|
-| `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API. | n/a                | no      |
-| `uuid-0_8`   | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API.     | n/a                | no      |
+| Feature      | Description                                                                                         | Extra dependencies | Default |
+|:-------------|:----------------------------------------------------------------------------------------------------|:-------------------|:--------|
+| `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API.              | n/a                | no      |
+| `uuid-0_8`   | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API.                  | n/a                | no      |
+| `serde_with` | Enable [`serde_with`](docs.rs/serde_with/latest) integrations for `bson::DateTime` and `bson::Uuid` | serde_with         | no      |
 
 ## Overview of the BSON Format
 

serde-tests/Cargo.toml

@@ -8,10 +8,13 @@ edition = "2018"
 default = []
 
 [dependencies]
-bson = { path = "..", default-features = false }
+bson = { path = "..", features = ["uuid-0_8", "chrono-0_4", "serde_with"] }
 serde = { version = "1.0", features = ["derive"] }
 pretty_assertions = "0.6.1"
 hex = "0.4.2"
+serde_with = "1"
+chrono = "0.4"
+uuid = "0.8"
 
 [dev-dependencies]
 serde_json = "1"

serde-tests/test.rs

@@ -62,6 +62,7 @@ where
         .expect(description);
 
     let expected_bytes_serde = bson::to_vec(&expected_value).expect(description);
+
     assert_eq!(expected_bytes_serde, expected_bytes, "{}", description);
 
     let expected_bytes_from_doc_serde = bson::to_vec(&expected_doc).expect(description);
@@ -1231,6 +1232,54 @@ fn u2i() {
     bson::to_vec(&v).unwrap_err();
 }
 
+#[test]
+fn serde_with_chrono() {
+    #[serde_with::serde_as]
+    #[derive(Deserialize, Serialize, PartialEq, Debug)]
+    struct Foo {
+        #[serde_as(as = "Option<bson::DateTime>")]
+        as_bson: Option<chrono::DateTime<chrono::Utc>>,
+
+        #[serde_as(as = "Option<bson::DateTime>")]
+        none_bson: Option<chrono::DateTime<chrono::Utc>>,
+    }
+
+    let f = Foo {
+        as_bson: Some(bson::DateTime::now().into()),
+        none_bson: None,
+    };
+    let expected = doc! {
+        "as_bson": Bson::DateTime(f.as_bson.unwrap().into()),
+        "none_bson": Bson::Null
+    };
+
+    run_test(&f, &expected, "serde_with - chrono");
+}
+
+#[test]
+fn serde_with_uuid() {
+    #[serde_with::serde_as]
+    #[derive(Deserialize, Serialize, PartialEq, Debug)]
+    struct Foo {
+        #[serde_as(as = "Option<bson::Uuid>")]
+        as_bson: Option<uuid::Uuid>,
+
+        #[serde_as(as = "Option<bson::Uuid>")]
+        none_bson: Option<uuid::Uuid>,
+    }
+
+    let f = Foo {
+        as_bson: Some(uuid::Uuid::new_v4()),
+        none_bson: None,
+    };
+    let expected = doc! {
+        "as_bson": bson::Uuid::from(f.as_bson.unwrap()),
+        "none_bson": Bson::Null
+    };
+
+    run_test(&f, &expected, "serde_with - uuid");
+}
+
 #[test]
 fn hint_cleared() {
     #[derive(Debug, Serialize, Deserialize)]

src/datetime.rs

@@ -5,6 +5,11 @@ use std::{
     time::{Duration, SystemTime},
 };
 
+#[cfg(all(feature = "serde_with", feature = "chrono-0_4"))]
+use serde::{Deserialize, Deserializer, Serialize};
+#[cfg(all(feature = "serde_with", feature = "chrono-0_4"))]
+use serde_with::{DeserializeAs, SerializeAs};
+
 use chrono::{LocalResult, TimeZone, Utc};
 
 /// Struct representing a BSON datetime.
@@ -54,6 +59,40 @@ use chrono::{LocalResult, TimeZone, Utc};
 /// }
 /// # }
 /// ```
+/// ## The `serde_with` feature flag
+///
+/// The `serde_with` feature can be enabled to support more ergonomic serde attributes for
+/// (de)serializing `chrono::DateTime` from/to BSON via the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/)
+/// crate. The main benefit of this compared to the regular `serde_helpers` is that `serde_with` can
+/// handle nested `chrono::DateTime` values (e.g. in `Option`), whereas the former only works on
+/// fields that are exactly `chrono::DateTime`.
+/// ```
+/// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with"))]
+/// # {
+/// use serde::{Deserialize, Serialize};
+/// use bson::doc;
+///
+/// #[serde_with::serde_as]
+/// #[derive(Deserialize, Serialize, PartialEq, Debug)]
+/// struct Foo {
+///   /// Serializes as a BSON datetime rather than using `chrono::DateTime`'s serialization
+///   #[serde_as(as = "Option<bson::DateTime>")]
+///   as_bson: Option<chrono::DateTime<chrono::Utc>>,
+/// }
+///
+/// let dt = chrono::Utc::now();
+/// let foo = Foo {
+///   as_bson: Some(dt),
+/// };
+///
+/// let expected = doc! {
+///   "as_bson": bson::DateTime::from_chrono(dt),
+/// };
+///
+/// assert_eq!(bson::to_document(&foo)?, expected);
+/// # }
+/// # Ok::<(), Box<dyn std::error::Error>>(())
+/// ```
 #[derive(Eq, PartialEq, Ord, PartialOrd, Hash, Copy, Clone)]
 pub struct DateTime(i64);
 
@@ -234,6 +273,33 @@ impl<T: chrono::TimeZone> From<chrono::DateTime<T>> for crate::DateTime {
     }
 }
 
+#[cfg(all(feature = "chrono-0_4", feature = "serde_with"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "chrono-0_4", feature = "serde_with"))))]
+impl<'de> DeserializeAs<'de, chrono::DateTime<Utc>> for crate::DateTime {
+    fn deserialize_as<D>(deserializer: D) -> std::result::Result<chrono::DateTime<Utc>, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let dt = DateTime::deserialize(deserializer)?;
+        Ok(dt.to_chrono())
+    }
+}
+
+#[cfg(all(feature = "chrono-0_4", feature = "serde_with"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "chrono-0_4", feature = "chrono-0_4"))))]
+impl SerializeAs<chrono::DateTime<Utc>> for crate::DateTime {
+    fn serialize_as<S>(
+        source: &chrono::DateTime<Utc>,
+        serializer: S,
+    ) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let dt = DateTime::from_chrono(*source);
+        dt.serialize(serializer)
+    }
+}
+
 /// Errors that can occur during [`DateTime`] construction and generation.
 #[derive(Clone, Debug)]
 #[non_exhaustive]

src/lib.rs

@@ -59,10 +59,11 @@
 //!
 //! #### Feature Flags
 //!
-//! | Feature      | Description                                                                            | Extra dependencies | Default |
-//! |:-------------|:---------------------------------------------------------------------------------------|:-------------------|:--------|
-//! | `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API. | n/a                | no      |
-//! | `uuid-0_8`   | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API.     | n/a                | no      |
+//! | Feature      | Description                                                                                         | Extra dependencies | Default |
+//! |:-------------|:----------------------------------------------------------------------------------------------------|:-------------------|:--------|
+//! | `chrono-0_4` | Enable support for v0.4 of the [`chrono`](docs.rs/chrono/0.4) crate in the public API.              | n/a                | no      |
+//! | `uuid-0_8`   | Enable support for v0.8 of the [`uuid`](docs.rs/uuid/0.8) crate in the public API.                  | n/a                | no      |
+//! | `serde_with` | Enable [`serde_with`](docs.rs/serde_with/latest) integrations for `bson::DateTime` and `bson::Uuid` | serde_with         | no      |
 //!
 //! ## BSON values
 //!

src/uuid/mod.rs

@@ -69,6 +69,40 @@
 //! # };
 //! ```
 //!
+//! ## The `serde_with` feature flag
+//!
+//! The `serde_with` feature can be enabled to support more ergonomic serde attributes for
+//! (de)serializing `uuid::Uuid` from/to BSON via the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/)
+//! crate. The main benefit of this compared to the regular `serde_helpers` is that `serde_with` can
+//! handle nested `uuid::Uuid` values (e.g. in `Option`), whereas the former only works on fields
+//! that are exactly `uuid::Uuid`.
+//! ```
+//! # #[cfg(all(feature = "uuid-0_8", feature = "serde_with"))]
+//! # {
+//! use serde::{Deserialize, Serialize};
+//! use bson::doc;
+//!
+//! #[serde_with::serde_as]
+//! #[derive(Deserialize, Serialize, PartialEq, Debug)]
+//! struct Foo {
+//!   /// Serializes as a BSON binary rather than using `uuid::Uuid`'s serialization
+//!   #[serde_as(as = "Option<bson::Uuid>")]
+//!   as_bson: Option<uuid::Uuid>,
+//! }
+//!
+//! let foo = Foo {
+//!   as_bson: Some(uuid::Uuid::new_v4()),
+//! };
+//!
+//! let expected = doc! {
+//!   "as_bson": bson::Uuid::from(foo.as_bson.unwrap()),
+//! };
+//!
+//! assert_eq!(bson::to_document(&foo)?, expected);
+//! # }
+//! # Ok::<(), Box<dyn std::error::Error>>(())
+//! ```
+//!
 //! ## Using `crate::Uuid` with non-BSON formats
 //!
 //! [`crate::Uuid`]'s `serde` implementation is the same as `uuid::Uuid`'s
@@ -413,6 +447,30 @@ impl From<uuid::Uuid> for Binary {
     }
 }
 
+#[cfg(all(feature = "uuid-0_8", feature = "serde_with"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "uuid-0_8", feature = "serde_with"))))]
+impl<'de> serde_with::DeserializeAs<'de, uuid::Uuid> for crate::Uuid {
+    fn deserialize_as<D>(deserializer: D) -> std::result::Result<uuid::Uuid, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        let uuid = Uuid::deserialize(deserializer)?;
+        Ok(uuid.into())
+    }
+}
+
+#[cfg(all(feature = "uuid-0_8", feature = "serde_with"))]
+#[cfg_attr(docsrs, doc(cfg(all(feature = "uuid-0_8", feature = "sere_with"))))]
+impl serde_with::SerializeAs<uuid::Uuid> for crate::Uuid {
+    fn serialize_as<S>(source: &uuid::Uuid, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let uuid = Uuid::from_external_uuid(*source);
+        uuid.serialize(serializer)
+    }
+}
+
 /// Errors that can occur during [`Uuid`] construction and generation.
 #[derive(Clone, Debug)]
 #[non_exhaustive]