Rework the YearMonth serializers

dkhalanskyjb · dkhalanskyjb · commit ba67eb98b72d · 2025-05-30T12:18:17.000+02:00
diff --git a/core/api/kotlinx-datetime.api b/core/api/kotlinx-datetime.api
@@ -1100,6 +1100,15 @@ public abstract class kotlinx/datetime/serializers/FormattedUtcOffsetSerializer
 	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/UtcOffset;)V
 }
 
+public abstract class kotlinx/datetime/serializers/FormattedYearMonthSerializer : kotlinx/serialization/KSerializer {
+	public fun <init> (Ljava/lang/String;Lkotlinx/datetime/format/DateTimeFormat;)V
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
+}
+
 public final class kotlinx/datetime/serializers/InstantComponentSerializer : kotlinx/serialization/KSerializer {
 	public static final field INSTANCE Lkotlinx/datetime/serializers/InstantComponentSerializer;
 	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
@@ -1280,3 +1289,12 @@ public final class kotlinx/datetime/serializers/YearMonthIso8601Serializer : kot
 	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
 }
 
+public final class kotlinx/datetime/serializers/YearMonthSerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lkotlinx/datetime/serializers/YearMonthSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlinx/datetime/YearMonth;
+	public fun getDescriptor ()Lkotlinx/serialization/descriptors/SerialDescriptor;
+	public synthetic fun serialize (Lkotlinx/serialization/encoding/Encoder;Ljava/lang/Object;)V
+	public fun serialize (Lkotlinx/serialization/encoding/Encoder;Lkotlinx/datetime/YearMonth;)V
+}
+
diff --git a/core/api/kotlinx-datetime.klib.api b/core/api/kotlinx-datetime.klib.api
@@ -190,6 +190,16 @@ abstract class kotlinx.datetime.serializers/FormattedUtcOffsetSerializer : kotli
     open fun serialize(kotlinx.serialization.encoding/Encoder, kotlinx.datetime/UtcOffset) // kotlinx.datetime.serializers/FormattedUtcOffsetSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlinx.datetime.UtcOffset){}[0]
 }
 
+abstract class kotlinx.datetime.serializers/FormattedYearMonthSerializer : kotlinx.serialization/KSerializer<kotlinx.datetime/YearMonth> { // kotlinx.datetime.serializers/FormattedYearMonthSerializer|null[0]
+    constructor <init>(kotlin/String, kotlinx.datetime.format/DateTimeFormat<kotlinx.datetime/YearMonth>) // kotlinx.datetime.serializers/FormattedYearMonthSerializer.<init>|<init>(kotlin.String;kotlinx.datetime.format.DateTimeFormat<kotlinx.datetime.YearMonth>){}[0]
+
+    open val descriptor // kotlinx.datetime.serializers/FormattedYearMonthSerializer.descriptor|{}descriptor[0]
+        open fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.datetime.serializers/FormattedYearMonthSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    open fun deserialize(kotlinx.serialization.encoding/Decoder): kotlinx.datetime/YearMonth // kotlinx.datetime.serializers/FormattedYearMonthSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    open fun serialize(kotlinx.serialization.encoding/Encoder, kotlinx.datetime/YearMonth) // kotlinx.datetime.serializers/FormattedYearMonthSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlinx.datetime.YearMonth){}[0]
+}
+
 final class kotlinx.datetime.format/DateTimeComponents { // kotlinx.datetime.format/DateTimeComponents|null[0]
     final var amPm // kotlinx.datetime.format/DateTimeComponents.amPm|{}amPm[0]
         final fun <get-amPm>(): kotlinx.datetime.format/AmPmMarker? // kotlinx.datetime.format/DateTimeComponents.amPm.<get-amPm>|<get-amPm>(){}[0]
@@ -1053,6 +1063,14 @@ final object kotlinx.datetime.serializers/YearMonthIso8601Serializer : kotlinx.s
     final fun serialize(kotlinx.serialization.encoding/Encoder, kotlinx.datetime/YearMonth) // kotlinx.datetime.serializers/YearMonthIso8601Serializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlinx.datetime.YearMonth){}[0]
 }
 
+final object kotlinx.datetime.serializers/YearMonthSerializer : kotlinx.serialization/KSerializer<kotlinx.datetime/YearMonth> { // kotlinx.datetime.serializers/YearMonthSerializer|null[0]
+    final val descriptor // kotlinx.datetime.serializers/YearMonthSerializer.descriptor|{}descriptor[0]
+        final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.datetime.serializers/YearMonthSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    final fun deserialize(kotlinx.serialization.encoding/Decoder): kotlinx.datetime/YearMonth // kotlinx.datetime.serializers/YearMonthSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    final fun serialize(kotlinx.serialization.encoding/Encoder, kotlinx.datetime/YearMonth) // kotlinx.datetime.serializers/YearMonthSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlinx.datetime.YearMonth){}[0]
+}
+
 final val kotlinx.datetime/isDistantFuture // kotlinx.datetime/isDistantFuture|@kotlinx.datetime.Instant{}isDistantFuture[0]
     final fun (kotlinx.datetime/Instant).<get-isDistantFuture>(): kotlin/Boolean // kotlinx.datetime/isDistantFuture.<get-isDistantFuture>|<get-isDistantFuture>@kotlinx.datetime.Instant(){}[0]
 final val kotlinx.datetime/isDistantPast // kotlinx.datetime/isDistantPast|@kotlinx.datetime.Instant{}isDistantPast[0]
diff --git a/core/common/src/YearMonth.kt b/core/common/src/YearMonth.kt
@@ -7,7 +7,7 @@ package kotlinx.datetime
 
 import kotlinx.datetime.format.*
 import kotlinx.datetime.internal.*
-import kotlinx.datetime.serializers.YearMonthIso8601Serializer
+import kotlinx.datetime.serializers.*
 import kotlinx.serialization.Serializable
 
 /**
@@ -57,7 +57,7 @@ import kotlinx.serialization.Serializable
  * @sample kotlinx.datetime.test.samples.YearMonthSamples.simpleParsingAndFormatting
  * @sample kotlinx.datetime.test.samples.YearMonthSamples.customFormat
  */
-@Serializable(with = YearMonthIso8601Serializer::class)
+@Serializable(with = YearMonthSerializer::class)
 public expect class YearMonth
 /**
  * Constructs a [YearMonth] instance from the given year-month components.
diff --git a/core/common/src/serializers/YearMonthSerializers.kt b/core/common/src/serializers/YearMonthSerializers.kt
@@ -6,6 +6,7 @@
 package kotlinx.datetime.serializers
 
 import kotlinx.datetime.YearMonth
+import kotlinx.datetime.format.DateTimeFormat
 import kotlinx.datetime.number
 import kotlinx.serialization.*
 import kotlinx.serialization.descriptors.*
@@ -16,22 +17,10 @@ import kotlinx.serialization.encoding.*
  *
  * JSON example: `"2020-01"`
  *
- * @see YearMonth.parse
- * @see YearMonth.toString
+ * @see YearMonth.Formats.ISO
  */
-public object YearMonthIso8601Serializer: KSerializer<YearMonth> {
-
-    override val descriptor: SerialDescriptor =
-        PrimitiveSerialDescriptor("kotlinx.datetime.YearMonth", PrimitiveKind.STRING)
-
-    override fun deserialize(decoder: Decoder): YearMonth =
-        YearMonth.parse(decoder.decodeString())
-
-    override fun serialize(encoder: Encoder, value: YearMonth) {
-        encoder.encodeString(value.toString())
-    }
-
-}
+public object YearMonthIso8601Serializer : KSerializer<YearMonth>
+by YearMonth.Formats.ISO.asKSerializer("kotlinx.datetime.YearMonth/ISO")
 
 /**
  * A serializer for [YearMonth] that represents a value as its components.
@@ -41,7 +30,7 @@ public object YearMonthIso8601Serializer: KSerializer<YearMonth> {
 public object YearMonthComponentSerializer: KSerializer<YearMonth> {
 
     override val descriptor: SerialDescriptor =
-        buildClassSerialDescriptor("kotlinx.datetime.LocalDate") {
+        buildClassSerialDescriptor("kotlinx.datetime.YearMonth/components") {
             element<Int>("year")
             element<Short>("month")
         }
@@ -51,11 +40,11 @@ public object YearMonthComponentSerializer: KSerializer<YearMonth> {
         decoder.decodeStructure(descriptor) {
             var year: Int? = null
             var month: Short? = null
-            loop@while (true) {
+            while (true) {
                 when (val index = decodeElementIndex(descriptor)) {
                     0 -> year = decodeIntElement(descriptor, 0)
                     1 -> month = decodeShortElement(descriptor, 1)
-                    CompositeDecoder.DECODE_DONE -> break@loop // https://youtrack.jetbrains.com/issue/KT-42262
+                    CompositeDecoder.DECODE_DONE -> break
                     else -> throwUnknownIndexException(index)
                 }
             }
@@ -72,3 +61,49 @@ public object YearMonthComponentSerializer: KSerializer<YearMonth> {
     }
 
 }
+
+/**
+ * An abstract serializer for [YearMonth] 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.YearMonth/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:
+ * ```
+ * // serializes YearMonth(2020, 1) as the string "202001"
+ * object IsoBasicYearMonthSerializer :
+ *     FormattedYearMonthSerializer("my.package.ISO_BASIC", YearMonth.Format { year(); monthNumber() })
+ * ```
+ *
+ * Note that [YearMonth] is [kotlinx.serialization.Serializable] by default,
+ * so it is not necessary to create custom serializers when the format is not important.
+ * Additionally, [YearMonthIso8601Serializer] is provided for the ISO 8601 format.
+ */
+public abstract class FormattedYearMonthSerializer(
+    name: String, format: DateTimeFormat<YearMonth>
+) : KSerializer<YearMonth> by format.asKSerializer("kotlinx.datetime.YearMonth/serializer/$name")
+
+/**
+ * A serializer for [YearMonth] that uses the default [YearMonth.toString]/[YearMonth.parse].
+ *
+ * JSON example: `"2020-01"`
+ */
+@PublishedApi
+internal object YearMonthSerializer: KSerializer<YearMonth> {
+
+    override val descriptor: SerialDescriptor =
+        PrimitiveSerialDescriptor("kotlinx.datetime.YearMonth", PrimitiveKind.STRING)
+
+    override fun deserialize(decoder: Decoder): YearMonth =
+        YearMonth.parse(decoder.decodeString())
+
+    override fun serialize(encoder: Encoder, value: YearMonth) {
+        encoder.encodeString(value.toString())
+    }
+
+}
diff --git a/core/commonKotlin/src/YearMonth.kt b/core/commonKotlin/src/YearMonth.kt
@@ -7,10 +7,10 @@ package kotlinx.datetime
 
 import kotlinx.datetime.format.*
 import kotlinx.datetime.internal.*
-import kotlinx.datetime.serializers.YearMonthIso8601Serializer
+import kotlinx.datetime.serializers.YearMonthSerializer
 import kotlinx.serialization.Serializable
 
-@Serializable(with = YearMonthIso8601Serializer::class)
+@Serializable(with = YearMonthSerializer::class)
 public actual class YearMonth
 public actual constructor(public actual val year: Int, month: Int) : Comparable<YearMonth> {
     internal actual val monthNumber: Int = month
diff --git a/core/jvm/src/YearMonthJvm.kt b/core/jvm/src/YearMonthJvm.kt
@@ -7,15 +7,15 @@ package kotlinx.datetime
 
 import kotlinx.datetime.format.*
 import kotlinx.datetime.internal.*
-import kotlinx.datetime.serializers.YearMonthIso8601Serializer
+import kotlinx.datetime.serializers.YearMonthSerializer
 import kotlinx.serialization.Serializable
 import java.time.DateTimeException
 import java.time.format.DateTimeFormatterBuilder
 import java.time.format.DateTimeParseException
 import java.time.format.SignStyle
 import java.time.YearMonth as jtYearMonth
 
-@Serializable(with = YearMonthIso8601Serializer::class)
+@Serializable(with = YearMonthSerializer::class)
 public actual class YearMonth internal constructor(
     internal val value: jtYearMonth
 ) : Comparable<YearMonth>, java.io.Serializable {
diff --git a/integration-testing/serialization/common/test/YearMonthSerializationTest.kt b/integration-testing/serialization/common/test/YearMonthSerializationTest.kt
@@ -53,18 +53,37 @@ class YearMonthSerializationTest {
 
     @Test
     fun testIso8601Serialization() {
+        assertKSerializerName("kotlinx.datetime.YearMonth/ISO", YearMonthIso8601Serializer)
         iso8601Serialization(YearMonthIso8601Serializer)
     }
 
     @Test
     fun testComponentSerialization() {
+        assertKSerializerName("kotlinx.datetime.YearMonth/components", YearMonthComponentSerializer)
         componentSerialization(YearMonthComponentSerializer)
     }
 
     @Test
     fun testDefaultSerializers() {
         // should be the same as the ISO 8601
+        assertKSerializerName<YearMonth>("kotlinx.datetime.YearMonth", Json.serializersModule.serializer())
         iso8601Serialization(Json.serializersModule.serializer())
     }
 
+    object IsoBasicYearMonthSerializer : FormattedYearMonthSerializer("ISO_BASIC", YearMonth.Format {
+        year(); monthNumber()
+    })
+
+    @Test
+    fun testCustomSerializer() {
+        assertKSerializerName("kotlinx.datetime.YearMonth/serializer/ISO_BASIC", IsoBasicYearMonthSerializer)
+        for ((yearMonth, json) in listOf(
+            Pair(YearMonth(2020, 12), "\"202012\""),
+            Pair(YearMonth(-2020, 1), "\"-202001\""),
+            Pair(YearMonth(2019, 10), "\"201910\""),
+        )) {
+            assertEquals(json, Json.encodeToString(IsoBasicYearMonthSerializer, yearMonth))
+            assertEquals(yearMonth, Json.decodeFromString(IsoBasicYearMonthSerializer, json))
+        }
+    }
 }
