Plugin Api

[evant]

I've gotten several requests for anvil or hilt like features. In order to keep this library simple and flexible I think they would be best implemented on top of kotlin-inject instead, much like those libs are built on top of dagger. The question then becomes should kotlin-inject provide anything to aid in the creation of such things. While doing nothing would be serviceable I think we can offer a nicer experience with a small plugin api.

The proposed idea is for plugins to provide interfaces that the generated component will implement. These interfaces can then provide whatever types they want into the component. For example, an anvil usecase may look like:

@ContributesTo(AppScope::class)
interface ComponentInterface {
  @Provides fun provideSomething(): Something = ...
}

@ContributesBinding(AppScope::class)
class RealAuthenticator @Inject constructor() : Authenticator

@MergeComponent(AppScope::class)
@Component abstract class AppComponent

and then the plugin will generate

AppScopeComponent : ComponentInterface {
   val RealAuthenticator.bind: Authenticator
      @Provides get() = this
}

and tell kotlin-inject about this interface so that it will generate

class InjectAppComponent : AppComponent, AppScopeComponent

Some thought needs to be put into what exactly this api should look like, I think in general it should provide the component class name and annotations and return what interface(s) to add. Something like:

class AnvilInjectPlugin : InjectPlugin {
   override fun provide(packageName: String, className: String, annotations: List<Annotation>) : String? {
      val mergeComponent = annoations.find { it.name == "MergeComponent" } ?: return null
      return "${packageName}.${mergeComponent.value.name}Component"
   }
}

[vRallev]

I'm the original author of Anvil for Dagger 2 and implemented the same features for kotlin-inject for our internal project. I'll give a talk about these extensions at Droidcon SF 2024.

In order to keep this library simple and flexible I think they would be best implemented on top of kotlin-inject instead

This approach seems reasonable and I agree, but the downside is that you open up the door of multiple ways of doing DI and using kotlin-inject, which becomes confusing to users and makes adoption harder. I believe it's okay to be opinionated, have one way to do DI and do it right.

I can speak a little bit about how the Anvil features for kotlin-inject are implemented and how the API surface looks like. All of this was built without making any changes to kotlin-inject itself.

My biggest concern is that kotlin-inject requires typealiases for qualifiers and arguments for scope annotations aren't supported, e.g. @SingleIn(AppScope::class) is the same scope as @SingleIn(LoggedInScope::class). This caused duplication in our case, more boilerplate and made APIs inconsistent. For Anvil, we defined scopes as single classes, e.g. object AppScope and then referenced the same marker in the scope annotation, qualifiers or Anvil annotations:

@SingleIn(AppScope::class)
@ContributesBinding(AppScope::class)
class SessionManagerImpl @Inject constructor(
  @ForScope(AppScope::class) private val coroutineScope: CoroutineScope,
) : SessionManager

For kotlin-inject we needed to introduce new types for each scope, e.g. for the app scope we had to define:

annotation class SingleInAppScope
typealias AppScopeCoroutineScope = CoroutineScope
typealias AppScopeScoped = Scoped

This repeats for every other scope.

For the Anvil features for kotlin-inject we implemented @ContributesTo to add any component interface to a scope:

@ContributesTo
@SingleInAppScope
interface PresenterCoroutineScopeComponent

For us it's a requirement to define the scope on the interface. This allows us to know when to merge this interface.

@MergeComponent is used to trigger the merging:

@Component
@MergeComponent
@SingleInAppScope
abstract class AndroidAppComponent : AndroidAppComponentMerged

When we see @MergeComponent we'll find all contributed component interfaces for this scope and add them as super type to the newly generated *Merged interface. This interface has to be manually added to the component itself. Anvil does this under the hood for you, because it's a compiler plugin and can modify existing code.

@ContributesBinding will generate a new component interface and binding method:

@Inject
@SingleInAppScope
@ContributesBinding
class CounterImpl : Counter

Here some inconsistency comes in. We can only make the connection to the right scope, if the type itself is scoped. If you want to create a new instance every time a type is injected, then you need to remove @SingleInAppScope. As a workaround you can set the scope on the annotation itself:

@ContributesBinding(scope = SingleInAppScope::class)

This is rather ugly but required. To find the right bound type, we inspect the super types. If there is more than one super type, then it's required to define the bound type:

@Inject
@SingleInAppScope
@ContributesBinding(boundType = Counter::class)
class CounterImpl : Counter, OtherType

The last annotation is @ContributesSubcomponent:

annotation class ContributesSubcomponent {
    annotation class Factory
}

This one works very similar to Anvil and no issues there except that we always require a Factory. For Anvil that's optional. E.g. on impl looks like this:

@ContributesSubcomponent
@SingleInRendererScope
interface RendererComponent {
    @ContributesSubcomponent.Factory
    @SingleInAppScope
    interface Parent {
        fun rendererComponent(factory: RendererFactory): RendererComponent
    }
}

This one is very powerful and helps us to reduce boilerplate.

We have more annotations for our codebase specifically. TL;DR is that implementing these things wasn't too hard with KSP and how kotlin-inject works today. I didn't encounter any blocker.

What would be nice to have is for kotlin-inject to automatically pick up the *Merged interface. A hook or plugin for the generated Inject* component to add super types could solve that.

[vRallev]

One more thing. For @MergedComponent I considered generating the class using @Component:

@MergeComponent
@SingleInAppScope
abstract class AppComponent

// Would generate:
@Component
@SingleInAppScope
abstract class GeneratedAppComponent : AppComponent(), AppComponentMerged

I didn't go down that path, because I'm not sure how this would support constructor arguments like provided types or other components. I also need to generate the .create(..) function myself.

[evant]

Thanks for the details!

What would be nice to have is for kotlin-inject to automatically pick up the *Merged interface

Does the proposal I outlined above address this? Anything you'd want to call out if it were to be implemented?

My biggest concern is that kotlin-inject requires typealiases for qualifiers

#253 (comment) is where we currently stand on this. For the short-term, qualifiers are supported under javax.inject.Qualifier right now, I'm curious if you explored using that for the time being?

and arguments for scope annotations aren't supported

Could you file an issue for this? that actually seems pretty reasonable

but the downside is that you open up the door of multiple ways of doing DI and using kotlin-inject, which becomes confusing to users and makes adoption harder. I believe it's okay to be opinionated, have one way to do DI and do it right.

Check out #212 which has some discussion on this. TLDR I'm not against it but it would require a time investment to prove out. If you are interested maybe you could use your implementation as a starting point for contributing? maybe after the other kinks have been worked out.

[vRallev]

Does the proposal I outlined above address this? Anything you'd want to call out if it were to be implemented?

I think it would cover this use case, yes. Generally kotlin-inject doesn't need to provide much. The most important piece was supporting KSP rounds properly and KSP does! I don't put much weight on this particular issue. The downside of automatically adding the interface to the generated component is that when referencing AppComponent from your example, the IDE wouldn't be aware of that the component will implement ComponentInterface as well. By manually adding the interface like I did, the IDE integration is better, because it resolves all the types.

For the short-term, qualifiers are supported under javax.inject.Qualifier right now, I'm curious if you explored using that for the time being?

I did not try this, because I didn't like the idea of a fake annotation that may conflict with the original annotation on Android / JVM project. I could probably workaround this using expect / actual, but I didn't want to build our framework on top of a workaround. The lack of argument support for scopes would have added more inconsistency.

Could you file an issue for this? that actually seems pretty reasonable

Done: #377

maybe after the other kinks have been worked out.

I'll check internally what it takes to open source our framework.

[evant]

because I didn't like the idea of a fake annotation that may conflict with the original annotation on Android / JVM project

fair enough, I do plan to add a kotlin-inject specific annotation soon, I think it's actually hanging out in a branch somewhere already but got a little stuck with #253 (comment), but maybe just doing the exact same thing as the javax annotation for now would be a good starting point.

[evant]

done in #378

[vRallev]

Our code is now public: https://github.com/amzn/kotlin-inject-anvil