Yatagan DI Framework

Yatagan achieves faster builds (potentially up to 2x faster incremental builds) by reducing the scope of annotation processing.

In a standard Dagger setup, every module with DI code requires an annotation processor. In Yatagan, you only apply processing to modules containing root components (@Component(isRoot = true)).

Optimization Strategy:

• Apply Yatagan processing only to root-component modules.
• For all other modules, use only the api-public dependency (no KAPT/KSP).
• In debug environments, use the Reflection backend to remove KAPT/KSP from the build pipeline entirely in many modules.

To ensure consistency across the component hierarchy, Yatagan follows these evaluation rules:

• Single Evaluation: Each unique condition (boolean variable) is evaluated only once per component hierarchy. The value is cached and reused.
• Provider Lifecycle: Condition provider classes are queried from the graph like standard dependencies. If a provider is used in multiple branches, it is queried and cached in the highest (closest to root) component.
• Static vs Non-static:
  • If a condition is accessible via a static context, Yatagan queries it directly (potentially during component construction).
  • For non-static conditions, evaluation is lazy: it occurs strictly upon the first construction of a conditional binding that uses that condition.

Yatagan provides first-class support for dynamic optional dependencies, which are dependencies that may or may not be present in the DI graph based on runtime conditions. This is more maintainable and scalable than manually writing @Provides methods for Optional<T> in Dagger.

Example of using an optional dependency in a class constructor:

@Singleton
class MyClass @Inject constructor(
    /**
     * Dynamic optional dependency, that is present/absent in DI-graph based on declared runtime condition.
     */
    val myOptionalDependency: Optional<MyClassUnderRuntimeCondition>,
)

You can implement custom graph inspections by writing a plugin for Yatagan's validation pipeline. This is achieved via the Service Provider Interface (SPI), similar to Dagger.

Constraints:

• Plugins cannot perform additional code generation.
• Plugins cannot modify the graph being inspected.

Yatagan provides APIs for conditional logic and component variations, which can replace Dagger's @BindsOptionalOf and SPI-based models.

Conditional Bindings

Use @ConditionExpression to declare a runtime condition. Then, apply the @Conditional annotation to a binding or a class with an @Inject-annotated constructor to determine if that binding should be present.

Variants API

Similar to Android flavors, you can declare components with specific variants. This allows you to include or exclude bindings based on the component's variant.

• Use @Component(variant = ...) to define the variant on a component.
• Use @Conditional(.., onlyIn = ...) to restrict a binding to a specific variant.

Yatagan provides three primary backends that are designed to behave identically, allowing you to switch between them based on your environment:

1. KAPT/APT (processor-jap): The classic, stable code generation mode. Use this for mixed Java/Kotlin projects or when stability is the priority.
2. KSP (processor-ksp): A modern code generation mode leveraging Google's KSP. It works best for pure-Kotlin projects. Because Yatagan operates on the Java type system, KSP support for modeling Java code can be inconsistent.
3. Reflection (api-dynamic): A runtime backend designed for extremely fast local debug builds. It eliminates the need for annotation processing in many modules.
   • Warning: Reflection mode is broken by code minifiers like Proguard or R8 and should generally not be used in production.

When using the reflection backend, annotations used for Scopes, Qualifiers, or other DI metadata must have RUNTIME retention.

If an annotation has non-runtime retention, it will work with code generation backends but will fail silently or cause inconsistencies with the reflection backend. To ensure compatibility between both modes, Yatagan's code generation backends will report non-runtime retention as an error/warning to maintain parity with reflection's requirements.

For Android, it is recommended to use the Reflection backend in debug builds to maximize build speed, and a codegen backend (KSP or KAPT) in release builds.

Note on Reflection: Reflection mode requires minSdk = 24 to safely support static methods in interfaces without performance penalties from AGP desugaring. If your minSdk is lower, use reflection only for debug builds where the target is at least 24.

// Use reflection in debug builds.
debugApi("com.yandex.yatagan:api-dynamic:${yataganVer}")

// Use codegen in releases
releaseApi("com.yandex.yatagan:api-public:${yataganVer}")
if (kspEnabled) {
    kspRelease("com.yandex.yatagan:processor-ksp:${yataganVer}")
} else {
    kaptRelease("com.yandex.yatagan:processor-jap:${yataganVer}")
}