Add the name parameter to custom serializers

Author: dkhalanskyjb

core/common/src/serializers/InstantSerializers.kt

@@ -5,8 +5,7 @@
 
 package kotlinx.datetime.serializers
 
-import kotlinx.datetime.Instant
-import kotlinx.datetime.format
+import kotlinx.datetime.*
 import kotlinx.datetime.format.DateTimeComponents
 import kotlinx.datetime.format.DateTimeFormat
 import kotlinx.serialization.*
@@ -86,30 +85,43 @@ public object InstantComponentSerializer : KSerializer<Instant> {
  * [format] should be a format that includes enough components to unambiguously define a date, a time, and a UTC offset.
  * See [Instant.parse] for details of how deserialization is performed.
  *
+ * [name] is the name of the serializer.
+ * The [SerialDescriptor.serialName] of the resulting serializer is `kotlinx.datetime.Instant serializer `[name].
+ * [SerialDescriptor.serialName] must be unique across all serializers in the same serialization context.
+ * When defining a serializer in a library, it is recommended to use the fully qualified class name in [name]
+ * to avoid conflicts with serializers defined by other libraries and client code.
+ *
  * When serializing, the [Instant] value is formatted as a string using the specified [format]
  * in the [ZERO][UtcOffset.ZERO] UTC offset.
  *
  * This serializer is abstract and must be subclassed to provide a concrete serializer.
  * Example:
  * ```
- * object Rfc1123InstantSerializer : FormattedInstantSerializer(DateTimeComponents.Formats.RFC_1123)
+ * // serializes LocalDateTime(2008, 6, 30, 11, 5, 30).toInstant(TimeZone.UTC)
+ * // as the string "Mon, 30 Jun 2008 11:05:30 GMT"
+ * object Rfc1123InstantSerializer : FormattedInstantSerializer(
+ *     "my.package.RFC1123", DateTimeComponents.Formats.RFC_1123
+ * )
  * ```
  *
  * Note that [Instant] is [kotlinx.serialization.Serializable] by default,
  * so it is not necessary to create custom serializers when the format is not important.
  * Additionally, [InstantIso8601Serializer] is provided for the ISO 8601 format.
  */
 public abstract class FormattedInstantSerializer(
+    name: String,
     private val format: DateTimeFormat<DateTimeComponents>,
 ) : KSerializer<Instant> {
-
     override val descriptor: SerialDescriptor =
-        PrimitiveSerialDescriptor("kotlinx.datetime.Instant", PrimitiveKind.STRING)
+        PrimitiveSerialDescriptor("kotlinx.datetime.Instant serializer $name", PrimitiveKind.STRING)
 
     override fun deserialize(decoder: Decoder): Instant =
         Instant.parse(decoder.decodeString(), format)
 
     override fun serialize(encoder: Encoder, value: Instant) {
         encoder.encodeString(value.format(format))
     }
+
+    @OptIn(ExperimentalSerializationApi::class)
+    override fun toString(): String = descriptor.serialName
 }

core/common/src/serializers/LocalDateSerializers.kt

@@ -82,28 +82,38 @@ public object LocalDateComponentSerializer: KSerializer<LocalDate> {
  * An abstract serializer for [LocalDate] values that uses
  * a custom [DateTimeFormat] to serialize and deserialize the value.
  *
+ * [name] is the name of the serializer.
+ * The [SerialDescriptor.serialName] of the resulting serializer is `kotlinx.datetime.LocalDate serializer `[name].
+ * [SerialDescriptor.serialName] must be unique across all serializers in the same serialization context.
+ * When defining a serializer in a library, it is recommended to use the fully qualified class name in [name]
+ * to avoid conflicts with serializers defined by other libraries and client code.
+ *
  * This serializer is abstract and must be subclassed to provide a concrete serializer.
  * Example:
  * ```
- * object IsoBasicLocalDateSerializer : FormattedLocalDateSerializer(LocalDate.Formats.ISO_BASIC)
+ * // serializes LocalDate(2020, 1, 4) as the string "20200104"
+ * object IsoBasicLocalDateSerializer :
+ *     FormattedLocalDateSerializer("my.package.ISO_BASIC", LocalDate.Formats.ISO_BASIC)
  * ```
  *
  * Note that [LocalDate] is [kotlinx.serialization.Serializable] by default,
  * so it is not necessary to create custom serializers when the format is not important.
  * Additionally, [LocalDateIso8601Serializer] is provided for the ISO 8601 format.
  */
 public abstract class FormattedLocalDateSerializer(
-    format: DateTimeFormat<LocalDate>,
-) : KSerializer<LocalDate> by format.asKSerializer("kotlinx.datetime.LocalDate")
+    name: String, format: DateTimeFormat<LocalDate>
+) : KSerializer<LocalDate> by format.asKSerializer("kotlinx.datetime.LocalDate serializer $name")
 
-internal fun <T> DateTimeFormat<T>.asKSerializer(classFqn: String): KSerializer<T> =
+internal fun <T> DateTimeFormat<T>.asKSerializer(serialName: String): KSerializer<T> =
     object : KSerializer<T> {
         override val descriptor: SerialDescriptor =
-            PrimitiveSerialDescriptor(classFqn, PrimitiveKind.STRING)
+            PrimitiveSerialDescriptor(serialName, PrimitiveKind.STRING)
 
         override fun deserialize(decoder: Decoder): T = parse(decoder.decodeString())
 
         override fun serialize(encoder: Encoder, value: T) {
             encoder.encodeString(format(value))
         }
+
+        override fun toString(): String = serialName
     }

core/common/src/serializers/LocalDateTimeSerializers.kt

@@ -104,20 +104,29 @@ public object LocalDateTimeComponentSerializer: KSerializer<LocalDateTime> {
  * An abstract serializer for [LocalDateTime] values that uses
  * a custom [DateTimeFormat] to serialize and deserialize the value.
  *
+ * [name] is the name of the serializer.
+ * The [SerialDescriptor.serialName] of the resulting serializer is `kotlinx.datetime.LocalDateTime serializer `[name].
+ * [SerialDescriptor.serialName] must be unique across all serializers in the same serialization context.
+ * When defining a serializer in a library, it is recommended to use the fully qualified class name in [name]
+ * to avoid conflicts with serializers defined by other libraries and client code.
+ *
  * This serializer is abstract and must be subclassed to provide a concrete serializer.
  * Example:
  * ```
- * object PythonDateTimeSerializer : FormattedLocalDateTimeSerializer(LocalDateTime.Format {
- *     date(LocalDate.Formats.ISO)
- *     char(' ')
- *     time(LocalTime.Formats.ISO)
- * })
+ * // serializes LocalDateTime(2020, 1, 4, 12, 30) as the string "2020-01-04 12:30"
+ * object PythonDateTimeSerializer : FormattedLocalDateTimeSerializer("my.package.PythonDateTime",
+ *     LocalDateTime.Format {
+ *         date(LocalDate.Formats.ISO)
+ *         char(' ')
+ *         time(LocalTime.Formats.ISO)
+ *     }
+ * )
  * ```
  *
  * Note that [LocalDateTime] is [kotlinx.serialization.Serializable] by default,
  * so it is not necessary to create custom serializers when the format is not important.
  * Additionally, [LocalDateTimeIso8601Serializer] is provided for the ISO 8601 format.
  */
 public abstract class FormattedLocalDateTimeSerializer(
-    format: DateTimeFormat<LocalDateTime>,
-) : KSerializer<LocalDateTime> by format.asKSerializer("kotlinx.datetime.LocalDateTime")
+    name: String, format: DateTimeFormat<LocalDateTime>
+) : KSerializer<LocalDateTime> by format.asKSerializer("kotlinx.datetime.LocalDateTime serializer $name")

core/common/src/serializers/LocalTimeSerializers.kt

@@ -87,10 +87,17 @@ public object LocalTimeComponentSerializer : KSerializer<LocalTime> {
  * An abstract serializer for [LocalTime] values that uses
  * a custom [DateTimeFormat] to serialize and deserialize the value.
  *
+ * [name] is the name of the serializer.
+ * The [SerialDescriptor.serialName] of the resulting serializer is `kotlinx.datetime.LocalTime serializer `[name].
+ * [SerialDescriptor.serialName] must be unique across all serializers in the same serialization context.
+ * When defining a serializer in a library, it is recommended to use the fully qualified class name in [name]
+ * to avoid conflicts with serializers defined by other libraries and client code.
+ *
  * This serializer is abstract and must be subclassed to provide a concrete serializer.
  * Example:
  * ```
- * object FixedWidthTimeSerializer : FormattedLocalTimeSerializer(LocalTime.Format {
+ * // serializes LocalTime(12, 30) as "12:30:00.000"
+ * object FixedWidthTimeSerializer : FormattedLocalTimeSerializer("my.package.FixedWidthTime", LocalTime.Format {
  *     hour(); char(':'); minute(); char(':'); second(); char('.'); secondFraction(3)
  * })
  * ```
@@ -100,5 +107,5 @@ public object LocalTimeComponentSerializer : KSerializer<LocalTime> {
  * Additionally, [LocalTimeIso8601Serializer] is provided for the ISO 8601 format.
  */
 public abstract class FormattedLocalTimeSerializer(
-    format: DateTimeFormat<LocalTime>,
-) : KSerializer<LocalTime> by format.asKSerializer("kotlinx.datetime.LocalTime")
+    name: String, format: DateTimeFormat<LocalTime>
+) : KSerializer<LocalTime> by format.asKSerializer("kotlinx.datetime.LocalTime serializer $name")

core/common/src/serializers/TimeZoneSerializers.kt

@@ -78,16 +78,25 @@ public object UtcOffsetSerializer: KSerializer<UtcOffset> {
  * An abstract serializer for [UtcOffset] values that uses
  * a custom [DateTimeFormat] to serialize and deserialize the value.
  *
+ * [name] is the name of the serializer.
+ * The [SerialDescriptor.serialName] of the resulting serializer is `kotlinx.datetime.UtcOffset serializer `[name].
+ * [SerialDescriptor.serialName] must be unique across all serializers in the same serialization context.
+ * When defining a serializer in a library, it is recommended to use the fully qualified class name in [name]
+ * to avoid conflicts with serializers defined by other libraries and client code.
+ *
  * This serializer is abstract and must be subclassed to provide a concrete serializer.
  * Example:
  * ```
- * object FourDigitOffsetSerializer : FormattedUtcOffsetSerializer(UtcOffset.Formats.FOUR_DIGITS)
+ * // serializes the UTC offset UtcOffset(hours = 2) as the string "+0200"
+ * object FourDigitOffsetSerializer : FormattedUtcOffsetSerializer(
+ *     "my.package.FOUR_DIGITS", UtcOffset.Formats.FOUR_DIGITS
+ * )
  * ```
  *
  * Note that [UtcOffset] is [kotlinx.serialization.Serializable] by default,
  * so it is not necessary to create custom serializers when the format is not important.
  * Additionally, [UtcOffsetSerializer] is provided for the ISO 8601 format.
  */
 public abstract class FormattedUtcOffsetSerializer(
-    format: DateTimeFormat<UtcOffset>,
-) : KSerializer<UtcOffset> by format.asKSerializer("kotlinx.datetime.UtcOffset")
+    name: String, format: DateTimeFormat<UtcOffset>
+) : KSerializer<UtcOffset> by format.asKSerializer("kotlinx.datetime.UtcOffset serializer $name")

serialization/common/test/InstantSerializationTest.kt

@@ -68,10 +68,11 @@ class InstantSerializationTest {
         iso8601Serialization(Json.serializersModule.serializer())
     }
 
-    object Rfc1123InstantSerializer : FormattedInstantSerializer(DateTimeComponents.Formats.RFC_1123)
+    object Rfc1123InstantSerializer : FormattedInstantSerializer("RFC_1123", DateTimeComponents.Formats.RFC_1123)
 
     @Test
     fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.Instant serializer RFC_1123", Rfc1123InstantSerializer)
         for ((instant, json) in listOf(
             Pair(Instant.fromEpochSeconds(1607505416),
                 "\"Wed, 9 Dec 2020 09:16:56 GMT\""),

serialization/common/test/LocalDateSerializationTest.kt

@@ -70,10 +70,11 @@ class LocalDateSerializationTest {
         iso8601Serialization(Json.serializersModule.serializer())
     }
 
-    object IsoBasicLocalDateSerializer : FormattedLocalDateSerializer(LocalDate.Formats.ISO_BASIC)
+    object IsoBasicLocalDateSerializer : FormattedLocalDateSerializer("ISO_BASIC", LocalDate.Formats.ISO_BASIC)
 
     @Test
     fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.LocalDate serializer ISO_BASIC", IsoBasicLocalDateSerializer)
         for ((localDate, json) in listOf(
             Pair(LocalDate(2020, 12, 9), "\"20201209\""),
             Pair(LocalDate(-2020, 1, 1), "\"-20200101\""),
@@ -84,3 +85,8 @@ class LocalDateSerializationTest {
         }
     }
 }
+
+@OptIn(ExperimentalSerializationApi::class)
+fun <T> assertKSerializerName(expectedName: String, serializer: KSerializer<T>) {
+    assertEquals(expectedName, serializer.descriptor.serialName)
+}

serialization/common/test/LocalDateTimeSerializationTest.kt

@@ -84,14 +84,15 @@ class LocalDateTimeSerializationTest {
         iso8601Serialization(Json.serializersModule.serializer())
     }
 
-    object PythonDateTimeSerializer : FormattedLocalDateTimeSerializer(LocalDateTime.Format {
+    object PythonDateTimeSerializer : FormattedLocalDateTimeSerializer("PythonDateTime", LocalDateTime.Format {
         date(LocalDate.Formats.ISO)
         char(' ')
         time(LocalTime.Formats.ISO)
     })
 
     @Test
     fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.LocalDateTime serializer PythonDateTime", PythonDateTimeSerializer)
         for ((localDateTime, json) in listOf(
             Pair(LocalDateTime(2008, 7, 5, 2, 1), "\"2008-07-05 02:01:00\""),
             Pair(LocalDateTime(2007, 12, 31, 23, 59, 1), "\"2007-12-31 23:59:01\""),

serialization/common/test/LocalTimeSerializationTest.kt

@@ -74,12 +74,13 @@ class LocalTimeSerializationTest {
         iso8601Serialization(Json.serializersModule.serializer())
     }
 
-    object FixedWidthTimeSerializer : FormattedLocalTimeSerializer(LocalTime.Format {
+    object FixedWidthTimeSerializer : FormattedLocalTimeSerializer("FixedWidth", LocalTime.Format {
         hour(); char(':'); minute(); char(':'); second(); char('.'); secondFraction(3)
     })
 
     @Test
     fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.LocalTime serializer FixedWidth", FixedWidthTimeSerializer)
         for ((localTime, json) in listOf(
             Pair(LocalTime(2, 1), "\"02:01:00.000\""),
             Pair(LocalTime(23, 59, 1), "\"23:59:01.000\""),

serialization/common/test/UtcOffsetSerializationTest.kt

@@ -36,10 +36,11 @@ class UtcOffsetSerializationTest {
         testSerializationAsPrimitive(UtcOffset.serializer())
     }
 
-    object FourDigitOffsetSerializer : FormattedUtcOffsetSerializer(UtcOffset.Formats.FOUR_DIGITS)
+    object FourDigitOffsetSerializer : FormattedUtcOffsetSerializer("FOUR_DIGITS", UtcOffset.Formats.FOUR_DIGITS)
 
     @Test
     fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.UtcOffset serializer FOUR_DIGITS", FourDigitOffsetSerializer)
         for ((utcOffset, json) in listOf(
             Pair(UtcOffset.ZERO, "\"+0000\""),
             Pair(UtcOffset(2), "\"+0200\""),