Skip to content

Mention type unsoundness of serializer() in the documentation #2998

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

Mention type unsoundness of serializer() in the documentation #2998

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 31 additions & 13 deletions core/commonMain/src/kotlinx/serialization/Serializers.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,14 +58,14 @@ public inline fun <reified T> SerializersModule.serializer(): KSerializer<T> {
* Creates a serializer for the given [type].
* [type] argument is usually obtained with [typeOf] method.
*
* This overload works with full type information, including type arguments and nullability,
* and is a recommended way to retrieve a serializer.
* For example, `serializer<typeOf<List<String?>>>()` returns [KSerializer] that is able
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know what this dependent-type-style syntax means and was assuming that this was a copy-paste artifact of some sort.

* to serialize and deserialize list of nullable strings — i.e. `ListSerializer(String.serializer().nullable)`.
*
* Variance of [type]'s type arguments is not used by the serialization and is not taken into account.
* Star projections in [type]'s arguments are prohibited.
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
* Consider using the `serializer()` overload accepting a type argument (for example, `serializer<List<String>>()`),
* which returns the serializer with the correct type.
*
* @throws SerializationException if serializer cannot be created (provided [type] or its type argument is not serializable).
* @throws IllegalArgumentException if any of [type]'s arguments contains star projection
*/
Expand All @@ -80,11 +80,16 @@ public fun serializer(type: KType): KSerializer<Any?> = EmptySerializersModule()
* The nullability of returned serializer is specified using the [isNullable].
*
* Note that it is impossible to create an array serializer with this method,
* as array serializer needs additional information: type token for an element type.
* as an array serializer needs additional information: type token for an element type.
* To create array serializer, use overload with [KType] or [ArraySerializer] directly.
*
* Caching on JVM platform is disabled for this function, so it may work slower than an overload with [KType].
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
* Consider using the `serializer()` overload accepting a type argument (for example, `serializer<List<String>>()`),
* which returns the serializer with the correct type.
*
* @throws SerializationException if serializer cannot be created (provided [kClass] or its type argument is not serializable)
* @throws SerializationException if [kClass] is a `kotlin.Array`
* @throws SerializationException if size of [typeArgumentsSerializers] does not match the expected generic parameters count
Expand All @@ -100,14 +105,12 @@ public fun serializer(
* Creates a serializer for the given [type] if possible.
* [type] argument is usually obtained with [typeOf] method.
*
* This overload works with full type information, including type arguments and nullability,
* and is a recommended way to retrieve a serializer.
* For example, `serializerOrNull<typeOf<List<String?>>>()` returns [KSerializer] that is able
* to serialize and deserialize list of nullable strings — i.e. `ListSerializer(String.serializer().nullable)`.
*
* Variance of [type]'s arguments is not used by the serialization and is not taken into account.
* Star projections in [type]'s arguments are prohibited.
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
*
* @return [KSerializer] for the given [type] or `null` if serializer cannot be created (given [type] or its type argument is not serializable).
* @throws IllegalArgumentException if any of [type]'s arguments contains star projection
*/
Expand All @@ -121,11 +124,17 @@ public fun serializerOrNull(type: KType): KSerializer<Any?>? = EmptySerializersM
* This overload works with full type information, including type arguments and nullability,
* and is a recommended way to retrieve a serializer.
* For example, `serializer<typeOf<List<String?>>>()` returns [KSerializer] that is able
* to serialize and deserialize list of nullable strings — i.e. `ListSerializer(String.serializer().nullable)`.
* to serialize and deserialize a list of nullable strings — i.e. `ListSerializer(String.serializer().nullable)`.
*
* Variance of [type]'s arguments is not used by the serialization and is not taken into account.
* Star projections in [type]'s arguments are prohibited.
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
* Consider using the `serializer()` overload accepting a type argument
* (for example, `module.serializer<List<String>>()`),
* which returns the serializer with the correct type.
*
* @throws SerializationException if serializer cannot be created (provided [type] or its type argument is not serializable and is not registered in [this] module).
* @throws IllegalArgumentException if any of [type]'s arguments contains star projection
*/
Expand All @@ -143,11 +152,17 @@ public fun SerializersModule.serializer(type: KType): KSerializer<Any?> =
* The nullability of returned serializer is specified using the [isNullable].
*
* Note that it is impossible to create an array serializer with this method,
* as array serializer needs additional information: type token for an element type.
* as an array serializer needs additional information: type token for an element type.
* To create array serializer, use overload with [KType] or [ArraySerializer] directly.
*
* Caching on JVM platform is disabled for this function, so it may work slower than an overload with [KType].
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
* Consider using the `serializer()` overload accepting a type argument
* (for example, `module.serializer<List<String>>()`),
* which returns the serializer with the correct type.
*
* @throws SerializationException if serializer cannot be created (provided [kClass] or its type argument is not serializable and is not registered in [this] module)
* @throws SerializationException if [kClass] is a `kotlin.Array`
* @throws SerializationException if size of [typeArgumentsSerializers] does not match the expected generic parameters count
Expand All @@ -174,6 +189,9 @@ public fun SerializersModule.serializer(
* Variance of [type]'s arguments is not used by the serialization and is not taken into account.
* Star projections in [type]'s arguments are prohibited.
*
* **Pitfall**: the returned serializer may return incorrect results or throw a [ClassCastException] if it receives
* a value that's not a valid instance of the [KType], even though the type allows passing such a value.
*
* @return [KSerializer] for the given [type] or `null` if serializer cannot be created (given [type] or its type argument is not serializable and is not registered in [this] module).
* @throws IllegalArgumentException if any of [type]'s arguments contains star projection
*/
Expand Down