Skip to content

RUST-1748 Refactor BSON DateTime serde converters using serde_conv_doc macro #570

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 19 commits into from
Jul 16, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
a54433e
Refactor BSON DateTime serde converters using serde_conv_doc macro
JamieTsai1024 Jul 8, 2025
2298c43
Remove bson from datetime helpers module name
JamieTsai1024 Jul 14, 2025
7cdc3d9
Add RFC 3339 format to error messages
JamieTsai1024 Jul 14, 2025
76349a0
Fix typo
JamieTsai1024 Jul 14, 2025
e9b14b8
Refactor DateTime FromI64 and FromTime03OffsetDateTime using serde_co…
JamieTsai1024 Jul 14, 2025
212ea0b
Add rustdoc comments to module and structs
JamieTsai1024 Jul 14, 2025
03027d1
Switch from clone through to_owned() to dereference
JamieTsai1024 Jul 14, 2025
ebe3a99
Remove extra rustdocs ///
JamieTsai1024 Jul 14, 2025
9f41ee6
Add DateTime import to fix lint on rustdocs
JamieTsai1024 Jul 14, 2025
2d26b59
Remove DateTime import for rustdocs to avoid clippy warning
JamieTsai1024 Jul 14, 2025
d3d9a95
Add missing conditional compilation to OffsetDateTime struct
JamieTsai1024 Jul 14, 2025
3a0e345
Update rustdocs phrasing and improve struct naming for Chrono04DateTime
JamieTsai1024 Jul 14, 2025
f527aff
Split tests for DateTime
JamieTsai1024 Jul 14, 2025
fe5b5e4
clippy test: revert FromTime03OffsetDateTime to FromTimeOffsetDateTime
JamieTsai1024 Jul 14, 2025
ca6f68f
Rename FromTime03OffsetDateTime
JamieTsai1024 Jul 14, 2025
a3dd1b8
Fix clippy attempt - move conditional compilation attribute
JamieTsai1024 Jul 15, 2025
11b0ddd
Update rustdocs
JamieTsai1024 Jul 15, 2025
71cab69
Update rustdocs imports
JamieTsai1024 Jul 15, 2025
48234dc
Move cfg_attr into macro
JamieTsai1024 Jul 15, 2025
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,7 @@ provides a `DateTime` type, but its `Serialize` and `Deserialize` implementation
instead, so when using it with BSON, the BSON datetime type is not used. To work around this, the
`chrono-0_4` feature flag can be enabled. This flag exposes a number of convenient conversions
between `bson::DateTime` and `chrono::DateTime`, including the
[`bson_datetime::FromChronoDateTime`](https://docs.rs/bson/latest/bson/serde_helpers/bson_datetime/struct.FromChronoDateTime/index.html)
[`datetime::FromChrono04DateTime`](https://docs.rs/bson/latest/bson/serde_helpers/datetime/struct.FromChrono04DateTime/index.html)
serde helper, which can be used to (de)serialize `chrono::DateTime`s to/from BSON datetimes, and the
`From<chrono::DateTime>` implementation for `Bson`, which allows `chrono::DateTime` values to be
used in the `doc!` and `bson!` macros.
Expand All @@ -250,7 +250,7 @@ struct Foo {

// serializes as a BSON datetime.
// this requires the "chrono-0_4" feature flag
#[serde_as(as = "bson::serde_helpers::bson_datetime::FromChronoDateTime")]
#[serde_as(as = "bson::serde_helpers::datetime::FromChrono04DateTime")]
chrono_as_bson: chrono::DateTime<chrono::Utc>,
}

Expand Down
44 changes: 23 additions & 21 deletions src/datetime.rs
Original file line number Diff line number Diff line change
Expand Up @@ -108,20 +108,25 @@ use crate::error::{Error, Result};
///
/// ### `serde_helpers`
/// The `bson` crate provides a number of useful helpers for serializing and deserializing
/// various datetime types to and from different formats. For example, to serialize a
/// [`chrono::DateTime`] as a BSON datetime, you can use
/// [`crate::serde_helpers::bson_datetime::FromChronoDateTime`].
/// Similarly, to serialize a BSON [`DateTime`] to a string, you can use
/// [`crate::serde_helpers::bson_datetime::AsRfc3339String`]. Check out the
/// [`crate::serde_helpers`] module documentation for a list of all of the helpers offered by the
/// various datetime types to and from different formats using the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/)
/// crate.
///
/// > **Note:** All helpers in this module require use of the [`#[serde_as]`](https://docs.rs/serde_with/latest/serde_with/attr.serde_as.html)
/// > attribute on the struct. This enables the enhanced serialization behavior provided by
/// > `serde_with-3`.
///
/// For example, to serialize a [`chrono::DateTime`] as a BSON datetime, you can use
/// [`crate::serde_helpers::datetime::FromChrono04DateTime`].
/// Similarly, to serialize a BSON [`DateTime`] to a string, you can use
/// [`crate::serde_helpers::datetime::AsRfc3339String`]. Check out the
/// [`crate::serde_helpers`] module documentation for a list of all of the helpers
/// offered by the crate.
/// ```rust
/// # #[cfg(feature = "chrono-0_4")]
/// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
/// # {
/// use serde::{Serialize, Deserialize};
/// use serde_with::serde_as;
/// use bson::serde_helpers::bson_datetime;
/// use bson::serde_helpers::datetime;
///
/// #[serde_as]
/// #[derive(Serialize, Deserialize)]
Expand All @@ -134,33 +139,30 @@ use crate::error::{Error, Result};
///
/// // serializes as a BSON datetime.
/// // this requires the "chrono-0_4" feature flag
/// #[serde_as(as = "bson_datetime::FromChronoDateTime")]
/// #[serde_as(as = "datetime::FromChrono04DateTime")]
/// chrono_as_bson: chrono::DateTime<chrono::Utc>,
///
/// // serializes as an RFC 3339 / ISO-8601 string.
/// #[serde_as(as = "bson_datetime::AsRfc3339String")]
/// // this requires the "serde_with-3" feature flag
/// #[serde_as(as = "datetime::AsRfc3339String")]
/// bson_as_string: bson::DateTime,
/// }
/// # }
/// ```
/// ### The `serde_with-3` feature flag
///
/// The `serde_with-3` 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-3`
/// can handle nested [`chrono::DateTime`] values (e.g. in [`Option`]), whereas the former only
/// works on fields that are exactly [`chrono::DateTime`].
/// The main benefit of using the [`serde_with`](https://docs.rs/serde_with/1.11.0/serde_with/) crate
/// is that it can handle nested [`chrono::DateTime`] values (e.g. in [`Option`] or [`Vec`]).
/// ```
/// # #[cfg(all(feature = "chrono-0_4", feature = "serde_with-3"))]
/// # {
/// use serde::{Deserialize, Serialize};
/// use bson::doc;
/// use serde_with::serde_as;
/// use bson::{doc, serde_helpers::datetime};
///
/// #[serde_with::serde_as]
/// #[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>")]
/// /// serializes as a BSON datetime rather than using [`chrono::DateTime`]'s serialization
/// #[serde_as(as = "Option<datetime::FromChrono04DateTime>")]
/// as_bson: Option<chrono::DateTime<chrono::Utc>>,
/// }
///
Expand Down
6 changes: 3 additions & 3 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,7 @@
//! on strings instead, so when using it with BSON, the BSON datetime type is not used. To work
//! around this, the `chrono-0_4` feature flag can be enabled. This flag exposes a number of
//! convenient conversions between [`bson::DateTime`](crate::DateTime) and [`chrono::DateTime`],
//! including the [`serde_helpers::bson_datetime::FromChronoDateTime`]
//! including the [`serde_helpers::datetime::FromChrono04DateTime`]
//! serde helper, which can be used to (de)serialize [`chrono::DateTime`]s to/from BSON datetimes,
//! and the `From<chrono::DateTime>` implementation for [`Bson`], which allows [`chrono::DateTime`]
//! values to be used in the `doc!` and `bson!` macros.
Expand All @@ -245,7 +245,7 @@
//! use serde::{Serialize, Deserialize};
//! use serde_with::serde_as;
//! use bson::doc;
//! use bson::serde_helpers::bson_datetime;
//! use bson::serde_helpers::datetime;
//!
//! #[serde_as]
//! #[derive(Serialize, Deserialize)]
Expand All @@ -258,7 +258,7 @@
//!
//! // serializes as a BSON datetime.
//! // this requires the "chrono-0_4" feature flag
//! #[serde_as(as = "bson_datetime::FromChronoDateTime")]
//! #[serde_as(as = "datetime::FromChrono04DateTime")]
//! chrono_as_bson: chrono::DateTime<chrono::Utc>,
//! }
//!
Expand Down
Loading