Pbandk: Kotlin Multiplatform Protocol Buffers

Pbandk is a Kotlin Multiplatform library, but support levels vary by platform:

Stable/Primary Platforms

• JVM, Android, and Native (iOS, macOS, Linux): Fully supported.
• Windows (mingwX64): Supported on a best-effort basis. While the runtime is available, full correctness cannot be guaranteed via official protobuf conformance tests on Windows, though it shares most code with Linux/macOS.

Experimental Platforms

• Kotlin/JS (js): Support is experimental. While using pbandk from other KMP code on JS is mostly stable, using it directly from Javascript/Typescript is not well supported due to @JsExport limitations.
• Kotlin/Wasm (wasmJs): Support is experimental. Pbandk APIs and generated code can only be called from other Kotlin code compiled for Wasm; they cannot be called directly from Javascript or other Wasm host languages due to limitations in passing complex types to the Wasm host environment.

Pbandk generates Kotlin data classes that implement the pbandk.Message interface. These classes represent Protobuf messages and include several key features:

• Data Classes: Messages are represented as standard Kotlin data classes, making them easy to use with standard Kotlin features.
• Companion Objects: Each message has a Companion object that provides a defaultInstance and a decodeWith(u: pbandk.MessageDecoder) method for deserialization.
• Enums: Protobuf enums are generated as sealed classes implementing pbandk.Message.Enum. They include a values list and helper methods like fromValue(value: Int) and fromName(name: String).
• Unknown Fields: Every message includes an unknownFields property of type Map<Int, pbandk.UnknownField> to preserve data that was not recognized during decoding.
• Merging: Messages implement the plus operator (operator fun plus(other: pbandk.Message?)) to allow merging two messages together.
• Descriptors: Each message provides a descriptor property of type pbandk.MessageDescriptor for runtime reflection and schema inspection.
• Default Values: The library provides orDefault() extension functions (e.g., Person?.orDefault()) to safely handle nullable message instances by returning the defaultInstance if the receiver is null.

// Example of a generated message structure
@pbandk.Export
public data class Person(
    val name: String = "",
    val id: Int = 0,
    val email: String = "",
    val phones: List<tutorial.Person.PhoneNumber> = emptyList(),
    val lastUpdated: pbandk.wkt.Timestamp? = null,
    override val unknownFields: Map<Int, pbandk.UnknownField> = emptyMap()
) : pbandk.Message {
    override operator fun plus(other: pbandk.Message?): tutorial.Person = protoMergeImpl(other)
    override val descriptor: pbandk.MessageDescriptor<tutorial.Person> get() = Companion.descriptor
    // ...
    public companion object : pbandk.Message.Companion<tutorial.Person> {
        public val defaultInstance: tutorial.Person by lazy { tutorial.Person() }
        override fun decodeWith(u: pbandk.MessageDecoder): tutorial.Person = Person.decodeWithImpl(u)
        // ...
    }
}

Generated messages are immutable Kotlin data classes that extend pbandk.Message.

Serialization and Deserialization

• Binary: Use encodeToByteArray() on the instance and MessageName.Companion.decodeFromByteArray(byteArray) to deserialize.
• JSON: Use encodeToJsonString() and decodeFromJsonString() for Protobuf JSON encoding.
• Streams (JVM only): Use encodeToStream(outputStream) and decodeFromStream(inputStream).

Key Features

• Immutability: Messages are data classes, providing equals, hashCode, and toString automatically.
• Unknown Fields: An unknownFields map stores unrecognized fields. These are preserved and re-encoded during output. You can configure MessageDecoder to discard them if desired.
• Merge Semantics: The plus operator is defined for messages to follow protobuf merge semantics.
• Size: The protoSize field lazily calculates the message size.
• Bytes: bytes fields use a pbandk.ByteArr wrapper around ByteArray to ensure predictable behavior in Kotlin data classes.