Make DeserializationStrategy covariant at declaration-site (#1897)

The type parameter T of DeserializationStrategy only appears in an out
position, namely as the return type of deserialize().
It can therefore be annotated with `out` to increase API flexibility
compared to DeserializationStrategy being invariant.
E.g. a function taking DeserializationStrategy<Number> will now also
accept an object of type DeserializationStrategy<Int>.

This also results in DeserializationStrategy being more similar to the
symmetric SerializationStrategy interface which is already contravariant
at declaration-site (interface SerializationStrategy<in T>):
SerializationStrategy is a consumer, and DeserializationStrategy is a producer.

This change is
* binary backward compatible: generics are erased at runtime
* source backward compatible: previously specified out projections
  (use-site covariance) will only report a warning about a redundant
  projection

Author: lukellmann

core/commonMain/src/kotlinx/serialization/KSerializer.kt

@@ -5,7 +5,6 @@
 package kotlinx.serialization
 
 import kotlinx.serialization.descriptors.*
-import kotlinx.serialization.descriptors.elementNames
 import kotlinx.serialization.encoding.*
 
 /**
@@ -140,7 +139,7 @@ public interface SerializationStrategy<in T> {
  *
  * For a more detailed explanation of the serialization process, please refer to [KSerializer] documentation.
  */
-public interface DeserializationStrategy<T> {
+public interface DeserializationStrategy<out T> {
     /**
      * Describes the structure of the serializable representation of [T], that current
      * deserializer is able to deserialize.
@@ -193,4 +192,3 @@ public interface DeserializationStrategy<T> {
      */
     public fun deserialize(decoder: Decoder): T
 }
-

core/commonMain/src/kotlinx/serialization/PolymorphicSerializer.kt

@@ -98,7 +98,7 @@ public class PolymorphicSerializer<T : Any>(override val baseClass: KClass<T>) :
 public fun <T : Any> AbstractPolymorphicSerializer<T>.findPolymorphicSerializer(
     decoder: CompositeDecoder,
     klassName: String?
-): DeserializationStrategy<out T> =
+): DeserializationStrategy<T> =
     findPolymorphicSerializerOrNull(decoder, klassName) ?: throwSubtypeNotRegistered(klassName, baseClass)
 
 @InternalSerializationApi

core/commonMain/src/kotlinx/serialization/SealedSerializer.kt

@@ -137,7 +137,7 @@ public class SealedClassSerializer<T : Any>(
             }.mapValues { it.value.value }
     }
 
-    override fun findPolymorphicSerializerOrNull(decoder: CompositeDecoder, klassName: String?): DeserializationStrategy<out T>? {
+    override fun findPolymorphicSerializerOrNull(decoder: CompositeDecoder, klassName: String?): DeserializationStrategy<T>? {
         return serialName2Serializer[klassName] ?: super.findPolymorphicSerializerOrNull(decoder, klassName)
     }
 

core/commonMain/src/kotlinx/serialization/internal/AbstractPolymorphicSerializer.kt

@@ -81,7 +81,7 @@ public abstract class AbstractPolymorphicSerializer<T : Any> internal constructo
     public open fun findPolymorphicSerializerOrNull(
         decoder: CompositeDecoder,
         klassName: String?
-    ): DeserializationStrategy<out T>? = decoder.serializersModule.getPolymorphic(baseClass, klassName)
+    ): DeserializationStrategy<T>? = decoder.serializersModule.getPolymorphic(baseClass, klassName)
 
 
     /**

core/commonMain/src/kotlinx/serialization/modules/PolymorphicModuleBuilder.kt

@@ -21,7 +21,7 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
 ) {
     private val subclasses: MutableList<Pair<KClass<out Base>, KSerializer<out Base>>> = mutableListOf()
     private var defaultSerializerProvider: ((Base) -> SerializationStrategy<Base>?)? = null
-    private var defaultDeserializerProvider: ((String?) -> DeserializationStrategy<out Base>?)? = null
+    private var defaultDeserializerProvider: ((String?) -> DeserializationStrategy<Base>?)? = null
 
     /**
      * Registers a [subclass] [serializer] in the resulting module under the [base class][Base].
@@ -46,7 +46,7 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
      * Default deserializers provider affects only deserialization process.
      */
     @ExperimentalSerializationApi
-    public fun defaultDeserializer(defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?) {
+    public fun defaultDeserializer(defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?) {
         require(this.defaultDeserializerProvider == null) {
             "Default deserializer provider is already registered for class $baseClass: ${this.defaultDeserializerProvider}"
         }
@@ -75,7 +75,7 @@ public class PolymorphicModuleBuilder<in Base : Any> @PublishedApi internal cons
      */
     @OptIn(ExperimentalSerializationApi::class)
     // TODO: deprecate in 1.4
-    public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy<out Base>?) {
+    public fun default(defaultSerializerProvider: (className: String?) -> DeserializationStrategy<Base>?) {
         defaultDeserializer(defaultSerializerProvider)
     }
 

core/commonMain/src/kotlinx/serialization/modules/SerializersModule.kt

@@ -61,7 +61,7 @@ public sealed class SerializersModule {
      * or default value constructed from [serializedClassName] if a default serializer provider was registered.
      */
     @ExperimentalSerializationApi
-    public abstract fun <T : Any> getPolymorphic(baseClass: KClass<in T>, serializedClassName: String?): DeserializationStrategy<out T>?
+    public abstract fun <T : Any> getPolymorphic(baseClass: KClass<in T>, serializedClassName: String?): DeserializationStrategy<T>?
 
     /**
      * Copies contents of this module to the given [collector].
@@ -129,7 +129,7 @@ public infix fun SerializersModule.overwriteWith(other: SerializersModule): Seri
 
         override fun <Base : Any> polymorphicDefaultDeserializer(
             baseClass: KClass<Base>,
-            defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
+            defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
         ) {
             registerDefaultPolymorphicDeserializer(baseClass, defaultDeserializerProvider, allowOverwrite = true)
         }
@@ -161,7 +161,7 @@ internal class SerialModuleImpl(
         return (polyBase2DefaultSerializerProvider[baseClass] as? PolymorphicSerializerProvider<T>)?.invoke(value)
     }
 
-    override fun <T : Any> getPolymorphic(baseClass: KClass<in T>, serializedClassName: String?): DeserializationStrategy<out T>? {
+    override fun <T : Any> getPolymorphic(baseClass: KClass<in T>, serializedClassName: String?): DeserializationStrategy<T>? {
         // Registered
         val registered = polyBase2NamedSerializers[baseClass]?.get(serializedClassName) as? KSerializer<out T>
         if (registered != null) return registered
@@ -204,7 +204,7 @@ internal class SerialModuleImpl(
     }
 }
 
-internal typealias PolymorphicDeserializerProvider<Base> = (className: String?) -> DeserializationStrategy<out Base>?
+internal typealias PolymorphicDeserializerProvider<Base> = (className: String?) -> DeserializationStrategy<Base>?
 internal typealias PolymorphicSerializerProvider<Base> = (value: Base) -> SerializationStrategy<Base>?
 
 /** This class is needed to support re-registering the same static (argless) serializers:

core/commonMain/src/kotlinx/serialization/modules/SerializersModuleBuilders.kt

@@ -122,7 +122,7 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser
     @ExperimentalSerializationApi
     public override fun <Base : Any> polymorphicDefaultDeserializer(
         baseClass: KClass<Base>,
-        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
+        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
     ) {
         registerDefaultPolymorphicDeserializer(baseClass, defaultDeserializerProvider, false)
     }
@@ -168,7 +168,7 @@ public class SerializersModuleBuilder @PublishedApi internal constructor() : Ser
     @JvmName("registerDefaultPolymorphicDeserializer") // Don't mangle method name for prettier stack traces
     internal fun <Base : Any> registerDefaultPolymorphicDeserializer(
         baseClass: KClass<Base>,
-        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?,
+        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?,
         allowOverwrite: Boolean
     ) {
         val previous = polyBase2DefaultDeserializerProvider[baseClass]

core/commonMain/src/kotlinx/serialization/modules/SerializersModuleCollector.kt

@@ -70,7 +70,7 @@ public interface SerializersModuleCollector {
     @ExperimentalSerializationApi
     public fun <Base : Any> polymorphicDefaultDeserializer(
         baseClass: KClass<Base>,
-        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
+        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
     )
 
     /**
@@ -84,7 +84,7 @@ public interface SerializersModuleCollector {
     // TODO: deprecate in 1.4
     public fun <Base : Any> polymorphicDefault(
         baseClass: KClass<Base>,
-        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
+        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
     ) {
         polymorphicDefaultDeserializer(baseClass, defaultDeserializerProvider)
     }

formats/json/commonMain/src/kotlinx/serialization/json/JsonContentPolymorphicSerializer.kt

@@ -96,7 +96,7 @@ public abstract class JsonContentPolymorphicSerializer<T : Any>(private val base
     /**
      * Determines a particular strategy for deserialization by looking on a parsed JSON [element].
      */
-    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<out T>
+    protected abstract fun selectDeserializer(element: JsonElement): DeserializationStrategy<T>
 
     private fun throwSubtypeNotRegistered(subClass: KClass<*>, baseClass: KClass<*>): Nothing {
         val subClassName = subClass.simpleName ?: "$subClass"

formats/json/commonMain/src/kotlinx/serialization/json/internal/PolymorphismValidator.kt

@@ -83,7 +83,7 @@ internal class PolymorphismValidator(
 
     override fun <Base : Any> polymorphicDefaultDeserializer(
         baseClass: KClass<Base>,
-        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<out Base>?
+        defaultDeserializerProvider: (className: String?) -> DeserializationStrategy<Base>?
     ) {
         // Nothing here
     }