Konvert

Name: konvert
Rating: 5 (156 reviews)
Author: mcarleio

[![Maven Central][maven-image]][maven-url] [![License][license-image]](LICENSE) [![Code Coverage][codecov-image]][codecov-url]

This is Konvert, a Kotlin mapping code generator using Kotlin Symbol Processing (KSP). Designed specifically for Kotlin and its features, Konvert supports a wide range of use cases.

Major features:

🧩 supports various class kinds → data, enum, value, regular POJOs
🔄 Null-safe by default
⚙️ Smart conversions (Int → String, Instant → Date, …)
🔧 Define reusable converters with @Konverter
🔌 Extend via SPI for ultimate control
🔗 Collections & maps — mapping of elements included
🛠️ Fine-grained property mapping customization
☕ 100% Java interoperability
✨ Generates clean, idiomatic Kotlin code
⏱️ Generated at compile time
🚫 Zero reflection, zero runtime overhead
📦 Works seamlessly with Gradle and Maven

> ℹ️ This README provides a basic overview, for more details have a look at the documentation.

Usage

There are three different ways to use Konvert:

Using @KonvertTo:

   @KonvertTo(PersonDto::class)
   data class Person(val firstName: String, val lastName: String)
   data class PersonDto(val firstName: String, val lastName: String)
   ``
   This will generate the following extension function
   `kotlin
   fun Person.toPersonDto(): PersonDto =
      PersonDto(firstName = firstName, lastName = lastName)
   `
Using @KonvertFrom (especially useful if you cannot change the source class code)
   
`kotlin
   class Person(val firstName: String, val lastName: String) {
      @KonvertFrom(PersonDto::class)
      companion object
   }
   class PersonDto(val firstName: String, val lastName: String)
   `
   This will generate the following extension function
   `kotlin
   fun Person.Companion.fromPersonDto(personDto: PersonDto): Person =
      Person(firstName = personDto.firstName, lastName = personDto.lastName)
   `Using @Konverter:

   
`kotlin
   class Person(val firstName: String, val lastName: String)
   data class PersonDto(val firstName: String, val lastName: String)   @Konverter
   interface PersonMapper {
      fun toDto(person: Person): PersonDto
   }
   `
   This will generate the following object
   `kotlin
   object PersonMapperImpl: PersonMapper {
      override fun toDto(person: Person): PersonDto
         = PersonDto(firstName = person.firstName, lastName = person.lastName)
   }
   `
For a simple example project have a look into the example directory.
Type mappings
For simple type mappings, like from Instant to Date, there already is a type converter provided with Konvert:

kotlin
@KonvertTo(PersonDto::class)
class Person(val name: String, val birthday: Instant)
class PersonDto(val name: String, val birthday: Date)

This will generate the following extension function
kotlin
fun Person.toPersonDto(): PersonDto = PersonDto(
   name = name,
   birthday = birthday.let { java.util.Date.from(it) }
)

Have a look at the documentation for a list of provided type converters.
🛈: You can also create your own type converter library by
implementing TypeConverter and register it
using SPI.
Fine tuning
Most of the time, the source and target classes might not have the same property names and types.
You can configure specific mappings and rename the generated extension function like this:
kotlin
@KonvertTo(
   PersonDto::class,
   mappings = [
      Mapping(source = "firstName", target = "givenName"),
      Mapping(source = "lastName", target = "familyName")
   ],
   mapFunctionName = "asDto"
)
class Person(val firstName: String, val lastName: String)
class PersonDto(val givenName: String, val familyName: String)

This will generate the following extension function
kotlin
fun Person.asDto(): PersonDto = PersonDto(
   givenName = firstName,
   familyName = lastName
)


For further functionality, have a look into
the documentation
the KDocs of the annotations,
the example project
or the tests.
Gradle Setup
To use Konvert with Gradle, you have to do the following steps:

Add konvert-api as a dependency to use the annotations:

kotlin
   dependencies {
      implementation("io.mcarle:konvert-api:$konvertVersion")
   }


Add the KSP plugin:

kotlin
   plugins {
       id("com.google.devtools.ksp").version("2.3.5")
   }

Add konvert as a ksp dependency:

kotlin
   dependencies {
      ksp("io.mcarle:konvert:$konvertVersion")
   }


Maven Setup
To use Konvert with Maven, you have to do the following steps:

Add konvert-api as a dependency to use the annotations:

xml
   
       io.mcarle
       konvert-api
       ${konvert.version}

Use the ksp-maven-plugin with konvert as a dependency:

xml
   
       io.mcarle
       ksp-maven-plugin
       2.3.5-1
       
           
               
                   ksp
               
           
       
       
           
               io.mcarle
               konvert
               ${konvert.version}


Further information
Konvert is primarily compiled and tested with JDK >=17. It should also work with anything below JDK 17, but is not guaranteed to.
Konvert is able to convert classes from and to classes written in Java (and probably also in other JVM languages).
Alternatives
There are some alternatives to Konvert that you might want to check out:
Mappie
  Mappie does not use KSP, but instead is a compiler plugin for Kotlin itself.
  It uses reflection rather than String references to define the mappings,
  but replaces the reflection code during compile time with idiomatic Kotlin code.
MapStruct
  
MapStruct is a well known Java mapping library using annotation processing (see kapt).
  Can be used in Kotlin projects, but does not support Kotlin specific features.
kMapper
  
kMapper is also a KSP processor, but seems to only support mapping between Kotlin data classes.
ShapeShift️
  
ShapeShift uses reflection at runtime to map between classes.
Code yourself (with AI support)
  Indeed, it sometimes can be faster, easier and more flexible to write mapping code manually.
  With the help of AI tools nowadays, this repetitive task can be automated to a certain degree.
Building
Gradle
To build the project, simply run
gradle build
#### Run all tests

By default, only a subset of available tests are executed, which should verify most of Konvert's functionality. To run all tests, append the propertyrunAllTests, e.g.:

gradle test -PrunAllTests

`Documentation`

To serve the Jekyll site locally, simply run the following command inside docs`:

docker run --rm -it -v "$PWD":/site -p 4000:4000 bretfisher/jekyll-serve

CI

GitHub Actions are used to:

build and test
release and publish to a Maven repository
generate documentation and deploy it to GitHub Pages.

Changelog

The changelog contains all notable changes.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

[maven-image]: https://img.shields.io/maven-central/v/io.mcarle/konvert.svg

[maven-url]: https://central.sonatype.com/artifact/io.mcarle/konvert/

[license-image]: https://img.shields.io/github/license/mcarleio/konvert.svg

[codecov-image]: https://img.shields.io/codecov/c/github/mcarleio/konvert.svg

[codecov-url]: https://codecov.io/gh/mcarleio/konvert

--- Tranlated By Open Ai Tx | Last indexed: 2026-04-08 ---