Minimizes boilerplate by generating mapping functions between annotated types, supports custom transformations, parameter aggregation, and handles mapping discrepancies with annotations, enhancing code efficiency.
kmap is a KSP plugin that aims to minimize the amount of boilerplate code in a project by generating mapping functions to the accordingly annotated types.
First you need to add the KSP Gradle Plugin
plugins {
id("com.google.devtools.ksp") version "CURRENT_KSP_VERSION"
}
You then need to add the kmap processor so that ksp can actually use it:
dependencies {
ksp("es.horm.kmap:kmap-processor:0.1.0")
}
Then you need to add the kmap runtime library so that you can use the required annotations:
Multiplatform Projects:
sourceSets {
val commonMain by getting {
dependencies {
implementation("es.horm.kmap:kmap-runtime:0.1.0")
}
}
}
Single Platform Projects:
dependencies {
implementation("es.horm.kmap:kmap-runtime:0.1.0")
}
Currently, the main annotations in kmap are the @KmapTo and @KmapFrom annotations.
To generate a mapper from class Source to class Destination you either annotate class Source with the @KmapTo annotation like so:
@KmapTo(Target::class)
data class Source(...)
which will generate an extension function on Source like so: fun Source.toTarget().
Or you annotate your Target class with the @KmapFrom annotation like so:
@KmapFrom(Source::class)
data class Target(...)
which will also generate an extension function on Source called toTarget().
During the build phase the kmap-processor will now generate mapping functions for all classes annotated with either @KmapFrom or @KmapTo.
You can then freely use these mapping functions in your code.
For cases, where the parameters in the source and target classes are different you can
use the Mapping Annotation. Both @KmapTo and @KmapFrom take an array of Mapping annotations
as parameter like so:
@KmapTo(
target = PersonBusinessModel::class,
mappings = [Mapping(source = "yearsOld", target = "age")]
)
data class PersonDto(
val yearsOld: Int,
//...
)
For the more complicated cases, where you need to do some kind of transformation between your source
and target kmap offers an extension to the Mapping mechanism called Transformer:
class AgeTransformer : KmapTransformer<Int, Int> {
override fun transform(value: Int): Int = (value * ).roundToInt()
}
(
yearsOld: ,
)
Like this you can not only transform from, say Int to Int but also between different types, like
for example String to kotlinx datetime's LocalDate:
class DateTransformer : KmapTransformer<String, LocalDate> {
override fun transform(value: String): LocalDate = LocalDate.parse(value)
}
@KmapTo(
target = PersonBusinessModel::class,
mappings = [Mapping(source = "birthDate", target = , transformer = DateTransformer::class)]
)
(
birthDate: ,
)
To map from multiple parameters to a single parameter you can use an Aggegator. Both @KmapTo and @KmapFrom
take an array of aggregators as parameter.
Using aggregators you can easily map from multiple parameters to a single one like so:
class NameAggregator : KmapTransformer<PersonDto, String> {
override fun transform(value: PersonDto): String = with(value) { "$lastName, " }
}
(
firstName: String,
lastName: String,
)
Both Aggregators and Transformers use the same abstraction to achieve the same result: KmapTransformer.
However, when using KmapTransformer to implement an Aggregator the first type parameter is the source class as
this is the value where you can freely decide which parameters you will choose to map to your defined target parameter.
While kmap already offers quite a few ways to map between your classes nested mapping is currently not supported (see Roadmap).
There currently exist no properly supported way to do nested mappings. You probably could use an aggregator for each property. However, that would be way too verbose since you'd need one aggregator for each single property of your nested object (in the example below that'd already be two aggregators although the Address class doesn't even represent a complete Address yet). Mappings wouldn't work, because checks are being made to see whether the source exists verbatim.
Currently, I do not check, whether a Transformer actually returns the type it is supposed to. How should type conflicts be handled? -> Probably error out, causing the Processor to stop
Error Messages are currently not helpful at all, they should be improved in order to point users to where something is going wrong.
Source.toTarget() function. Maybe there would
be some utility in having a way to generate a Target.Companion.fromSource() function? This may be a viable thing to
implement if there is a need in the Community.Thank you to Daniel Pelsmaeker for teaching me How to debug KSP processors
data class PersonDto(
val firstName: String,
val lastName: String,
val yearsOld: Int,
val address: Address,
)
data class Address(
val street: String,
val houseNumber: Int,
// ...
)
data class PersonBusinessModel(
val name: String, // aggregate from firstName and lastName -> Handled by aggregator
val age: Int, // called yearsOld in Dto -> handled by mapper
val street: String, // currently no way of mapping PersonDto.address.street to this, could be handled by an aggregator but should also be doable with a mapping in my mind
val houseNumber: Int, // see above
)
Surfaced from shared tags and platforms — no rankings paid for.