Pbandk

https://github.com/streem/pbandk
Admin
Pbandk is a Kotlin Multiplatform code generator and runtime for Protocol Buffers that generates...
Tokens:13,619
Snippets:109
Trust Score:7.9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run Kotlin/JS App with Gradle

Source: https://github.com/streem/pbandk/blob/master/examples/browser-js/README.md

Command to build and run the Kotlin/JS application. This command bundles the project using webpack and starts a development web server.

```bash
path/to/gradle :app:jsRun
```

--------------------------------

### Install pbandk Generator Locally

Source: https://github.com/streem/pbandk/blob/master/README.md

Installs the generator to the local build directory for testing changes in external projects without publishing.

```bash
./gradlew :protoc-gen-pbandk:protoc-gen-pbandk-jvm:installDist
```

--------------------------------

### Run Kotlin/Wasm Application via Gradle

Source: https://github.com/streem/pbandk/blob/master/examples/browser-wasm/README.md

Command to build and launch the Kotlin/Wasm application using the Gradle build system. This triggers the webpack bundling process and starts a local development server.

```bash
path/to/gradle :app:wasmJsRun
```

--------------------------------

### Generate Kotlin Code with Local Plugin

Source: https://github.com/streem/pbandk/blob/master/README.md

Uses the locally installed protoc-gen-pbandk plugin to generate Kotlin files from proto definitions.

```bash
protoc \
    --plugin=protoc-gen-pbandk=/path/to/pbandk/protoc-gen-pbandk/jvm/build/install/protoc-gen-pbandk/bin/protoc-gen-pbandk \
    --pbandk_out=src/main/kotlin \
    src/main/proto/*.proto
```

--------------------------------

### Configure Pbandk in Gradle

Source: https://context7.com/streem/pbandk/llms.txt

Add the pbandk runtime and code generator dependencies to your build.gradle.kts file. This setup includes the protobuf-gradle-plugin for automated code generation during the build process.

```kotlin
repositories {
	mavenCentral()
	maven { url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/") }
}
dependencies {
	implementation("pro.streem.pbandk:pbandk-runtime:0.16.0")
	compileOnly("pro.streem.pbandk:protoc-gen-pbandk-lib:0.16.0")
}
plugins {
	id("com.google.protobuf") version "0.9.4"
}
protobuf {
	protoc {
		artifact = "com.google.protobuf:protoc:4.28.0"
	}
	plugins {
		create("pbandk") {
			artifact = "pro.streem.pbandk:protoc-gen-pbandk-jvm:0.16.0:jvm8@jar"
		}
	}
	generateProtoTasks {
		all().forEach { task ->
			task.builtins { remove("java") }
			task.plugins { create("pbandk") }
		}
	}
}
```

--------------------------------

### Access Message Descriptor and Reflection in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

This code snippet demonstrates how to access message metadata and field descriptors for reflection purposes in Kotlin using pbandk. It shows how to get the message descriptor, iterate over field descriptors, and retrieve field values using reflection.

```kotlin
import pbandk.ExperimentalProtoReflection
import pbandk.getFieldValue

@OptIn(ExperimentalProtoReflection::class)
fun inspectMessage(message: Person) {
    // Access message descriptor
    val descriptor = message.descriptor
    println("Full name: ${descriptor.fullName}")  // "tutorial.Person"
    println("Name: ${descriptor.name}")            // "Person"

    // Iterate over field descriptors
    descriptor.fields.forEach { field ->
        println("Field: ${field.name}, number: ${field.number}")
        val value = message.getFieldValue(field)
        println("  Value: $value")
    }
}

// Field descriptor properties
val personDescriptor = Person.descriptor
personDescriptor.fields.forEach { field ->
    println("${field.name}: ${field.jsonName}, #${field.number}")
}
```

--------------------------------

### Working with google.protobuf.Any - pack, isA, unpack

Source: https://context7.com/streem/pbandk/llms.txt

Utilities for packing, checking, and unpacking messages using the `google.protobuf.Any` type, allowing for arbitrary protobuf message wrapping.

```APIDOC
## Working with google.protobuf.Any - pack, isA, unpack

### Description
Use the Any type to wrap arbitrary protobuf messages.

### Method
`pack`, `isA`, `unpack`

### Endpoint
N/A (Library functions)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.wkt.Any
import pbandk.isA
import pbandk.pack
import pbandk.unpack

// Pack a message into Any
val person = Person(name = "John", id = 123)
val anyMessage: Any = Any.pack(person)
// typeUrl: "type.googleapis.com/tutorial.Person"

// Pack with custom type URL prefix
val customAny = Any.pack(person, typeUrlPrefix = "example.com/types")
// typeUrl: "example.com/types/tutorial.Person"

// Check the type
if (anyMessage.isA(Person)) {
    println("Contains a Person message")
}

// Unpack the message
val unpacked: Person = anyMessage.unpack(Person)
println(unpacked.name) // "John"

// Handle potential type mismatch
try {
    val wrongType = anyMessage.unpack(AddressBook)
} catch (e: InvalidProtocolBufferException) {
    println("Type mismatch: ${e.message}")
}
```

### Response
#### Success Response (200)
`pack`: `Any` message containing the packed protobuf message.
`isA`: Boolean indicating if the `Any` message contains the specified type.
`unpack`: The unpacked protobuf message.

#### Response Example
```kotlin
// Example unpacked Person object
val person: Person = ...
```
```

--------------------------------

### Manage google.protobuf.Any Types

Source: https://context7.com/streem/pbandk/llms.txt

Covers packing and unpacking arbitrary Protobuf messages into the Any wrapper, including type checking and custom type URL prefixes.

```kotlin
import pbandk.wkt.Any
import pbandk.isA
import pbandk.pack
import pbandk.unpack

val person = Person(name = "John", id = 123)
val anyMessage: Any = Any.pack(person)

if (anyMessage.isA(Person)) {
    val unpacked: Person = anyMessage.unpack(Person)
}
```

--------------------------------

### Build Conformance Test Runner

Source: https://github.com/streem/pbandk/blob/master/README.md

Clones and builds the official protobuf conformance test runner from source.

```bash
git clone -b v28.0 --depth 1 --recurse-submodules --shallow-submodules https://github.com/protocolbuffers/protobuf.git
cd protobuf
cmake -S . -B build -DCMAKE_CXX_STANDARD=14 -Dprotobuf_BUILD_CONFORMANCE=ON -Dprotobuf_BUILD_TESTS=OFF -Dprotobuf_BUILD_LIBUPB=OFF
cmake --build build --parallel=10
```

--------------------------------

### Run Conformance Tests

Source: https://github.com/streem/pbandk/blob/master/README.md

Executes the conformance test suite for specific platforms.

```bash
./conformance/test-conformance.sh jvm
./conformance/test-conformance.sh js
./conformance/test-conformance.sh wasmJs
./conformance/test-conformance.sh macos
```

--------------------------------

### Implementing Custom Service Generators

Source: https://context7.com/streem/pbandk/llms.txt

Shows how to implement the ServiceGenerator interface to create custom gRPC or RPC code generation logic, allowing for tailored service interfaces.

```kotlin
import pbandk.gen.ServiceGenerator

class MyServiceGenerator : ServiceGenerator {
    override fun generate(service: ServiceGenerator.Service): List<ServiceGenerator.Result> {
        val methods = service.methods.map { method ->
            val reqType = service.kotlinTypeMappings[method.inputType!!]!!
            val respType = service.kotlinTypeMappings[method.outputType!!]!!
            "suspend fun ${method.name}(request: $reqType): $respType"
        }
        val code = "interface ${service.name} { ${methods.joinToString("\n    ")} }"
        return listOf(ServiceGenerator.Result(code = code, otherFilePath = "${service.filePath.removeSuffix(".kt")}Service.kt"))
    }
}
```

--------------------------------

### Generate Code with Protoc on Windows

Source: https://github.com/streem/pbandk/blob/master/README.md

This snippet provides instructions for generating code with pbandk on Windows, where the self-executing jar is not directly supported. It involves building the generator locally and specifying its path explicitly.

```bash
./gradlew :protoc-gen-pbandk:protoc-gen-pbandk-jvm:installDist
```

```bash
protoc \
    --pbandk_out=src/main/kotlin \
    --plugin=protoc-gen-pbandk=/path/to/pbandk/protoc-gen-pbandk/jvm/build/install/protoc-gen-pbandk/bin/protoc-gen-pbandk.bat \
    sample.proto
```

--------------------------------

### Generate Code with Protoc and Pbandk

Source: https://github.com/streem/pbandk/blob/master/README.md

This snippet shows how to use the protoc compiler with the pbandk plugin to generate Kotlin code from a .proto file. It covers basic usage and options for specifying output directories and Kotlin packages.

```bash
protoc --pbandk_out=src/main/kotlin sample.proto
```

```bash
protoc --pbandk_out=kotlin_package=my.pkg:src/main/kotlin sample.proto
```

```bash
protoc --pbandk_out=kotlin_package_mapping="simple.package->new.package;foo.bar.*->my.foo.bar.*":src/main/kotlin sample.proto
```

```bash
protoc --pbandk_out=visibility=internal:src/main/kotlin sample.proto
```

--------------------------------

### Build Runtime Library

Source: https://github.com/streem/pbandk/blob/master/README.md

Compiles the pbandk runtime library for both JS and JVM platforms.

```bash
./gradlew :pbandk-runtime:assemble
```

--------------------------------

### Using Protobuf Well-Known Types in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

Demonstrates how to instantiate and use standard Protobuf well-known types like Timestamp, Duration, and wrapper types for nullable primitives within the pbandk library.

```kotlin
import pbandk.wkt.Timestamp
import pbandk.wkt.Duration
import pbandk.wkt.StringValue
import pbandk.wkt.Int32Value
import pbandk.wkt.BoolValue
import pbandk.wkt.Empty

val timestamp = Timestamp(seconds = 1609459200L, nanos = 500_000_000)
val duration = Duration(seconds = 3600L, nanos = 0)
val nullableString: StringValue? = StringValue(value = "hello")
val nullableInt: Int32Value? = Int32Value(value = 42)
val nullableBool: BoolValue? = BoolValue(value = true)
val empty = Empty()
val defaultTimestamp = Timestamp.defaultInstance
```

--------------------------------

### Define Protocol Buffer Schema

Source: https://github.com/streem/pbandk/blob/master/README.md

A sample addressbook.proto file defining a Person message with nested PhoneNumber messages, enums, and a timestamp field.

```protobuf
syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

message Person {
    string name = 1;
    int32 id = 2;
    string email = 3;

    enum PhoneType {
        MOBILE = 0;
        HOME = 1;
        WORK = 2;
    }

    message PhoneNumber {
        string number = 1;
        PhoneType type = 2;
    }

    repeated PhoneNumber phones = 4;

    google.protobuf.Timestamp last_updated = 5;
}

message AddressBook {
    repeated Person people = 1;
}
```

--------------------------------

### Implement Default Instance Extensions

Source: https://github.com/streem/pbandk/blob/master/README.md

Provides extension functions to safely retrieve default instances of generated message types. This pattern simplifies null-handling when working with optional Protocol Buffer fields.

```kotlin
@pbandk.Export
@pbandk.JsName("orDefaultForAddressBook")
public fun AddressBook?.orDefault(): tutorial.AddressBook = this ?: AddressBook.defaultInstance
```

--------------------------------

### Encode Protobuf Messages to JSON

Source: https://context7.com/streem/pbandk/llms.txt

Explains how to serialize Protobuf messages into JSON strings, including options for compact output, proto field naming, and including default values.

```kotlin
import pbandk.json.encodeToJsonString
import pbandk.json.JsonConfig

val person = Person(name = "John Doe", id = 123)
val json: String = person.encodeToJsonString()
val compactJson = person.encodeToJsonString(JsonConfig(compactOutput = true))
val protoNames = person.encodeToJsonString(JsonConfig(outputProtoFieldNames = true))
```

--------------------------------

### Define Protocol Buffer Message Models in Kotlin

Source: https://github.com/streem/pbandk/blob/master/README.md

Shows the implementation of generated data classes for Protocol Buffer messages. These classes include field descriptors, metadata for serialization, and companion objects for decoding.

```kotlin
public data class PhoneNumber(
    val number: String = "",
    val type: tutorial.Person.PhoneType = tutorial.Person.PhoneType.fromValue(0),
    override val unknownFields: Map<Int, pbandk.UnknownField> = emptyMap()
) : pbandk.Message {
    override val descriptor: MessageDescriptor<tutorial.Person.PhoneNumber> get() = Companion.descriptor
    public companion object : pbandk.Message.Companion<tutorial.Person.PhoneNumber> {
        override val descriptor: pbandk.MessageDescriptor<tutorial.Person.PhoneNumber> = pbandk.MessageDescriptor(
           fullName = "tutorial.Person.PhoneNumber",
           messageClass = tutorial.Person.PhoneNumber::class,
           messageCompanion = this,
           fields = buildList(2) {
                add(pbandk.FieldDescriptor(name = "number", number = 1, type = pbandk.FieldDescriptor.Type.Primitive.String(), value = tutorial.Person.PhoneNumber::number))
                add(pbandk.FieldDescriptor(name = "type", number = 2, type = pbandk.FieldDescriptor.Type.Enum(enumCompanion = tutorial.Person.PhoneType.Companion), value = tutorial.Person.PhoneNumber::type))
            }
        )
    }
}
```

--------------------------------

### Configure Gradle for PBandK Dependencies

Source: https://github.com/streem/pbandk/blob/master/CHANGELOG.md

Provides the configuration required to include the PBandK runtime and snapshot repositories in a Gradle Kotlin DSL build file.

```kotlin
repositories {
    mavenCentral()
    maven { url = uri("https://s01.oss.sonatype.org/content/repositories/snapshots/") }
}

dependencies {
    implementation("pro.streem.pbandk:pbandk-runtime:0.10.0")
}
```

--------------------------------

### Decode JSON Strings to Protobuf Messages

Source: https://context7.com/streem/pbandk/llms.txt

Demonstrates parsing JSON strings back into Protobuf objects, with support for lenient configurations like ignoring unknown fields.

```kotlin
import pbandk.json.decodeFromJsonString
import pbandk.json.JsonConfig

val json = "{\"name\": \"Jane Doe\", \"id\": 456}"
val person = Person.decodeFromJsonString(json)
val lenientConfig = JsonConfig(ignoreUnknownFieldsInInput = true)
val personLenient = Person.decodeFromJsonString(json, lenientConfig)
```

--------------------------------

### Decode Protobuf Messages from JVM Streams

Source: https://context7.com/streem/pbandk/llms.txt

Demonstrates how to decode Protobuf messages from a Java InputStream. Supports reading from files and streams with optional size constraints.

```kotlin
import pbandk.decodeFromStream
import java.io.FileInputStream

val person = FileInputStream("person.bin").use { stream ->
    Person.decodeFromStream(stream)
}

val stream: InputStream = /* data source */
val expectedSize = 1024
val message = Person.decodeFromStream(stream, expectedSize)
```

--------------------------------

### Service Code Generation

Source: https://github.com/streem/pbandk/blob/master/README.md

Information on generating code for Protobuf services using custom generators.

```APIDOC
## Services

### Description
Protobuf services can be handled using a custom service generator. Refer to the "Service Code Generation" section and the `custom-service-gen` example for more details.
```

--------------------------------

### Access Protobuf Field Values via Reflection

Source: https://github.com/streem/pbandk/blob/master/CHANGELOG.md

Shows how to use the new experimental reflection API to iterate over message fields and retrieve values dynamically using FieldDescriptor.

```kotlin
@OptIn(ExperimentalProtoReflection::class)
fun printFields(msg: Message) {
    msg.descriptor.fields.forEach { field ->
        val value = msg.getFieldValue(field)
        println("${field.name}: $value")
    }
}
```

--------------------------------

### Configure Service Code Generation with Pbandk

Source: https://github.com/streem/pbandk/blob/master/README.md

This snippet demonstrates how to configure pbandk for custom service code generation. It involves adding a compile-only dependency and using the `kotlin_service_gen` option with protoc to specify the generator JAR and implementation class.

```gradle
dependencies {
    compileOnly("pro.streem.pbandk:protoc-gen-pbandk-lib:0.16.1-SNAPSHOT")
}
```

```bash
protoc --pbandk_out=kotlin_service_gen=gen.jar|my.Generator,kotlin_package=my.pkg:src/main/kotlin some.proto
```

--------------------------------

### Decode Protobuf Messages from Java NIO ByteBuffer

Source: https://context7.com/streem/pbandk/llms.txt

Shows how to decode messages directly from a ByteBuffer, which is efficient for memory-mapped files or direct memory access.

```kotlin
import pbandk.decodeFromByteBuffer
import java.nio.ByteBuffer

val buffer: ByteBuffer = ByteBuffer.wrap(bytes)
val person = Person.decodeFromByteBuffer(buffer)

val directBuffer = ByteBuffer.allocateDirect(1024)
directBuffer.flip()
val message = Person.decodeFromByteBuffer(directBuffer)
```

--------------------------------

### Working with Oneof Fields in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

Illustrates how to work with oneof fields in Kotlin, allowing a message to have only one of several possible fields set. It shows creating messages with oneof values, accessing them via sealed classes, and using convenience properties for direct access.

```kotlin
// Proto definition:
// message Value {
//   oneof value {
//     bool boolean_value = 1;
//     int32 integer_value = 2;
//     string string_value = 3;
//   }
// }

// Create with oneof value
val intValue = Value(value = Value.Value.IntegerValue(42))
val strValue = Value(value = Value.Value.StringValue("hello"))
val boolValue = Value(value = Value.Value.BooleanValue(true))

// Access via sealed class
when (val v = intValue.value) {
    is Value.Value.IntegerValue -> println("Int: ${v.value}")
    is Value.Value.StringValue -> println("String: ${v.value}")
    is Value.Value.BooleanValue -> println("Bool: ${v.value}")
    null -> println("Not set")
}

// Access via convenience properties (null if different type is set)
println(intValue.integerValue)  // 42
println(intValue.stringValue)   // null
println(intValue.booleanValue)  // null
```

--------------------------------

### Generate Kotlin Code with protoc

Source: https://context7.com/streem/pbandk/llms.txt

Use the protoc compiler with the pbandk plugin to generate Kotlin data classes from .proto files. This supports various configuration options like custom packages, internal visibility, and debug logging.

```bash
protoc --pbandk_out=src/main/kotlin sample.proto
protoc --pbandk_out=kotlin_package=my.pkg:src/main/kotlin sample.proto
protoc --pbandk_out=kotlin_package_mapping="simple.package->new.package;foo.bar.*->my.foo.bar.*":src/main/kotlin sample.proto
protoc --pbandk_out=visibility=internal:src/main/kotlin sample.proto
protoc --pbandk_out=log=debug:src/main/kotlin sample.proto
protoc --pbandk_out=src/main/kotlin --plugin=protoc-gen-pbandk=/path/to/protoc-gen-pbandk/bin/protoc-gen-pbandk.bat sample.proto
```

--------------------------------

### Build pbandk Code Generator

Source: https://github.com/streem/pbandk/blob/master/README.md

Builds the protoc-gen-pbandk distribution using Gradle. This is required to generate Kotlin code from Protobuf definitions.

```bash
./gradlew :protoc-gen-pbandk:protoc-gen-pbandk-jvm:assembleDist
```

--------------------------------

### Handle Delimited Message Streams

Source: https://context7.com/streem/pbandk/llms.txt

Provides methods to read and write multiple Protobuf messages to a single stream using size prefixes, ensuring compatibility with standard Java protobuf libraries.

```kotlin
import pbandk.encodeDelimitedToStream
import pbandk.decodeDelimitedFromStream
import java.io.FileInputStream
import java.io.FileOutputStream

FileOutputStream("people.bin").use { stream ->
    val people = listOf(Person(name = "Alice", id = 1), Person(name = "Bob", id = 2))
    people.forEach { person -> person.encodeDelimitedToStream(stream) }
}

FileInputStream("people.bin").use { stream ->
    val people = mutableListOf<Person>()
    while (true) {
        val person = Person.decodeDelimitedFromStream(stream) ?: break
        people.add(person)
    }
}
```

--------------------------------

### Add Pbandk Runtime Library Dependency

Source: https://github.com/streem/pbandk/blob/master/README.md

This snippet shows how to add the pbandk runtime library as a dependency in a Gradle project. It includes configuring Maven repositories and specifying the implementation dependency.

```gradle
repositories {
    // This repository is only needed if using a SNAPSHOT version of pbandk
    maven {
        url "https://s01.oss.sonatype.org/content/repositories/snapshots/"
    }

    mavenCentral()
}

dependencies {
    // Can be used from the `common` sourceset in a Kotlin Multiplatform project,
    // or from platform-specific JVM, Android, JS, or Native sourcesets/projects.
    implementation("pro.streem.pbandk:pbandk-runtime:0.16.1-SNAPSHOT")
}
```

--------------------------------

### Decode Protobuf Message from Stream with Size Limit

Source: https://github.com/streem/pbandk/blob/master/CHANGELOG.md

Demonstrates how to use the updated decodeFromStream method to read a message from an InputStream with an optional expectedSize parameter. This is useful for parsing multiple messages from a single stream.

```kotlin
val message = MyMessage.decodeFromStream(inputStream, expectedSize = 1024)
```

--------------------------------

### Message Encoding and Decoding

Source: https://github.com/streem/pbandk/blob/master/README.md

Details on encoding Protobuf messages to byte arrays and decoding them back, along with platform-specific methods and JSON support.

```APIDOC
## Message Encoding and Decoding

### Description
Each Protobuf message extends `pbandk.Message` and provides methods for encoding and decoding.

### Methods
- `encodeToByteArray()`: Encodes the message to a `ByteArray` using Protobuf binary encoding.
- `decodeFromByteArray(byteArray)`: Decodes a `ByteArray` into a message instance.
- `encodeToJsonString()`: Encodes the message to a JSON string using Protobuf JSON encoding.
- `decodeFromJsonString(jsonString)`: Decodes a JSON string into a message instance.

Platform-specific methods like `encodeToStream` and `decodeFromStream` are also available (e.g., on JVM).

### Message Properties
- `unknownFields`: A map containing unrecognized fields encountered during decoding. These are re-encoded on output unless discarded by the `MessageDecoder`.
- `protoSize`: Lazily calculates the size of the message in bytes.
- `plus` operator: Implements Protobuf merge semantics for messages.
```

--------------------------------

### Well-Known Types

Source: https://github.com/streem/pbandk/blob/master/README.md

Explanation of pbandk's support for Protobuf well-known types, including wrappers.

```APIDOC
## Well-Known Types

### Description
Protobuf well-known types (from `google/protobuf`) are available under the `pbandk.wkt` package.

Specialized support exists for `google/protobuf/wrappers.proto`. These map to nullable Kotlin primitives (e.g., `String?` for `StringValue`, `Int?` for `Int32Value`).
```

--------------------------------

### Combine Messages using '+' Operator in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

Demonstrates how to merge two messages using protobuf merge semantics via the '+' operator in Kotlin. The second message's values override the first message's values where conflicts occur. It also shows handling of nullable messages.

```kotlin
import pbandk.plus

// Merge two messages - second message's values override first
val base = Person(name = "Base", id = 1, email = "base@example.com")
val updates = Person(name = "Updated", phones = listOf(Person.PhoneNumber(number = "555-1234")))

val merged: Person = base + updates
// merged.name = "Updated" (overwritten)
// merged.id = 1 (kept from base)
// merged.email = "base@example.com" (kept from base)
// merged.phones = [PhoneNumber(555-1234)] (from updates)

// Merge with nullable
val nullMessage: Person? = null
val result: Person? = base + nullMessage // returns base
val result2: Person? = nullMessage + base // returns base
```

--------------------------------

### Repeated and Map Fields

Source: https://github.com/streem/pbandk/blob/master/README.md

Information on how repeated and map fields are represented using standard Kotlin collections.

```APIDOC
## Repeated and Map Fields

### Description
- `repeated` fields are represented as standard Kotlin `List`s. The specific list implementation should not be assumed.
- `map` fields are represented as Kotlin `Map`s. In proto2, both keys and values in maps are considered nullable due to serialization specifics.
```

--------------------------------

### Regenerate Well-Known Types

Source: https://github.com/streem/pbandk/blob/master/README.md

Regenerates well-known proto types using the updated pbandk binary.

```bash
./gradlew generateProtos
```

--------------------------------

### Binary Encoding - encodeToByteArray

Source: https://context7.com/streem/pbandk/llms.txt

Encodes a protobuf message instance into a binary byte array.

```APIDOC
## POST /pbandk/encodeToByteArray

### Description
Serializes a Kotlin data class generated by Pbandk into a binary protobuf byte array.

### Method
POST

### Endpoint
/pbandk/encodeToByteArray

### Parameters
#### Request Body
- **message** (Object) - Required - The protobuf message instance to encode.

### Request Example
{
  "id": 1234,
  "name": "John Doe",
  "email": "john@example.com"
}

### Response
#### Success Response (200)
- **bytes** (ByteArray) - The serialized binary data.

#### Response Example
[0x0A, 0x08, 0x4A, 0x6F, 0x68, 0x6E, 0x20, 0x44, 0x6F, 0x65]
```

--------------------------------

### Encode Protobuf Messages to JVM Stream

Source: https://context7.com/streem/pbandk/llms.txt

Directly write a protobuf message to a Java OutputStream, which is useful for file I/O or network communication in JVM and Android environments.

```kotlin
import pbandk.encodeToStream
import java.io.FileOutputStream
val person = Person(name = "Jane", id = 5678)
FileOutputStream("person.bin").use { stream ->
	val bytesWritten: Int = person.encodeToStream(stream)
	println("Wrote $bytesWritten bytes")
}
```

--------------------------------

### Delimited Message Streams - encodeDelimitedToStream / decodeDelimitedFromStream

Source: https://context7.com/streem/pbandk/llms.txt

Write and read multiple protobuf messages to/from a single stream. Each message is prefixed with its size, ensuring compatibility with other protobuf implementations.

```APIDOC
## Delimited Message Streams - encodeDelimitedToStream / decodeDelimitedFromStream

### Description
Write and read multiple messages to/from a stream with size prefixes (compatible with Java protobuf library).

### Method
`encodeDelimitedToStream`, `decodeDelimitedFromStream`

### Endpoint
N/A (Library functions)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.encodeDelimitedToStream
import pbandk.decodeDelimitedFromStream
import java.io.FileInputStream
import java.io.FileOutputStream

// Write multiple messages to a stream
FileOutputStream("people.bin").use {
    val people = listOf(
        Person(name = "Alice", id = 1),
        Person(name = "Bob", id = 2),
        Person(name = "Charlie", id = 3)
    )
    people.forEach { person ->
        person.encodeDelimitedToStream(it)
    }
}

// Read all messages from the stream
FileInputStream("people.bin").use {
    val people = mutableListOf<Person>()
    while (true) {
        val person = Person.decodeDelimitedFromStream(it) ?: break
        people.add(person)
    }
    println("Read ${people.size} people")
}
```

### Response
#### Success Response (200)
`encodeDelimitedToStream`: Void (writes to stream).
`decodeDelimitedFromStream`: Decoded protobuf message or null if end of stream is reached.

#### Response Example
```kotlin
// Example Person object read from stream
val person: Person = ...
```
```

--------------------------------

### Working with Enums in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

This section explains how to access enum values by their integer representation or name, and how to handle unrecognized enum values in Kotlin. It covers retrieving enum objects from integers and strings, and iterating through all defined enum values.

```kotlin
// Enum values are sealed classes with known objects
val phoneType: Person.PhoneType = Person.PhoneType.MOBILE
println(phoneType.value) // 0
println(phoneType.name)  // "MOBILE"

// Get enum from integer value
val fromInt = Person.PhoneType.fromValue(1) // HOME
val unknown = Person.PhoneType.fromValue(999) // UNRECOGNIZED(999)

// Get enum from string name
val fromName = Person.PhoneType.fromName("WORK") // WORK

// Handle unknown enum values
when (val type = Person.PhoneType.fromValue(receivedValue)) {
    Person.PhoneType.MOBILE -> handleMobile()
    Person.PhoneType.HOME -> handleHome()
    Person.PhoneType.WORK -> handleWork()
    is Person.PhoneType.UNRECOGNIZED -> handleUnknown(type.value)
}

// Access all known values
val allTypes: List<Person.PhoneType> = Person.PhoneType.values
```

--------------------------------

### Configure TypeRegistry for JSON Any Fields in Kotlin

Source: https://context7.com/streem/pbandk/llms.txt

This snippet shows how to configure a TypeRegistry for JSON encoding and decoding of messages that contain Any fields. It involves building a registry with message types, creating a JsonConfig with this registry, and then encoding/decoding messages with Any fields.

```kotlin
import pbandk.typeRegistry
import pbandk.json.JsonConfig
import pbandk.json.encodeToJsonString
import pbandk.json.decodeFromJsonString

// Build a type registry with message types
val registry = typeRegistry {
    add(Person)
    add(AddressBook)
    add(CustomMessage)
}

// Create JSON config with type registry
val jsonConfig = JsonConfig(typeRegistry = registry)

// Encode message with Any field to JSON
val wrapper = MessageWithAnyField(
    payload = Any.pack(Person(name = "Test", id = 1))
)
val json = wrapper.encodeToJsonString(jsonConfig)
// JSON Any is encoded with @type field

// Decode JSON with Any field
val decoded = MessageWithAnyField.decodeFromJsonString(json, jsonConfig)
val person = decoded.payload?.unpack(Person)
```

--------------------------------

### Decode Protobuf Messages from Byte Array

Source: https://context7.com/streem/pbandk/llms.txt

Deserialize a binary byte array back into a Kotlin data class instance using the companion object's decodeFromByteArray method. This allows access to fields and iteration over repeated fields.

```kotlin
import pbandk.decodeFromByteArray
val bytes: ByteArray = /* received bytes */
val person = Person.decodeFromByteArray(bytes)
println("Name: ${person.name}")
person.phones.forEach { phone ->
	when (phone.type) {
		Person.PhoneType.MOBILE -> println("Mobile: ${phone.number}")
		Person.PhoneType.HOME -> println("Home: ${phone.number}")
		else -> println("Other: ${phone.number}")
	}
}
```

--------------------------------

### Accessing Extension Fields

Source: https://context7.com/streem/pbandk/llms.txt

Explains how to access extension fields on extendable messages using the pbandk library, including lazy decoding from unknown fields.

```kotlin
import pbandk.ExtendableMessage
import pbandk.FieldDescriptor

@OptIn(pbandk.ExperimentalProtoReflection::class)
fun <T : ExtendableMessage> T.getCustomField(): String? {
    return getExtension(customFieldDescriptor)
}

val message = MyMessage.decodeFromByteArray(bytes)
val customValue = message.getCustomField()
```

--------------------------------

### Binary Decoding - decodeFromByteArray

Source: https://context7.com/streem/pbandk/llms.txt

Deserializes a binary byte array back into a specific protobuf message instance.

```APIDOC
## POST /pbandk/decodeFromByteArray

### Description
Parses a binary byte array into a strongly-typed Kotlin object using the message companion object.

### Method
POST

### Endpoint
/pbandk/decodeFromByteArray

### Parameters
#### Request Body
- **bytes** (ByteArray) - Required - The binary protobuf data to decode.

### Request Example
{
  "bytes": [0x0A, 0x08, 0x4A, 0x6F, 0x68, 0x6E, 0x20, 0x44, 0x6F, 0x65]
}

### Response
#### Success Response (200)
- **message** (Object) - The deserialized Kotlin data class instance.

#### Response Example
{
  "name": "John Doe",
  "id": 1234
}
```

--------------------------------

### JSON Decoding - decodeFromJsonString

Source: https://context7.com/streem/pbandk/llms.txt

Decode a JSON string back into a protobuf message. Supports configuration for lenient parsing, such as ignoring unknown fields.

```APIDOC
## JSON Decoding - decodeFromJsonString

### Description
Decode a JSON string back into a protobuf message.

### Method
`decodeFromJsonString`

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.json.decodeFromJsonString
import pbandk.json.JsonConfig

val json = """
{
  "name": "Jane Doe",
  "id": 456,
  "email": "jane@example.com",
  "phones": [
    {"number": "555-9999", "type": "WORK"}
  ]
}
"""

// Decode from JSON
val person = Person.decodeFromJsonString(json)

// Ignore unknown fields in input
val lenientConfig = JsonConfig(ignoreUnknownFieldsInInput = true)
val personLenient = Person.decodeFromJsonString(jsonWithExtraFields, lenientConfig)
```

### Response
#### Success Response (200)
Decoded protobuf message.

#### Response Example
```kotlin
// Example Person object
val person: Person = ...
```
```

--------------------------------

### Encode Protobuf Messages to Byte Array

Source: https://context7.com/streem/pbandk/llms.txt

Convert a generated Kotlin data class instance into a binary byte array using the encodeToByteArray extension function. You can also calculate the encoded size without performing the full serialization.

```kotlin
import pbandk.encodeToByteArray
val person = Person(
	id = 1234,
	name = "John Doe",
	email = "john@example.com",
	phones = listOf(
		Person.PhoneNumber(number = "555-1234", type = Person.PhoneType.MOBILE),
		Person.PhoneNumber(number = "555-5678", type = Person.PhoneType.HOME)
	)
)
val bytes: ByteArray = person.encodeToByteArray()
val size: Int = person.protoSize
```

--------------------------------

### Generate Kotlin Data Class from Proto

Source: https://github.com/streem/pbandk/blob/master/README.md

The resulting Kotlin code generated by pbandk, implementing the Person data class with pbandk.Message interfaces and field descriptors.

```kotlin
@file:OptIn(pbandk.PublicForGeneratedCode::class)

package tutorial

@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
    override val protoSize: Int by lazy { super.protoSize }
    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 = tutorial.Person.decodeWithImpl(u)

        override val descriptors: pbandk.MessageDescriptor<tutorial.Person> = pbandk.MessageDescriptor(
            fullName = "tutorial.Person",
            messageClass = tutorial.Person::class,
            messageCompanion = this,
            fields = buildList(5) {
                add(pbandk.FieldDescriptor(messageDescriptor = this@Companion::descriptor, name = "name", number = 1, type = pbandk.FieldDescriptor.Type.Primitive.String(), jsonName = "name", value = tutorial.Person::name))
                add(pbandk.FieldDescriptor(messageDescriptor = this@Companion::descriptor, name = "id", number = 2, type = pbandk.FieldDescriptor.Type.Primitive.Int32(), jsonName = "id", value = tutorial.Person::id))
                add(pbandk.FieldDescriptor(messageDescriptor = this@Companion::descriptor, name = "email", number = 3, type = pbandk.FieldDescriptor.Type.Primitive.String(), jsonName = "email", value = tutorial.Person::email))
                add(pbandk.FieldDescriptor(messageDescriptor = this@Companion::descriptor, name = "phones", number = 4, type = pbandk.FieldDescriptor.Type.Repeated<tutorial.Person.PhoneNumber>(valueType = pbandk.FieldDescriptor.Type.Message(messageCompanion = tutorial.Person.PhoneNumber.Companion)), jsonName = "phones", value = tutorial.Person::phones))
                add(pbandk.FieldDescriptor(messageDescriptor = this@Companion::descriptor, name = "last_updated", number = 5, type = pbandk.FieldDescriptor.Type.Message(messageCompanion = pbandk.wkt.Timestamp.Companion), jsonName = "lastUpdated", value = tutorial.Person::lastUpdated))
            }
        )
    }

    public sealed class PhoneType(override val value: Int, override val name: String? = null) : pbandk.Message.Enum {
        override fun equals(other: kotlin.Any?): Boolean = other is tutorial.Person.PhoneType && other.value == value
        override fun hashCode(): Int = value.hashCode()
        override fun toString(): String = "Person.PhoneType.${name ?: "UNRECOGNIZED"}(value=$value)"

        public object MOBILE : PhoneType(0, "MOBILE")
        public object HOME : PhoneType(1, "HOME")
        public object WORK : PhoneType(2, "WORK")
        public class UNRECOGNIZED(value: Int) : PhoneType(value)

        public companion object : pbandk.Message.Enum.Companion<tutorial.Person.PhoneType> {
            override fun fromValue(value: Int): tutorial.Person.PhoneType = when(value) {
                0 -> MOBILE
                1 -> HOME
                2 -> WORK
                else -> UNRECOGNIZED(value)
            }
        }
    }
}
```

--------------------------------

### Enum Fields

Source: https://github.com/streem/pbandk/blob/master/README.md

Details on how Protobuf enums are generated as sealed classes in pbandk to handle open-ended values.

```APIDOC
## Enum Fields

### Description
Enum fields are generated as sealed classes. Each known enum value is a nested `object`, and unknown values are represented by an `Unrecognized` nested class.

This approach handles Protobuf's open-ended enums effectively. Each enum object contains `value` (numeric) and `name` (string) fields.

### Companion Object Methods
- `fromValue(value)`: Maps a numeric value to the corresponding enum object.
- `fromName(name)`: Maps a string name to the corresponding enum object.
- `values`: A list of all known enum values.
```

--------------------------------

### JVM Stream Decoding - decodeFromStream

Source: https://context7.com/streem/pbandk/llms.txt

Decode a protobuf message from a Java InputStream. Supports an optional size limit for reading specific portions of a stream.

```APIDOC
## JVM Stream Decoding - decodeFromStream

### Description
Decode a message from a Java InputStream with optional size limit (JVM/Android only).

### Method
`decodeFromStream`

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.decodeFromStream
import java.io.FileInputStream

// Read from file
val person = FileInputStream("person.bin").use {
    Person.decodeFromStream(it)
}

// Read with expected size
val stream: InputStream = /* data source */
val expectedSize = 1024
val message = Person.decodeFromStream(stream, expectedSize)
```

### Response
#### Success Response (200)
Decoded protobuf message.

#### Response Example
```kotlin
// Example Person object
val person: Person = ...
```
```

--------------------------------

### Oneof Fields

Source: https://github.com/streem/pbandk/blob/master/README.md

Explanation of how oneof fields are represented in pbandk, using sealed classes and wrapper classes.

```APIDOC
## Oneof Fields

### Description
Oneof fields are generated as nested classes within a common sealed base class. Each specific field within the oneof is a class that wraps its value.

The parent message includes nullable fields corresponding to each oneof inner field. These fields resolve to the wrapped value if the oneof is set to that specific field, otherwise they are null.
```

--------------------------------

### JVM Stream Encoding - encodeToStream

Source: https://context7.com/streem/pbandk/llms.txt

Writes a protobuf message directly to a Java OutputStream.

```APIDOC
## POST /pbandk/encodeToStream

### Description
Encodes a message directly to an output stream, useful for file I/O or network sockets on JVM/Android.

### Method
POST

### Endpoint
/pbandk/encodeToStream

### Parameters
#### Request Body
- **message** (Object) - Required - The message to encode.
- **stream** (OutputStream) - Required - The target output stream.

### Response
#### Success Response (200)
- **bytesWritten** (Int) - The number of bytes successfully written to the stream.
```

--------------------------------

### JVM ByteBuffer Decoding - decodeFromByteBuffer

Source: https://context7.com/streem/pbandk/llms.txt

Decode a protobuf message directly from a Java NIO ByteBuffer. This is efficient for data already in memory or memory-mapped files.

```APIDOC
## JVM ByteBuffer Decoding - decodeFromByteBuffer

### Description
Decode a message from a Java NIO ByteBuffer (JVM/Android only).

### Method
`decodeFromByteBuffer`

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.decodeFromByteBuffer
import java.nio.ByteBuffer

// Decode from ByteBuffer (reads from position to limit)
val buffer: ByteBuffer = ByteBuffer.wrap(bytes)
val person = Person.decodeFromByteBuffer(buffer)

// Useful for memory-mapped files or direct buffers
val directBuffer = ByteBuffer.allocateDirect(1024)
// ... fill buffer with protobuf data ...
directBuffer.flip()
val message = Person.decodeFromByteBuffer(directBuffer)
```

### Response
#### Success Response (200)
Decoded protobuf message.

#### Response Example
```kotlin
// Example Person object
val person: Person = ...
```
```

--------------------------------

### JSON Encoding - encodeToJsonString

Source: https://context7.com/streem/pbandk/llms.txt

Encode a protobuf message into a JSON string, adhering to the proto3 JSON specification. Supports configuration for formatting and field output.

```APIDOC
## JSON Encoding - encodeToJsonString

### Description
Encode a message to JSON format following the proto3 JSON specification.

### Method
`encodeToJsonString`

### Endpoint
N/A (Library function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```kotlin
import pbandk.json.encodeToJsonString
import pbandk.json.JsonConfig

val person = Person(
    name = "John Doe",
    id = 123,
    phones = listOf(Person.PhoneNumber(number = "555-1234", type = Person.PhoneType.MOBILE))
)

// Default JSON output (formatted)
val json: String = person.encodeToJsonString()
// {
//   "name": "John Doe",
//   "id": 123,
//   "phones": [{"number": "555-1234", "type": "MOBILE"}]
// }

// Compact JSON output
val compactJson = person.encodeToJsonString(JsonConfig(compactOutput = true))
// {"name":"John Doe","id":123,"phones":[{"number":"555-1234","type":"MOBILE"}]}

// Use proto field names instead of camelCase
val protoNames = person.encodeToJsonString(JsonConfig(outputProtoFieldNames = true))

// Output fields with default values
val withDefaults = person.encodeToJsonString(JsonConfig(outputDefaultValues = true))
```

### Response
#### Success Response (200)
JSON string representation of the protobuf message.

#### Response Example
```json
{
  "name": "John Doe",
  "id": 123,
  "phones": [
    {
      "number": "555-1234",
      "type": "MOBILE"
    }
  ]
}
```
```
Tokens:
Raw