Arri Kotlin Codegen

Setup

1) Add the generator to your arri config

// arri.config.ts
import { defineConfig, generators } from 'arri';

export default defineConfig({
    generators: [
        generators.kotlinClient({
            clientName: 'MyClient',
            outputFile: './client/src/MyClient.g.kt',
        }),
    ],
});

Options:

2) Install dependencies

The generated code relies on the following dependencies:

• kotlinx.serialization
• ktor client

Using the Generated Code

Initialize the client

fun main() {
    // create a Ktor HTTP client
    val httpClient = HttpClient() {
        install(HttpTimeout)
    }
    // initialize your generated client and pass it the httpClient
    // the client name will match whatever options you passed into your arri config
    val client = MyClient(
        httpClient = httpClient,
        baseUrl = "https://example.com",
        // a function that returns a mutable map of headers
        // this function will run before every request. Or before every reconnection in the case of SSE
        headers = {
            mutableMapOf(Pair("x-example-header", "<some-header-value>"))
        }
    )
    runBlocking {
        client.someProcedure()
    }
}

The root client will be a class containing all of the services and procedures in a single class. If you only need a particular service, you can initialize just that service.

val service = MyClientUsersService(
        httpClient = httpClient,
        baseUrl = "https://example.com",
        headers = {
            mutableMapOf(Pair("x-example-header", "<some-header-value>"))
        }
    )

Client / Service Options

Calling Procedures

Standard HTTP Procedures

runBlocking {
    // procedure with no parameters
    val getUsersResponse = myClient.users.getUsers()

    // procedure with parameters
    val getUserResponse = myClient.users.getUser(GetUserParams(userId = "12345"))
}

Event Stream Procedures

Basic Usage

runBlocking {
    myClient.users.watchUserChanges(
        onData { message ->
            println("New message: ${message}")
        },
        onOpen {
            println("Connection established")
        }
        onRequestError { err ->
            println("Error connecting to server: ${err}")
        },
        onResponseError { err ->
            println("Server returned an error: ${err.code} ${err.message}")
        },
        onClose {
            println("Connection closed")
        }
    )
}

Cancelling Requests

Event stream procedures can be cancelled from inside one of the hooks by throwing a CancellationException

runBlocking {
    myClient.users.watchUserChanges(
        onResponseError { err ->
            println("Server returned an error: ${err.code} ${err.message}")
            throw CancellationException()
        }
    )
}

You can also spawn a job and cancel that job in order to cancel the Event stream procedure from the outside

val job = someCoroutineScope.launch {
    myClient.users.watchUserChanges()
}
job.cancel()

Other Options

Using Arri Models

All generated models will be data classes. They will have access to the following features:

Methods:

• toJson(): String
• toUrlQueryParams(): String

Factory Methods:

• new()
• fromJson(input: String)
• fromJsonElement(input: JsonElement, instancePath: String)

Other Notes

• All Enums will have a serialValue property.
• Discriminator schemas are converted to sealed classes

Development

# build the library
pnpm nx build codegen-kotlin

# test
pnpm nx test codegen-kotlin

# lint
pnpm nx lint codegen-lint