How to benefit from ksp / arrow-meta

[fmatosqg]

I'd like to get some chat going on about how to make koin better by using ksp. I understand that arrow-meta is much more powerful, at the same time that in my experience it's slower at compile time and a bit harder to figure out how to use and troubleshoot.

#1059 was started to explore what things can be done with ksp. So far it has shown that it's very easy to find classes, constructors and methods that have annotations, and the generation of factories, singletons, etc is relatively straighforward as long as it doesn't cross gradle module boundaries.

From my explorations, doing the same task without annotations is either impossible or more complicated - though this is not complete yet. One way that is yet to be explored is through the application developer writing an interface for a factory, and ksp generating code that glues well with koin modules. For example:

interface Kitchen: KoinKspFactory {
   fun providesTermosiphon() : Termosiphon

   @Singleton
   fun providesCoffeeMaker() : CoffeeMaker // --> single<CoffeeMaker> () --> single{ CoffeeMaker(get().... } 
   fun providesSplashViewModel() : SplashViewModel // --> viewModel { SplashViewModel(get(), get() } 

   fun provideDummyServiceWithNamedBean( @BeanName("bean1") bean1:String ) : DummyService // --> factory { DummyService(bean1 = get(named("bean1") )
}

Although it's not clear how class inheritance would be solved by either the "interface" or "annotation" approaches. Though it's not a problem of code generation (it's easy to crawl all superclasses and generate factory chains that resolve all the class hierararchy of CoffeeMaker), but finding the best defaults and allowing them to be easily overriden by the application developer.

Something that could work but I haven't tried: fun providesEngine<Car>() : Engine could resolve inject<Engine> given an instance of Car is somewhere in the dependency graph.

To start small, I think these are ways to bulk generate a partial graph, while the more complicated use cases could be filled in by the application developer.

[arnaudgiuliani]

Hi @fmatosqg

let me share here my vision, and I can share more about how I see things. Let's take the thermosiphon case, it's a compact example.

// Heater component
interface Heater
class ElectricHeater : Heater { ... }

// Pump component
interface Pump {
    fun pump()
}
// Is injecting the Heater component
class Thermosiphon(private val heater: Heater) : Pump { ... }

// Coffee Maker
// Is injecting the Heater & Pump components
class CoffeeMaker(private val pump: Pump, private val heater: Heater)

// is bootstraping the CoffeeMaker instance
class CoffeeApp : KoinComponent {
    val maker: CoffeeMaker by inject()
}

For the Kotlin plugin perspective (either KSP or Meta), I see 2 ways of doing it.

#1 - First, would be a smarter DSL, thanks to code generation behind. I would write a module like:

val coffeeAppModule = module {
    single<CoffeeMaker>()
    single<Thermosiphon>() bind Pump::class
    single<ElectricHeater>() bind Heater::class
}

The experience would be the same as using koin-core-ext that is using runtime reflection, but finally all is done via the Kotlin plugin. This could generate code, like for example single<Thermosiphon>() bind Pump::class would generate single { Thermosiphon(get()) bind Pump::class }

#2 - Annotation processing solution, that generates code behinds for us. We would keep the "DSL experience" but with annotation. As a start, I would have a @Single annotation to replace any single { } declaration

I would write something like below, only on concrete types that need to be declared:

@Single
class ElectricHeater : Heater { ... }

@Single
class Thermosiphon(private val heater: Heater) : Pump { ... }

@Single
class CoffeeMaker(private val pump: Pump, private val heater: Heater)

Each @Single would generate the Koin definition. Like @Single class Thermosiphon(private val heater: Heater) : Pump would generate single { Thermosiphon(get()) } bind Pump::class

In all solution, I believe we need to see if we can generate some "default" code somewhere and allow us to run it. Let's see what we can do with those Kotlin plugin technologies.

[fmatosqg]

I have played a bit with proposal #1, and while I find it very tempting I couldn't get nowhere closer to getting it started.

The problem seems to be a key limitation of ksp by design: we cannot find function calls or assignments. Consider either the expression val key1: String = "value1" or val key2: String = value2(), basically ksp is suited to find key1 or key2 but not "value1" or value2(). Clarifying, this works as long as we're defining a class' field/property, so it won't work in the body of a method.

It means that it can find val coffeeAppModule, and it knows it is of class Module, but cannot see anything after = module { .... }. I'm not experienced in dsls, so I'm not aware if there's a way to transform or implement a similar looking dsl that would work around this limitation.

The closest thing I can imagine is something that looks more like an interface for a factory. The following file should be straightforward to find, process and generate a concrete class from. The "entry point" for the processing in this case would be finding interfaces that extend KoinSingletonFactory.

#1a

interface ICoffeeSingletons: KoinSingletonFactory {

    val thermosiphon: Thermosiphon
}

which could generate something along the lines of

val coffeeSingletons = module {
    single{ Thermosiphon( get() ) } 
}

or even a plain old class

class CoffeeSingletons: ICoffeeSingletons, KoinComponent {
    overrides val thermosiphon: Thermosiphon by lazy { 
         Thermosiphon( get() ) 
    }
. . .
}

A workaround for the bind situation may be achieved with generics (pending experiments)

#1b

interface ICoffeeSingletons {

   val pumpReference: KoinSingletonFactory<Thermosiphon, Pump>  
}

[arnaudgiuliani]

Ok, perspective #1 is quite tricky 🤔 Let's put it aside for now.

What could we do with annotation processing? In the #2 case, I would like just to add those @Single annotations, no module to write then. Can we spot the constructor, and see how much properties are required to write it? this would help guess the number of get() to write.

[fmatosqg]

Yep that's easy to do, I'm keen to give it a try next weekend. Spotting primary or even not primary constructors is close to trivial.

The only ambiguous thing about @Single is that we need a way to specify the bind from Thermosiphon to Pump.

There are also some considerations whether following or not JSR330. Because following it may create issues with multiplatform, and also not folowing it would allow us to have Single( val bind: KClass< out Any > ) like in

@Single(bind = Pump::class ) 
class Thermosiphon(private val heater: Heater) : Pump { ... }

[arnaudgiuliani]

I've just publish a rewrite of the index engine, to help declare as fast as possible any new mapping into Koin. (new_engine branch)

On an annotation, we can scan current extended types. But you're right. We need to allow a bind property to let the user specify what type is bound here.

[fmatosqg]

Upgrade of the POC to ksp beta01 is completed (branch https://github.com/fmatosqg/koin/tree/ksp) .

I'm still using a new class called KoinInject in that branch for more flexibility. An option for releasable code would be javax.inject.Singleton, but for the ongoing experiments I'm playing around with parameters that Singleton wouldn't allow. Currently:

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.FIELD, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.CLASS)
annotation class KoinInject(
        val isSingle: Boolean = false, val bind: KClass<out Any> = Any::class
)

[arnaudgiuliani]

Hey @fmatosqg

I have also cracked some experiments and figured out how we can delivery a great experience. I'm starting with the definitions:

@Single
class CoffeeMaker(private val pump: Pump, private val heater: Heater)
@Single
class ElectricHeater : Heater
@Single
class Thermosiphon(private val heater: Heater) : Pump

I believe, I need to keep the DSL experience & simplicity. We can also see for some javax standard annotations.

We can scan easily supertypes for classes, and easily generate extra bindings if not specified in the annotation @Single(binds = [...])

Then it's pretty easy to generate something with:

module {
  single { CoffeeMaker(get();get()) }
  single { ElectricHeater() } bind(Heater::class)
  single { Thermosiphon(get()) } bind(Pump::class)
}

First "good" thing is to be able to generate a default module:

startKoin { 
    modules(defaultModule)
    // either
    defaultModule() // extension generated
}

Factory, Scoped, Scope are fine to generate. The trick is that we need to bring code generation on existing modules. Two way for that:

• bring extension in existing module DSL, with @ComponentScan, that allow us to tag a Module field instance and bring an extension to bring scan/generated definition

@ComponentScan
val coffeeModule = module {
   useGeneratedComponents() // extension generated
}

with generated extension below:

fun Module.useGeneratedComponents():Module {
   single { ... }
   return this
}

and just use it in Koin:

startKoin {
   modules(coffeeModule)
}

• bring Module class with @Module, that allow us to tag a Module class instance and bring an extension to bring scan/generated definition:

@Module
class MyModule {

   @Single
   fun pump(heater: Heater) : Pump = Thermosiphon(heater)
}

it would bring a .module extension, generated the associated module:

fun myModuleKClass(moduleClass : org.koin.example.test2.MyModule) = module {
   single { moduleClass.pump(get()) }
}
val org.koin.example.MyModule.module: org.koin.core.module.Module
   get() = myModuleKClass(this)

and just use it in Koin:

startKoin {
   modules(MyModule().module)
}

Also, we can use @ComponentScan to generate declared components like regular modules:

@Module
@ComponentScan // Scan for annotated components
class MyModule {

}

What do you think about that?
I have a playground project, with a ksp compiler working on new Koin 3.1.0 engine. It can then be multiplatform!
Let me share it in the next days 👍