Add kotlin.time.Instant serializers

dkhalanskyjb · dkhalanskyjb · commit 88b69d5d9adf · 2025-03-04T17:02:18.000+01:00
Can be merged after moving to Kotlin 2.1.20, which introduces kotlin.time.Instant. kotlinx.datetime.Instant entered the stdlib as kotlin.time.Instant, and so kotlinx.serialization takes over its serializers. See Kotlin/KEEP#387
diff --git a/core/api/kotlinx-serialization-core.api b/core/api/kotlinx-serialization-core.api
@@ -202,9 +202,19 @@ public final class kotlinx/serialization/builtins/BuiltinSerializersKt {
 	public static final fun serializer (Lkotlin/jvm/internal/ShortCompanionObject;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/jvm/internal/StringCompanionObject;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/time/Duration$Companion;)Lkotlinx/serialization/KSerializer;
+	public static final fun serializer (Lkotlin/time/Instant$Companion;)Lkotlinx/serialization/KSerializer;
 	public static final fun serializer (Lkotlin/uuid/Uuid$Companion;)Lkotlinx/serialization/KSerializer;
 }
 
+public final class kotlinx/serialization/builtins/InstantComponentSerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lkotlinx/serialization/builtins/InstantComponentSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlin/time/Instant;
+	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;Lkotlin/time/Instant;)V
+}
+
 public final class kotlinx/serialization/builtins/LongAsStringSerializer : kotlinx/serialization/KSerializer {
 	public static final field INSTANCE Lkotlinx/serialization/builtins/LongAsStringSerializer;
 	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Long;
@@ -795,6 +805,15 @@ public final class kotlinx/serialization/internal/InlineClassDescriptorKt {
 	public static final fun InlinePrimitiveDescriptor (Ljava/lang/String;Lkotlinx/serialization/KSerializer;)Lkotlinx/serialization/descriptors/SerialDescriptor;
 }
 
+public final class kotlinx/serialization/internal/InstantSerializer : kotlinx/serialization/KSerializer {
+	public static final field INSTANCE Lkotlinx/serialization/internal/InstantSerializer;
+	public synthetic fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Ljava/lang/Object;
+	public fun deserialize (Lkotlinx/serialization/encoding/Decoder;)Lkotlin/time/Instant;
+	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;Lkotlin/time/Instant;)V
+}
+
 public final class kotlinx/serialization/internal/IntArrayBuilder : kotlinx/serialization/internal/PrimitiveArrayBuilder {
 	public synthetic fun build$kotlinx_serialization_core ()Ljava/lang/Object;
 }
diff --git a/core/api/kotlinx-serialization-core.klib.api b/core/api/kotlinx-serialization-core.klib.api
@@ -890,6 +890,14 @@ sealed class kotlinx.serialization.modules/SerializersModule { // kotlinx.serial
     final fun <#A1: kotlin/Any> getContextual(kotlin.reflect/KClass<#A1>): kotlinx.serialization/KSerializer<#A1>? // kotlinx.serialization.modules/SerializersModule.getContextual|getContextual(kotlin.reflect.KClass<0:0>){0§<kotlin.Any>}[0]
 }
 
+final object kotlinx.serialization.builtins/InstantComponentSerializer : kotlinx.serialization/KSerializer<kotlin.time/Instant> { // kotlinx.serialization.builtins/InstantComponentSerializer|null[0]
+    final val descriptor // kotlinx.serialization.builtins/InstantComponentSerializer.descriptor|{}descriptor[0]
+        final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.builtins/InstantComponentSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    final fun deserialize(kotlinx.serialization.encoding/Decoder): kotlin.time/Instant // kotlinx.serialization.builtins/InstantComponentSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin.time/Instant) // kotlinx.serialization.builtins/InstantComponentSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.time.Instant){}[0]
+}
+
 final object kotlinx.serialization.builtins/LongAsStringSerializer : kotlinx.serialization/KSerializer<kotlin/Long> { // kotlinx.serialization.builtins/LongAsStringSerializer|null[0]
     final val descriptor // kotlinx.serialization.builtins/LongAsStringSerializer.descriptor|{}descriptor[0]
         final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.builtins/LongAsStringSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
@@ -956,6 +964,14 @@ final object kotlinx.serialization.internal/FloatSerializer : kotlinx.serializat
     final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin/Float) // kotlinx.serialization.internal/FloatSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.Float){}[0]
 }
 
+final object kotlinx.serialization.internal/InstantSerializer : kotlinx.serialization/KSerializer<kotlin.time/Instant> { // kotlinx.serialization.internal/InstantSerializer|null[0]
+    final val descriptor // kotlinx.serialization.internal/InstantSerializer.descriptor|{}descriptor[0]
+        final fun <get-descriptor>(): kotlinx.serialization.descriptors/SerialDescriptor // kotlinx.serialization.internal/InstantSerializer.descriptor.<get-descriptor>|<get-descriptor>(){}[0]
+
+    final fun deserialize(kotlinx.serialization.encoding/Decoder): kotlin.time/Instant // kotlinx.serialization.internal/InstantSerializer.deserialize|deserialize(kotlinx.serialization.encoding.Decoder){}[0]
+    final fun serialize(kotlinx.serialization.encoding/Encoder, kotlin.time/Instant) // kotlinx.serialization.internal/InstantSerializer.serialize|serialize(kotlinx.serialization.encoding.Encoder;kotlin.time.Instant){}[0]
+}
+
 final object kotlinx.serialization.internal/IntArraySerializer : kotlinx.serialization.internal/PrimitiveArraySerializer<kotlin/Int, kotlin/IntArray, kotlinx.serialization.internal/IntArrayBuilder>, kotlinx.serialization/KSerializer<kotlin/IntArray> // kotlinx.serialization.internal/IntArraySerializer|null[0]
 
 final object kotlinx.serialization.internal/IntSerializer : kotlinx.serialization/KSerializer<kotlin/Int> { // kotlinx.serialization.internal/IntSerializer|null[0]
@@ -1074,6 +1090,7 @@ final val kotlinx.serialization.modules/EmptySerializersModule // kotlinx.serial
     final fun <get-EmptySerializersModule>(): kotlinx.serialization.modules/SerializersModule // kotlinx.serialization.modules/EmptySerializersModule.<get-EmptySerializersModule>|<get-EmptySerializersModule>(){}[0]
 
 final fun (kotlin.time/Duration.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.time/Duration> // kotlinx.serialization.builtins/serializer|serializer@kotlin.time.Duration.Companion(){}[0]
+final fun (kotlin.time/Instant.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.time/Instant> // kotlinx.serialization.builtins/serializer|serializer@kotlin.time.Instant.Companion(){}[0]
 final fun (kotlin.uuid/Uuid.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin.uuid/Uuid> // kotlinx.serialization.builtins/serializer|serializer@kotlin.uuid.Uuid.Companion(){}[0]
 final fun (kotlin/Boolean.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin/Boolean> // kotlinx.serialization.builtins/serializer|serializer@kotlin.Boolean.Companion(){}[0]
 final fun (kotlin/Byte.Companion).kotlinx.serialization.builtins/serializer(): kotlinx.serialization/KSerializer<kotlin/Byte> // kotlinx.serialization.builtins/serializer|serializer@kotlin.Byte.Companion(){}[0]
diff --git a/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt b/core/commonMain/src/kotlinx/serialization/builtins/BuiltinSerializers.kt
@@ -10,6 +10,8 @@ import kotlinx.serialization.internal.*
 import kotlin.reflect.*
 import kotlinx.serialization.descriptors.*
 import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 import kotlin.uuid.*
 
 /**
@@ -251,6 +253,19 @@ public fun UShort.Companion.serializer(): KSerializer<UShort> = UShortSerializer
  */
 public fun Duration.Companion.serializer(): KSerializer<Duration> = DurationSerializer
 
+/**
+ * Returns serializer for [Instant].
+ * It is serialized as a string that represents an instant in the format described in ISO-8601-1:2019, 5.4.2.1b).
+ *
+ * Deserialization is case-insensitive.
+ * More details can be found in the documentation of [Instant.toString] and [Instant.parse] functions.
+ *
+ * @see Instant.toString
+ * @see Instant.parse
+ */
+@ExperimentalTime
+public fun Instant.Companion.serializer(): KSerializer<Instant> = InstantSerializer
+
 /**
  * Returns serializer for [Uuid].
  * Serializer operates with a standard UUID string representation, also known as "hex-and-dash" format —
diff --git a/core/commonMain/src/kotlinx/serialization/builtins/InstantComponentSerializer.kt b/core/commonMain/src/kotlinx/serialization/builtins/InstantComponentSerializer.kt
@@ -0,0 +1,51 @@
+/*
+ * Copyright 2025-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package kotlinx.serialization.builtins
+
+import kotlinx.serialization.*
+import kotlinx.serialization.descriptors.*
+import kotlinx.serialization.encoding.*
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
+
+@ExperimentalTime
+public object InstantComponentSerializer : KSerializer<Instant> {
+
+    override val descriptor: SerialDescriptor =
+        buildClassSerialDescriptor("kotlinx.serialization.InstantComponentSerializer") {
+            element<Long>("epochSeconds")
+            element<Long>("nanosecondsOfSecond", isOptional = true)
+        }
+
+    @OptIn(ExperimentalSerializationApi::class)
+    override fun deserialize(decoder: Decoder): Instant =
+        decoder.decodeStructure(descriptor) {
+            var epochSeconds: Long? = null
+            var nanosecondsOfSecond = 0
+            loop@ while (true) {
+                when (val index = decodeElementIndex(descriptor)) {
+                    0 -> epochSeconds = decodeLongElement(descriptor, 0)
+                    1 -> nanosecondsOfSecond = decodeIntElement(descriptor, 1)
+                    CompositeDecoder.DECODE_DONE -> break@loop // https://youtrack.jetbrains.com/issue/KT-42262
+                    else -> throw SerializationException("Unexpected index: $index")
+                }
+            }
+            if (epochSeconds == null) throw MissingFieldException(
+                missingField = "epochSeconds",
+                serialName = descriptor.serialName
+            )
+            Instant.fromEpochSeconds(epochSeconds, nanosecondsOfSecond)
+        }
+
+    override fun serialize(encoder: Encoder, value: Instant) {
+        encoder.encodeStructure(descriptor) {
+            encodeLongElement(descriptor, 0, value.epochSeconds)
+            if (value.nanosecondsOfSecond != 0) {
+                encodeIntElement(descriptor, 1, value.nanosecondsOfSecond)
+            }
+        }
+    }
+
+}
diff --git a/core/commonMain/src/kotlinx/serialization/internal/BuiltInSerializers.kt b/core/commonMain/src/kotlinx/serialization/internal/BuiltInSerializers.kt
@@ -10,6 +10,8 @@ import kotlinx.serialization.descriptors.SerialDescriptor
 import kotlinx.serialization.encoding.Decoder
 import kotlinx.serialization.encoding.Encoder
 import kotlin.time.Duration
+import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 import kotlin.uuid.*
 
 
@@ -39,6 +41,20 @@ internal object NothingSerializer : KSerializer<Nothing> {
     }
 }
 
+@PublishedApi
+@ExperimentalTime
+internal object InstantSerializer : KSerializer<Instant> {
+    override val descriptor: SerialDescriptor = PrimitiveSerialDescriptor("kotlin.time.Instant", PrimitiveKind.STRING)
+
+    override fun serialize(encoder: Encoder, value: Instant) {
+        encoder.encodeString(value.toString())
+    }
+
+    override fun deserialize(decoder: Decoder): Instant {
+        return Instant.parse(decoder.decodeString())
+    }
+}
+
 @PublishedApi
 @ExperimentalUuidApi
 internal object UuidSerializer: KSerializer<Uuid> {
diff --git a/core/commonTest/src/kotlinx/serialization/BasicTypesSerializationTest.kt b/core/commonTest/src/kotlinx/serialization/BasicTypesSerializationTest.kt
@@ -10,9 +10,10 @@ import kotlinx.serialization.descriptors.*
 import kotlinx.serialization.encoding.*
 import kotlinx.serialization.encoding.CompositeDecoder.Companion.UNKNOWN_NAME
 import kotlinx.serialization.modules.*
-import kotlinx.serialization.test.*
 import kotlin.test.*
 import kotlin.time.Duration
+import kotlin.time.Instant
+import kotlin.time.ExperimentalTime
 
 /*
  * Test ensures that type that aggregate all basic (primitive/collection/maps/arrays)
@@ -193,6 +194,27 @@ class BasicTypesSerializationTest {
         assertEquals(Duration.parseIsoString(durationString), other)
     }
 
+    @OptIn(ExperimentalTime::class)
+    @Test
+    fun testEncodeInstant() {
+        val sb = StringBuilder()
+        val out = KeyValueOutput(sb)
+
+        val instant = Instant.parse("2020-12-09T09:16:56.000124Z")
+        out.encodeSerializableValue(Instant.serializer(), instant)
+
+        assertEquals("\"${instant}\"", sb.toString())
+    }
+
+    @OptIn(ExperimentalTime::class)
+    @Test
+    fun testDecodeInstant() {
+        val instantString = "2020-12-09T09:16:56.000124Z"
+        val inp = KeyValueInput(Parser(StringReader("\"$instantString\"")))
+        val other = inp.decodeSerializableValue(Instant.serializer())
+        assertEquals(Instant.parse(instantString), other)
+    }
+
     @Test
     fun testNothingSerialization() {
         // impossible to deserialize Nothing
diff --git a/core/jsMain/src/kotlinx/serialization/internal/Platform.kt b/core/jsMain/src/kotlinx/serialization/internal/Platform.kt
@@ -81,7 +81,8 @@ private val KClass<*>.isInterface: Boolean
         return js.asDynamic().`$metadata$`?.kind == "interface"
     }
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -111,5 +112,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )
diff --git a/core/jvmMain/src/kotlinx/serialization/internal/Platform.kt b/core/jvmMain/src/kotlinx/serialization/internal/Platform.kt
@@ -201,6 +201,9 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = buildMap {
     }
     @OptIn(ExperimentalUuidApi::class)
     loadSafe { put(Uuid::class, Uuid.serializer()) }
+
+    @OptIn(ExperimentalTime::class)
+    loadSafe { put(Instant::class, Instant.serializer()) }
 }
 
 // Reference classes in [block] ignoring any exceptions related to class loading
diff --git a/core/nativeMain/src/kotlinx/serialization/internal/Platform.kt b/core/nativeMain/src/kotlinx/serialization/internal/Platform.kt
@@ -75,7 +75,8 @@ private fun <T> arrayOfAnyNulls(size: Int): Array<T> = arrayOfNulls<Any>(size) a
 
 internal actual fun isReferenceArray(rootClass: KClass<Any>): Boolean = rootClass == Array::class
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -105,5 +106,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )
diff --git a/core/wasmMain/src/kotlinx/serialization/internal/Platform.kt b/core/wasmMain/src/kotlinx/serialization/internal/Platform.kt
@@ -65,7 +65,8 @@ internal actual fun <T : Any, E : T?> ArrayList<E>.toNativeArrayImpl(eClass: KCl
 
 internal actual fun isReferenceArray(rootClass: KClass<Any>): Boolean = rootClass == Array::class
 
-@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class)
+@OptIn(ExperimentalUnsignedTypes::class, ExperimentalUuidApi::class, ExperimentalSerializationApi::class,
+    ExperimentalTime::class)
 internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     String::class to String.serializer(),
     Char::class to Char.serializer(),
@@ -95,5 +96,6 @@ internal actual fun initBuiltins(): Map<KClass<*>, KSerializer<*>> = mapOf(
     Unit::class to Unit.serializer(),
     Nothing::class to NothingSerializer(),
     Duration::class to Duration.serializer(),
+    Instant::class to Instant.serializer(),
     Uuid::class to Uuid.serializer()
 )
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -1,5 +1,5 @@
 [versions]
-kotlin = "2.1.0"
+kotlin = "2.1.20-RC"
 kover = "0.8.2"
 dokka = "2.0.0-Beta"
 knit = "0.5.0"

Original file line number	Diff line number	Diff line change
`@@ -201,6 +201,9 @@ internal actual fun initBuiltins(): Map<KClass<>, KSerializer<>> = buildMap {`
`201`	`201`	`}`
`202`	`202`	`@OptIn(ExperimentalUuidApi::class)`
`203`	`203`	`loadSafe { put(Uuid::class, Uuid.serializer()) }`
	`204`	`+`
	`205`	`+ @OptIn(ExperimentalTime::class)`
	`206`	`+ loadSafe { put(Instant::class, Instant.serializer()) }`
`204`	`207`	`}`
`205`	`208`
`206`	`209`	`// Reference classes in [block] ignoring any exceptions related to class loading`