@arrirpc/codegen-kotlin 0.49.1 → 0.51.0

package/README.md

@@ -1,11 +1,106 @@
-# arri-codegen-kotlin
+# Arri Kotlin Codegen
 
-This library was generated with [Nx](https://nx.dev).
+## Setup
 
-## Building
+### 1) Add the generator to your arri config
 
-Run `nx build arri-codegen-kotlin` to build the library.
+```ts
+// arri.config.ts
+import { defineConfig, generators } from "arri";
 
-## Running unit tests
+export default defineConfig({
+    generators: [
+        generators.kotlinClient({
+            clientName: "MyClient",
+            outputFile: "./client/src/MyClient.g.kt",
+        }),
+    ],
+});
+```
 
-Run `nx test arri-codegen-kotlin` to execute the unit tests via [Vitest](https://vitest.dev).
+**Options:**
+
+| Name                  | Description                                                   |
+| --------------------- | ------------------------------------------------------------- |
+| clientName            | The name of the generated client class (Defaults to "Client") |
+| outputFile (required) | Path to the file that will be created by the generator        |
+| modelPrefix           | Add a prefix to the generated class names                     |
+
+### 2) Install dependencies
+
+The generated code relies on the following dependencies:
+
+-   [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization)
+-   [ktor client](https://ktor.io/docs/client-dependencies.html)
+
+## Using the Generated Code
+
+### Initialize the client
+
+```kotlin
+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.
+
+```kotlin
+val service = MyClientUsersService(
+        httpClient = httpClient,
+        baseUrl = "https://example.com",
+        headers = {
+            mutableMapOf(Pair("x-example-header", "<some-header-value>"))
+        }
+    )
+```
+
+### 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
+
+```bash
+# build the library
+pnpm nx build codegen-kotlin
+
+# test
+pnpm nx test codegen-kotlin
+
+# lint
+pnpm nx lint codegen-lint
+```

package/dist/index.cjs

@@ -152,7 +152,7 @@ function kotlinArrayFromSchema(schema, context) {
     modelPrefix: context.modelPrefix,
     clientName: context.clientName,
     clientVersion: context.clientVersion,
-    instancePath: `${context.instancePath}/[element]`,
+    instancePath: `${context.instancePath}/[Element]`,
     schemaPath: `${context.schemaPath}/elements`,
     existingTypeIds: context.existingTypeIds
   });
@@ -1254,7 +1254,7 @@ function kotlinRefFromSchema(schema, context) {
   };
 }
 
-const kotlinClientGenerator = codegenUtils.defineClientGeneratorPlugin(
+const kotlinClientGenerator = codegenUtils.defineGeneratorPlugin(
   (options) => {
     return {
       generator(def) {

package/dist/index.d.cts

@@ -33,7 +33,7 @@ interface KotlinClientOptions {
     modelPrefix?: string;
     outputFile: string;
 }
-declare const kotlinClientGenerator: _arrirpc_codegen_utils.ClientGeneratorPlugin<KotlinClientOptions>;
+declare const kotlinClientGenerator: _arrirpc_codegen_utils.GeneratorPlugin<KotlinClientOptions>;
 declare function kotlinClientFromAppDefinition(def: AppDefinition, options: KotlinClientOptions): string;
 declare function kotlinTypeFromSchema(schema: Schema, context: CodegenContext): KotlinProperty;
 

package/dist/index.d.mts

@@ -33,7 +33,7 @@ interface KotlinClientOptions {
     modelPrefix?: string;
     outputFile: string;
 }
-declare const kotlinClientGenerator: _arrirpc_codegen_utils.ClientGeneratorPlugin<KotlinClientOptions>;
+declare const kotlinClientGenerator: _arrirpc_codegen_utils.GeneratorPlugin<KotlinClientOptions>;
 declare function kotlinClientFromAppDefinition(def: AppDefinition, options: KotlinClientOptions): string;
 declare function kotlinTypeFromSchema(schema: Schema, context: CodegenContext): KotlinProperty;
 

package/dist/index.d.ts

@@ -33,7 +33,7 @@ interface KotlinClientOptions {
     modelPrefix?: string;
     outputFile: string;
 }
-declare const kotlinClientGenerator: _arrirpc_codegen_utils.ClientGeneratorPlugin<KotlinClientOptions>;
+declare const kotlinClientGenerator: _arrirpc_codegen_utils.GeneratorPlugin<KotlinClientOptions>;
 declare function kotlinClientFromAppDefinition(def: AppDefinition, options: KotlinClientOptions): string;
 declare function kotlinTypeFromSchema(schema: Schema, context: CodegenContext): KotlinProperty;
 

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { removeDisallowedChars, camelCase, stringStartsWithNumber, pascalCase, isServiceDefinition, isRpcDefinition, defineClientGeneratorPlugin, unflattenProcedures, isSchemaFormType, isSchemaFormEnum, isSchemaFormProperties, isSchemaFormElements, isSchemaFormValues, isSchemaFormDiscriminator, isSchemaFormRef } from '@arrirpc/codegen-utils';
+import { removeDisallowedChars, camelCase, stringStartsWithNumber, pascalCase, isServiceDefinition, isRpcDefinition, defineGeneratorPlugin, unflattenProcedures, isSchemaFormType, isSchemaFormEnum, isSchemaFormProperties, isSchemaFormElements, isSchemaFormValues, isSchemaFormDiscriminator, isSchemaFormRef } from '@arrirpc/codegen-utils';
 
 const reservedIdentifierKeywords = [
   "as",
@@ -146,7 +146,7 @@ function kotlinArrayFromSchema(schema, context) {
     modelPrefix: context.modelPrefix,
     clientName: context.clientName,
     clientVersion: context.clientVersion,
-    instancePath: `${context.instancePath}/[element]`,
+    instancePath: `${context.instancePath}/[Element]`,
     schemaPath: `${context.schemaPath}/elements`,
     existingTypeIds: context.existingTypeIds
   });
@@ -1248,7 +1248,7 @@ function kotlinRefFromSchema(schema, context) {
   };
 }
 
-const kotlinClientGenerator = defineClientGeneratorPlugin(
+const kotlinClientGenerator = defineGeneratorPlugin(
   (options) => {
     return {
       generator(def) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrirpc/codegen-kotlin",
-  "version": "0.49.1",
+  "version": "0.51.0",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -22,8 +22,8 @@
     "dist"
   ],
   "dependencies": {
-    "@arrirpc/schema": "0.49.1",
-    "json-schema-to-jtd": "0.49.1",
-    "@arrirpc/codegen-utils": "0.49.1"
+    "@arrirpc/schema": "0.51.0",
+    "@arrirpc/codegen-utils": "0.51.0",
+    "json-schema-to-jtd": "0.51.0"
   }
 }