README.md

kotlinx-serialization-msgpack

Project is under active development! Important features may be missing and bugs are present!

Check out milestones for progress.

About

This library provides MsgPack support for kotlinx.serialization. It supports all of kotlin targets (JVM, JS, Native).

Integration

Maven central

Gradle:

implementation("com.ensarsarajcic.kotlinx:serialization-msgpack:${kotlinxSerializationMsgPackVersion}")

To also use timestamp support with kotlinx-datetime, use serialization-msgpack-timestamp-extension:

implementation("com.ensarsarajcic.kotlinx:serialization-msgpack-timestamp-extension:${kotlinxSerializationMsgPackVersion}")

NOTE: Timestamp support is available in core library as well, the additional library just adds a specific serializer that can be used with kotlinx-datetime types. These are MsgPackTimestamp32DatetimeSerializer, MsgPackTimestamp64DatetimeSerializer and MsgPackTimestamp96DatetimeSerializer.

For experimental kotlin unsigned types support, use serialization-msgpack-unsigned-support:

implementation("com.ensarsarajcic.kotlinx:serialization-msgpack-unsigned-support:${kotlinxSerializationMsgPackVersion}")

Snapshot builds

Gradle:

repositories {
    maven {
        url = uri("https://oss.sonatype.org/content/repositories/snapshots")
    }
}
implementation("com.ensarsarajcic.kotlinx:serialization-msgpack:${kotlinxSerializationMsgPackSnapshotVersion}")

To also use timestamp support with kotlinx-datetime, use serialization-msgpack-timestamp-extension:

implementation("com.ensarsarajcic.kotlinx:serialization-msgpack-timestamp-extension:${kotlinxSerializationMsgPackSnapshotVersion}")

For experimental kotlin unsigned types support, use serialization-msgpack-unsigned-support:

implementation("com.ensarsarajcic.kotlinx:serialization-msgpack-unsigned-support:${kotlinxSerializationMsgPackSnapshotVersion}")

Usage

Library should be used in same way as any other kotlinx.serialization library. Created models are annotated with @Serializable annotation and their serializer() can be passed to MsgPack.

Example:

@Serializable
data class SampleClass(
    val testString: String,
    val testInt: Int,
    val testBoolean: Boolean
)

fun encode() {
    println(
        MsgPack.encodeToByteArray(
            SampleClass.serializer(),
            SampleClass("def", 123, true)
        ).joinToString(separator = "") { it.toInt().and(0xff).toString(16).padStart(2, '0') }
    ) // Outputs: 83aa74657374537472696e67a3646566a774657374496e747bab74657374426f6f6c65616ec3
}

fun decode() {
    println(
        MsgPack.decodeFromByteArray(
            SampleClass.serializer(),
            "83aa74657374537472696e67a3646566a774657374496e747bab74657374426f6f6c65616ec3".let { bytesString ->
                ByteArray(bytesString.length / 2) { bytesString.substring(it * 2, it * 2 + 2).toInt(16).toByte() }
            }
        )
    ) // Outputs: SampleClass(testString=def, testInt=123, testBoolean=true)
}

Contributing

Check out contributing guidelines.

License

MIT