How to use and register custom TypeConverters

[ctparton]

Hello,

Great work on the library - nice to see something utilising KSP.

I'm just wondering how we can utilise custom Type Converters. I would like to do this due to a custom enum to data class mapping.

@Mapper(
    collectionMappingStrategy = CollectionMappingStrategy.ADDER_PREFERRED,
    nullValueCheckStrategy = NullValueCheckStrategy.ALWAYS,
)
abstract class DocumentMapper {
    @Mappings(
        Mapping(source = "type", target = "type", qualifiedByName = ["documentType"]),
        Mapping(source = "number", target = "number"),
        Mapping(source = "country", target = "country"),
    )
    abstract fun map(document: com.lhv.protobuf.idv.v1.type.session.Document): SessionDocument

    @Named("documentType")
    fun documentType(type: DocumentType): com.lhv.capplat.veriff.model.decision.DocumentType {
        return when (type) {
            DocumentType.DOCUMENT_TYPE_PASSPORT -> com.lhv.capplat.veriff.model.decision.DocumentType.PASSPORT
            DocumentType.DOCUMENT_TYPE_ID_CARD -> com.lhv.capplat.veriff.model.decision.DocumentType.ID_CARD
            DocumentType.DOCUMENT_TYPE_RESIDENCE_PERMIT -> com.lhv.capplat.veriff.model.decision.DocumentType.RESIDENCE_PERMIT
            DocumentType.DOCUMENT_TYPE_DRIVERS_LICENSE -> com.lhv.capplat.veriff.model.decision.DocumentType.DRIVERS_LICENSE
            DocumentType.DOCUMENT_TYPE_VISA -> com.lhv.capplat.veriff.model.decision.DocumentType.VISA
            DocumentType.DOCUMENT_TYPE_TAX_STATEMENT -> com.lhv.capplat.veriff.model.decision.DocumentType.fromValue("TAX_STATEMENT")
            else -> com.lhv.capplat.veriff.model.decision.DocumentType.OTHER
        }
    }
}

In this case documentType maps from an enum DocumentType to a plain data class (also called document type)

The documentation simply reads:

Therefore, Konvert [provides a lot of TypeConverter](https://mcarleio.github.io/konvert/typeconverter/provided) in the [konvert-converter module](https://mcarleio.github.io/konvert/modules). You can even simply create your own (little) library with a collection of custom TypeConverter and provide them to Konvert during KSP (TODO: document).

From my understanding from the documentation that's there I would need to:

1. Create a new library that depends on konvert-converter-api, lets call this my-custom-library
2. Create an instance of a Type Converter for my custom mapping
3. In the upstream mapping library add it to the classpath with implementation(project(:"my-custom-library")
4. Konvert will detect mappings of this type and automatically apply the custom mapper

[mcarleio]

First, to answer your main question about how to build and use a custom type converter library:
Your steps seem quite correct, but:

• it needs to be in the KSP dependencies: ksp(project(...))
• Konvert uses Java's ServiceLoader to identify all implementations of the TypeConverter interface. Therefore, make sure to create the appropriate META-INF file. I am using @AutoService(TypeConverter::class) on the class. Have also a look in the gradle file of the converter module. With that, the file is automatically created.

With that, it should™ automatically work.

But I wonder if you really have a need for a custom type converter library. You can also just implement a @Konvert function in a @Konverter interface, which just maps according to your needs from/to enum to/from data class. Once defined, that function is (more or less) treated as a TypeConverter.

Implementing a custom library is more intended for special cases.

[ctparton]

Ah ok. So, I could do:

@Konverter
interface DocumentMapper {
    @Konvert(
        mappings = [
            Mapping(target = "type", expression = <inline expression for this when block>),

Then, just use the custom TypeConverters for conversions I do across several mappers. For example, I am often converting from a protobuf date type to Java Local Time.

[mcarleio]

Sorry, I only have my smartphone with me, but you can simply implement it like this:

@Konverter
interface DocumentMapper {
    fun map(from: YourEnum): YourDataClass {
        // Implement your mapping logic here
    }
}

With that, Konvert will register that function as a custom converter.

[ctparton]

Thank you!

This is a much cleaner way of doing an explicit mapping.

I thought going down the Custom type converter route and writing Kotlin Poet code seemed a bit convoluted!

Currently experimenting with switching from MapStruct to your library, so this is very helpful.