DOCSP-41865: datetime serializers

Author: rustagir

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,84 @@ 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 allows
+you to work with dates and times. If you want a high level of control
+over how your date and time values are serialized, you can add the
+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.
+
+The following ``Appointment`` data class has the ``@Serializable``
+annotation and the ``@Contextual`` annotation on the ``date`` field
+to use the ``kotlinx-datetime`` serializer for ``LocalDate`` values.
+Values of the ``time`` field are stored as strings, because the driver
+does not use a serializer without the ``@Contextual`` annotation:
+
+.. 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 by using default serialization as a string:
+
+.. code-block:: json
+
+   {
+     "_id": ...,
+     "name": "Daria Smith",
+     "date": {
+       "$date": "2024-10-15T00:00:00.000Z"
+     },
+     "time": "11:30",
+   }

source/whats-new.txt

@@ -36,8 +36,9 @@ improvements, and fixes:
       :ref:`kotlin-search-indexes` in the Indexes guide
 
 - Adds support for serializers from the ``kotlinx-datetime`` library
-  that let you map to BSON as the expected types. To learn more, see the
-  :ref:`fundamentals-kotlin-serialization` guide.
+  that let you map to BSON as the expected types instead of as strings.
+  To learn more, see the :ref:`kotlin-datetime-serialization` section of
+  the Kotlin Serialization guide.
 
 .. _kotlin-coroutine-version-5.1.3: