{"id":13428748,"url":"https://github.com/ansman/kotshi","last_synced_at":"2025-05-14T20:06:18.258Z","repository":{"id":22259866,"uuid":"95685398","full_name":"ansman/kotshi","owner":"ansman","description":"An annotation processor that generates Moshi adapters from immutable Kotlin data classes.","archived":false,"fork":false,"pushed_at":"2025-04-09T13:24:43.000Z","size":1405,"stargazers_count":763,"open_issues_count":5,"forks_count":42,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-13T14:06:42.797Z","etag":null,"topics":["annotation-processor","annotations","data-class","kotlin","moshi"],"latest_commit_sha":null,"homepage":"https://kotshi.ansman.se","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ansman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-28T15:39:00.000Z","updated_at":"2025-04-06T01:15:52.000Z","dependencies_parsed_at":"2023-12-07T15:27:00.350Z","dependency_job_id":"19bff9e1-9883-452e-b275-c2f4ffcb8767","html_url":"https://github.com/ansman/kotshi","commit_stats":null,"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansman%2Fkotshi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansman%2Fkotshi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansman%2Fkotshi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ansman%2Fkotshi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ansman","download_url":"https://codeload.github.com/ansman/kotshi/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724639,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation-processor","annotations","data-class","kotlin","moshi"],"created_at":"2024-07-31T01:01:04.128Z","updated_at":"2025-05-14T20:06:18.251Z","avatar_url":"https://github.com/ansman.png","language":"Kotlin","funding_links":[],"categories":["Kotlin","Libraries"],"sub_categories":[],"readme":"# Kotshi [![Build Gradle](https://github.com/ansman/kotshi/actions/workflows/gradle.yml/badge.svg)](https://github.com/ansman/kotshi/actions/workflows/gradle.yml) [![Maven Central](https://img.shields.io/maven-central/v/se.ansman.kotshi/api.svg)](https://central.sonatype.com/search?namespace=se.ansman.kotshi)\nAn annotation processor that generates [Moshi](https://github.com/square/moshi) adapters from Kotlin classes.\n\nThere is a reflective adapter for Kotlin but that requires the kotlin reflection library which adds a lot of methods and\nincreases the binary size which in a constrained environment such as Android is not preferable.\n\nThis is where Kotshi comes in, it generates fast and optimized adapters for your Kotlin data classes, just as if you'd\nwritten them by hand yourself. It will automatically regenerate the adapters when you modify your class.\n\nIt's made to work with minimal setup, through there are [limitations](#limitations).\nMost of the limitations will be addressed as the support for Kotlin annotation processors improves.\n\nYou can find the generated documentation by visiting [kotshi.ansman.se](https://kotshi.ansman.se/).\n\n## Usage\nFirst you must annotate your types with the `@JsonSerializable` annotation\n\u003cdetails open\u003e\n  \u003csummary\u003eAnnotated class\u003c/summary\u003e\n\n  ```kotlin\n  @JsonSerializable\n  data class Person(\n      val name: String,\n      val email: String?,\n      val hasVerifiedAccount: Boolean,\n      // This property has a different name in the Json than here so @JsonProperty must be applied.\n      @JsonProperty(name = \"created_at\")\n      val signUpDate: Date,\n      // This field has a default value which will be used if the field is missing.\n      val jobTitle: String? = null\n  )\n  ```\n\u003c/details\u003e\n\nThe following types are supported:\n* `data object` (serialized as an empty JSON object)\n* `data class`\n* `enum class`\n* `sealed class`\n\nThen create a class that will be your factory.\n\u003cdetails open\u003e\n  \u003csummary\u003eFactory setup\u003c/summary\u003e\n\n  ```kotlin\n  @KotshiJsonAdapterFactory\n  object ApplicationJsonAdapterFactory : JsonAdapter.Factory by KotshiApplicationJsonAdapterFactory\n  ```\n\u003c/details\u003e\n\nLastly just add the factory to your Moshi instance, and you're all set.\n\n\u003cdetails open\u003e\n  \u003csummary\u003eAdd to moshi\u003c/summary\u003e\n\n  ```kotlin\n  val moshi = Moshi.Builder()\n      .add(ApplicationJsonAdapterFactory)\n      .build()\n  ```\n\u003c/details\u003e\n\nBy default adapters aren't requested for primitive types (even boxed primitive\ntypes) since it is worse for performance and most people will not have custom\nadapters anyway.\nIf you need to use custom adapters you can enable it per module be passing the\n`useAdaptersForPrimitives` to `@KotshiJsonAdapterFactory` or on a per adapter\nby passing the same argument to `@JsonSerializable` (the default is to follow\nthe module wide setting).\n\n### Annotations\n* `@JsonSerializable` is the annotation used to generate `JsonAdapter`'s. Should only be placed on data classes, enums, sealed classes and objects.\n* `@KotshiJsonAdapterFactory` makes Kotshi generate a JsonAdapter factory. Should be placed on an object that implements `JsonAdapter.Factory`.\n* `@JsonDefaultValue` can be used to annotate a fallback for enums or sealed classes when an unknown entry is encountered. The default is to thrown an exception.\n* `@JsonProperty` can be used to customize how a property or enum entry is serialized to and from JSON.\n* `@Polymorphic` and `@PolymorphicLabel` used on sealed classes and their implementations.\n* `@RegisterJsonAdapter` registers a json adapter into the Kotshi json adapter factory.\n\n### Default Values\nYou can use default values just like you normally would in Kotlin.\n\nDue to limitations in Kotlin two instances of the object will be created when a class uses default values\n([youtrack issue](https://youtrack.jetbrains.com/issue/KT-18695)). This also means that composite default values are not\nsupported (for example a `fullName` property that is `\"$firstName $lastName\"`).\n\nFor enum entries and sealed classes you may annotate a single type with `@JsonDefaultValue` to indicate that the entry\nshould be used when an unknown value is encountered (by default an exception is thrown).\n\n### Transient Values\nProperties marked with `@Transient` are not serialized. All transient properties must have a default value.\n\nOnly properties declared in the constructor need to be annotated since other properties are ignored.\n\n### Custom Names\nBy default, the property or enum entry name is used when reading and writing JSON. To change the name used you may use\nthe `@JsonProperty` annotation or the regular `@Json` annotation from Moshi to annotate the property or enum entry.\n\n### Json Qualifiers\nKotshi has full support for `@JsonQualifier`, both plain and those with arguments. Simply annotate a property with the\ndesired qualifiers and Kotshi will pick them up.\n\n### Registered adapters\nIt's often required to have a few adapters that are handwritten, for example for framework classes. Handling this in a\ncustom factory can be tedious, especially for generic types. To make this easier you may annotate any class or object\nthat extends `JsonAdapter` with `@RegisterJsonAdapter` and Kotshi will generate the needed code in the adapter factory.\n\n### Options\n\n#### `kotshi.generatedAnnotation`\nThis option tells Kotshi to add the `@Generated` annotation to all generated classes which is disabled by default.\n\nFor Java 9+ use `javax.annotation.processing.Generated` and for Java 8 and below use `javax.annotation.Generated`.\n\nExamples:\n\u003cdetails open\u003e\n  \u003csummary\u003eKSP\u003c/summary\u003e\n\n  ```kotlin\n  ksp {\n      // When using Java 9 and above\n      arg(\"kotshi.generatedAnnotation\", \"javax.annotation.processing.Generated\")\n      // When using Java 8 and below\n      arg(\"kotshi.generatedAnnotation\", \"javax.annotation.Generated\")\n  }\n  ```\n\u003c/details\u003e\n\n## Limitations\n* Kotshi only processes files written in Kotlin, types written in Java are not supported.\n* Only data classes, enums, sealed classes and data objects are supported.\n  - Only constructor properties will be serialized.\n  - Qualifiers whose arguments are named as a Java keyword cannot be seen by annotations processors and cannot be used.\n\n## Download\n\n\u003cdetails open\u003e\n  \u003csummary\u003eKotlin with KSP\u003c/summary\u003e\n\n  ```kotlin\n  plugins {\n    id(\"com.google.devtools.ksp\") version \"\u003cversion\u003e\"\n  }\n\n  dependencies {\n    val kotshiVersion = \"4.0.0\"\n    implementation(\"se.ansman.kotshi:api:$kotshiVersion\")\n    ksp(\"se.ansman.kotshi:compiler:$kotshiVersion\")\n  }\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eGroovy with KSP\u003c/summary\u003e\n\n  ```groovy\n  plugins {\n    id \"com.google.devtools.ksp\" version \"\u003cversion\u003e\"\n  }\n\n  dependencies {\n    def kotshiVersion = \"4.0.0\"\n    implementation \"se.ansman.kotshi:api:$kotshiVersion\"\n    ksp \"se.ansman.kotshi:compiler:$kotshiVersion\"\n  }\n  ```\n\u003c/details\u003e\n\nSnapshots of the development version are available in [the sonatype snapshots repository](https://oss.sonatype.org/#view-repositories;snapshots~browsestorage~se/ansman/kotshi/).\n\n## License\n```text\nCopyright 2017-2024 Nicklas Ansman Giertz.\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansman%2Fkotshi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fansman%2Fkotshi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fansman%2Fkotshi/lists"}