tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm

Kotlin multiplatform serialization runtime library core module with JVM target support

—

Pending

Overview

Eval results

Files

Built-in Serializers

Name: tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm
Author: tessl

kotlinx.serialization provides a comprehensive set of pre-built serializers for primitive types, collections, arrays, and common Kotlin types. These serializers handle the most common serialization scenarios and serve as building blocks for more complex serialization logic.

Capabilities

Primitive Type Serializers

Built-in serializers for all Kotlin primitive types.

/** Returns serializer for Boolean type */
val Boolean.Companion.serializer: KSerializer<Boolean>

/** Returns serializer for Byte type */
val Byte.Companion.serializer: KSerializer<Byte>

/** Returns serializer for Short type */
val Short.Companion.serializer: KSerializer<Short>

/** Returns serializer for Int type */
val Int.Companion.serializer: KSerializer<Int>

/** Returns serializer for Long type */
val Long.Companion.serializer: KSerializer<Long>

/** Returns serializer for Float type */
val Float.Companion.serializer: KSerializer<Float>

/** Returns serializer for Double type */
val Double.Companion.serializer: KSerializer<Double>

/** Returns serializer for Char type */
val Char.Companion.serializer: KSerializer<Char>

/** Returns serializer for String type */
val String.Companion.serializer: KSerializer<String>

Usage Examples:

import kotlinx.serialization.*
import kotlinx.serialization.json.*
import kotlinx.serialization.builtins.*

// Using primitive serializers directly
val json = Json

val intValue = 42
val serializedInt = json.encodeToString(Int.serializer(), intValue)
val deserializedInt = json.decodeFromString(Int.serializer(), serializedInt)

val stringValue = "Hello, World!"
val serializedString = json.encodeToString(String.serializer(), stringValue)
val deserializedString = json.decodeFromString(String.serializer(), serializedString)

// Primitive serializers are automatically used for @Serializable classes
@Serializable
data class PrimitiveData(
    val flag: Boolean,      // Uses Boolean.serializer
    val count: Int,         // Uses Int.serializer  
    val name: String,       // Uses String.serializer
    val score: Double       // Uses Double.serializer
)

Unsigned Type Serializers

Serializers for Kotlin's unsigned integer types.

/** Returns serializer for UByte type */
val UByte.Companion.serializer: KSerializer<UByte>

/** Returns serializer for UShort type */  
val UShort.Companion.serializer: KSerializer<UShort>

/** Returns serializer for UInt type */
val UInt.Companion.serializer: KSerializer<UInt>

/** Returns serializer for ULong type */
val ULong.Companion.serializer: KSerializer<ULong>

Usage Examples:

@Serializable
data class UnsignedData(
    val smallValue: UByte,    // 0..255
    val mediumValue: UInt,    // 0..4,294,967,295
    val largeValue: ULong     // 0..18,446,744,073,709,551,615
)

val data = UnsignedData(255u, 4294967295u, 18446744073709551615u)
val json = Json.encodeToString(data)

Array Serializers

Specialized serializers for Kotlin's primitive array types.

/** Returns serializer for ByteArray */
fun ByteArraySerializer(): KSerializer<ByteArray>

/** Returns serializer for ShortArray */
fun ShortArraySerializer(): KSerializer<ShortArray>

/** Returns serializer for IntArray */
fun IntArraySerializer(): KSerializer<IntArray>

/** Returns serializer for LongArray */
fun LongArraySerializer(): KSerializer<LongArray>

/** Returns serializer for FloatArray */
fun FloatArraySerializer(): KSerializer<FloatArray>

/** Returns serializer for DoubleArray */
fun DoubleArraySerializer(): KSerializer<DoubleArray>

/** Returns serializer for CharArray */
fun CharArraySerializer(): KSerializer<CharArray>

/** Returns serializer for BooleanArray */
fun BooleanArraySerializer(): KSerializer<BooleanArray>

/** Returns serializer for UByteArray */
fun UByteArraySerializer(): KSerializer<UByteArray>

/** Returns serializer for UShortArray */
fun UShortArraySerializer(): KSerializer<UShortArray>

/** Returns serializer for UIntArray */
fun UIntArraySerializer(): KSerializer<UIntArray>

/** Returns serializer for ULongArray */
fun ULongArraySerializer(): KSerializer<ULongArray>

Usage Examples:

import kotlinx.serialization.builtins.*

// Serialize primitive arrays
val intArray = intArrayOf(1, 2, 3, 4, 5)
val serializedArray = Json.encodeToString(IntArraySerializer(), intArray)
val deserializedArray = Json.decodeFromString(IntArraySerializer(), serializedArray)

// In data classes - arrays require explicit serializers
@Serializable
data class ArrayData(
    @Serializable(with = ByteArraySerializer::class)
    val bytes: ByteArray,
    
    @Serializable(with = IntArraySerializer::class)  
    val numbers: IntArray
)

Collection Serializers

Factory functions for creating serializers for Kotlin collection types.

/**
 * Creates a serializer for List<T>.
 * @param elementSerializer Serializer for list elements
 * @return KSerializer for List<T>
 */
fun <T> ListSerializer(elementSerializer: KSerializer<T>): KSerializer<List<T>>

/**
 * Creates a serializer for Set<T>.
 * @param elementSerializer Serializer for set elements
 * @return KSerializer for Set<T>
 */
fun <T> SetSerializer(elementSerializer: KSerializer<T>): KSerializer<Set<T>>

/**
 * Creates a serializer for Map<K,V>.
 * @param keySerializer Serializer for map keys
 * @param valueSerializer Serializer for map values
 * @return KSerializer for Map<K,V>
 */
fun <K, V> MapSerializer(
    keySerializer: KSerializer<K>, 
    valueSerializer: KSerializer<V>
): KSerializer<Map<K, V>>

/**
 * Creates a serializer for Pair<A,B>.
 * @param aSerializer Serializer for first element
 * @param bSerializer Serializer for second element
 * @return KSerializer for Pair<A,B>
 */
fun <A, B> PairSerializer(
    aSerializer: KSerializer<A>, 
    bSerializer: KSerializer<B>
): KSerializer<Pair<A, B>>

/**
 * Creates a serializer for Triple<A,B,C>.
 * @param aSerializer Serializer for first element
 * @param bSerializer Serializer for second element
 * @param cSerializer Serializer for third element
 * @return KSerializer for Triple<A,B,C>
 */
fun <A, B, C> TripleSerializer(
    aSerializer: KSerializer<A>, 
    bSerializer: KSerializer<B>, 
    cSerializer: KSerializer<C>
): KSerializer<Triple<A, B, C>>

/**
 * Creates a serializer for Map.Entry<K,V>.
 * @param keySerializer Serializer for entry keys
 * @param valueSerializer Serializer for entry values
 * @return KSerializer for Map.Entry<K,V>
 */
fun <K, V> MapEntrySerializer(
    keySerializer: KSerializer<K>, 
    valueSerializer: KSerializer<V>
): KSerializer<Map.Entry<K, V>>

Usage Examples:

import kotlinx.serialization.*
import kotlinx.serialization.builtins.*

// Collection serializers are automatically inferred for @Serializable classes
@Serializable
data class CollectionData(
    val names: List<String>,           // Uses ListSerializer(String.serializer())
    val uniqueIds: Set<Int>,          // Uses SetSerializer(Int.serializer())
    val mapping: Map<String, Double>   // Uses MapSerializer(String.serializer(), Double.serializer())
)

// Manual collection serialization
val listOfInts = listOf(1, 2, 3, 4)
val listSerializer = ListSerializer(Int.serializer())
val serializedList = Json.encodeToString(listSerializer, listOfInts)

val mapOfData = mapOf("a" to 1, "b" to 2, "c" to 3)
val mapSerializer = MapSerializer(String.serializer(), Int.serializer())
val serializedMap = Json.encodeToString(mapSerializer, mapOfData)

// Nested collections
val nestedList = listOf(listOf(1, 2), listOf(3, 4))
val nestedSerializer = ListSerializer(ListSerializer(Int.serializer()))
val serializedNested = Json.encodeToString(nestedSerializer, nestedList)

Special Type Serializers

Serializers for special Kotlin types and standard library classes.

/** Returns serializer for Unit type */
val Unit.Companion.serializer: KSerializer<Unit>

/** Returns serializer for Duration type */
val Duration.Companion.serializer: KSerializer<Duration>

/** Returns serializer for Instant type */  
val Instant.Companion.serializer: KSerializer<Instant>

/** Returns serializer for Uuid type */
val Uuid.Companion.serializer: KSerializer<Uuid>

Usage Examples:

import kotlin.time.Duration
import kotlinx.datetime.Instant
import kotlinx.uuid.Uuid

@Serializable
data class TimedEvent(
    val id: Uuid,
    val timestamp: Instant,
    val duration: Duration,
    val metadata: Unit = Unit  // Often used as a placeholder
)

val event = TimedEvent(
    id = Uuid.random(),
    timestamp = Instant.now(),
    duration = Duration.parse("1h 30m")
)

val json = Json.encodeToString(event)

Nullable Serializers

Extension property for creating nullable versions of any serializer.

/**
 * Returns a nullable serializer for the given non-null serializer.
 * Handles null values appropriately in the serialization format.
 */
val <T : Any> KSerializer<T>.nullable: KSerializer<T?>

Usage Examples:

import kotlinx.serialization.builtins.*

// Create nullable serializers
val nullableStringSerializer = String.serializer().nullable
val nullableIntSerializer = Int.serializer().nullable

// Serialize nullable values
val nullableValue: String? = null
val serialized = Json.encodeToString(nullableStringSerializer, nullableValue)
// Result: "null"

val nonNullValue: String? = "Hello"
val serialized2 = Json.encodeToString(nullableStringSerializer, nonNullValue)
// Result: "\"Hello\""

// In data classes - nullable properties are handled automatically
@Serializable
data class OptionalData(
    val name: String,
    val nickname: String? = null,    // Automatically uses String.serializer().nullable
    val age: Int? = null            // Automatically uses Int.serializer().nullable
)

Utility Serializers

Additional specialized serializers for specific use cases available in the JVM-specific extensions.

/**
 * Serializer that represents Long values as strings.
 * Useful for JavaScript compatibility where large numbers lose precision.
 */
object LongAsStringSerializer : KSerializer<Long>

/**
 * Serializer for Instant that handles nanosecond precision.
 * Provides more precise timestamp serialization than the default.
 */
object InstantComponentSerializer : KSerializer<Instant>

Integration Patterns

Custom Serializer Composition

Built-in serializers can be composed to create more complex serializers:

import kotlinx.serialization.*
import kotlinx.serialization.builtins.*
import kotlinx.serialization.encoding.*
import kotlinx.serialization.descriptors.*

// Custom serializer using built-in serializers as components
object CoordinateSerializer : KSerializer<Coordinate> {
    private val doubleSerializer = Double.serializer()
    
    override val descriptor = buildClassSerialDescriptor("Coordinate") {
        element("lat", doubleSerializer.descriptor)
        element("lng", doubleSerializer.descriptor)
    }
    
    override fun serialize(encoder: Encoder, value: Coordinate) {
        encoder.encodeStructure(descriptor) {
            encodeSerializableElement(descriptor, 0, doubleSerializer, value.lat)
            encodeSerializableElement(descriptor, 1, doubleSerializer, value.lng)
        }
    }
    
    override fun deserialize(decoder: Decoder): Coordinate {
        return decoder.decodeStructure(descriptor) {
            var lat = 0.0
            var lng = 0.0
            
            while (true) {
                when (val index = decodeElementIndex(descriptor)) {
                    0 -> lat = decodeSerializableElement(descriptor, index, doubleSerializer)
                    1 -> lng = decodeSerializableElement(descriptor, index, doubleSerializer)
                    CompositeDecoder.DECODE_DONE -> break
                    else -> error("Unexpected index: $index")
                }
            }
            
            Coordinate(lat, lng)
        }
    }
}

Format-Specific Considerations

Some built-in serializers may behave differently depending on the format:

// JSON handles numbers naturally
val jsonResult = Json.encodeToString(Long.serializer(), 123456789012345L)
// Result: 123456789012345

// For JavaScript compatibility, use LongAsStringSerializer
val jsCompatibleResult = Json.encodeToString(LongAsStringSerializer, 123456789012345L)
// Result: "123456789012345"

// Binary formats handle all numeric types efficiently
val protobufResult = ProtoBuf.encodeToByteArray(Long.serializer(), 123456789012345L)

Error Handling

Common errors when working with built-in serializers:

SerializationException: Type mismatches or invalid data during deserialization
IllegalArgumentException: Invalid configuration or null values for non-nullable serializers
NumberFormatException: Invalid numeric strings when deserializing number types
ClassCastException: Incorrect serializer usage for collection types

Install with Tessl CLI

npx tessl i tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm

docs

annotations.md

built-ins.md

core-serialization.md

tessl/maven-org-jetbrains-kotlinx--kotlinx-serialization-core-jvm

built-ins.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Built-in Serializers

Capabilities

Primitive Type Serializers

Unsigned Type Serializers

Array Serializers

Collection Serializers

Special Type Serializers

Nullable Serializers

Utility Serializers

Integration Patterns

Custom Serializer Composition

Format-Specific Considerations

Error Handling

built-ins.mddocs/