DOCSP-41865: datetime serializers

examples/src/test/kotlin/KotlinXSerializationTest.kt

@@ -204,7 +204,6 @@ internal class KotlinXSerializationTest {
         val department: String,
     ) : Person
     // :snippet-end:
-
     @Test
     fun polymorphicSerializationTest() = runBlocking {
 
@@ -242,5 +241,34 @@ internal class KotlinXSerializationTest {
         collection.drop()
     }
 
+    // :snippet-start: datetime-data-class
+    @Serializable
+    data class Appointment(
+        val name: String,
+        @Contextual val date: LocalDate,
+        val time: LocalTime,
+    )
+    // :snippet-end:
+
+    @Test
+    fun dateTimeSerializationTest() = runBlocking {
+
+        // :snippet-start: datetime-insertone
+        val collection = database.getCollection<Appointment>("appointments")
+
+        val apptDoc = Appointment(
+            "Daria Smith",
+            LocalDate(2024, 10, 15),
+            LocalTime(hour = 11, minute = 30)
+        )
+
+        collection.insertOne(apptDoc)
+        // :snippet-end:
+
+        assertEquals(apptDoc.name, "Daria Smith")
+
+        collection.drop()
+    }
+
 }
 

snooty.toml

@@ -35,3 +35,4 @@ zstdVersion = "com.github.luben:zstd-jni:1.5.5-2"
 logbackVersion = "1.2.11"
 log4j2Version = "2.17.1"
 serializationVersion = "1.5.1"
+kotlinx-dt-version = "0.6.1"

source/examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt

@@ -0,0 +1,6 @@
+@Serializable
+data class Appointment(
+    val name: String,
+    @Contextual val date: LocalDate,
+    val time: LocalTime,
+)

source/examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt

@@ -0,0 +1,9 @@
+val collection = database.getCollection<Appointment>("appointments")
+
+val apptDoc = Appointment(
+    "Daria Smith",
+    LocalDate(2024, 10, 15),
+    LocalTime(hour = 11, minute = 30)
+)
+
+collection.insertOne(apptDoc)

source/fundamentals/data-formats/serialization.txt

@@ -301,3 +301,91 @@ deserializes them accordingly.
       Retrieving as Document type
       Document{{_id=..., _t=Teacher, name=Vivian Lee, department=History}}
       Document{{_id=..., _t=Student, name=Kate Parker, grade=10}}
+
+.. _kotlin-datetime-serialization:
+
+Serialize Dates and Times
+-------------------------
+
+In this section, you can learn about using {+language+} serialization to
+work with date and time types.
+
+kotlinx-datetime Library
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``kotlinx-datetime`` is a {+language+} library that offers
+a high level of control over how your date and time values
+are serialized. To use the library, add the ``kotlinx-datetime``
+dependency to your project's dependency list.
+
+Select from the following tabs to see how to add the ``kotlinx-datetime``
+dependency to your project by using the :guilabel:`Gradle` and
+:guilabel:`Maven` package managers:
+
+.. tabs::
+
+   .. tab::
+      :tabid: Gradle
+
+      .. code-block:: kotlin
+        :caption: build.gradle.kts
+
+        implementation("org.jetbrains.kotlinx:kotlinx-datetime:{+kotlinx-dt-version+}")
+
+   .. tab::
+      :tabid: Maven
+
+      .. code-block:: kotlin
+        :caption: pom.xml
+
+        <dependency>
+            <groupId>org.jetbrains.kotlinx</groupId>
+            <artifactId>kotlinx-datetime-jvm</artifactId>
+            <version>{+kotlinx-dt-version+}</version>
+        </dependency>
+
+To learn more about this library, see the :github:`kotlinx-datetime repository
+</Kotlin/kotlinx-datetime>` on GitHub.
+
+Example Data Class with Dates and Times
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+After you add the library dependency, you can implement serializers from
+the ``kotlinx-datetime`` library that map your data class field values
+to the expected types in BSON.
+
+In the following example, the driver serializes the fields of
+the ``Appointment`` data class with the following behavior:
+
+- ``name``: The driver serializes the value as a string.
+
+- ``date``:  The driver uses the ``kotlinx-datetime`` serializer
+  because the field has the ``@Contextual`` annotation. ``LocalDate``
+  values are serialized as BSON dates.
+
+- ``time``: The driver serializes the value as a string because it does
+  not have the ``@Contextual`` annotation. This is the default
+  serialization behavior for ``LocalTime`` values.
+
+.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-data-class.kt
+    :language: kotlin
+
+The following example inserts an instance of the ``Appointment`` data
+class into MongoDB:
+
+.. literalinclude:: /examples/generated/KotlinXSerializationTest.snippet.datetime-insertone.kt
+    :language: kotlin
+
+In MongoDB, the ``LocalDate`` value is stored as a BSON date, and the
+``time`` field is stored  as a string by default serialization:
+
+.. code-block:: json
+
+   {
+     "_id": ...,
+     "name": "Daria Smith",
+     "date": {
+       "$date": "2024-10-15T00:00:00.000Z"
+     },
+     "time": "11:30",
+   }

source/whats-new.txt

@@ -26,14 +26,21 @@ Learn what's new in:
 What's New in 5.2
 -----------------
 
-New features of the 4.11 driver release include:
+The 5.2 driver release includes the following new features,
+improvements, and fixes:
 
 .. sharedinclude:: dbx/jvm/v5.2-wn-items.rst
 
    .. replacement:: avs-index-link
 
       :ref:`kotlin-search-indexes` in the Indexes guide
 
+- Adds support for serializers from the ``kotlinx-datetime`` library
+  that let you map {+language+} date and time types to BSON as the
+  expected types instead of as strings. To learn more, see the
+  :ref:`kotlin-datetime-serialization` section of the {+language+}
+  Serialization guide.
+
 - Supports serialization of `JsonElement
   <{+kotlin-docs+}/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/>`__
   values. To work with the ``JsonElement`` type, you must add the