0
# Kodein-DI
1
2
Kodein-DI is a comprehensive dependency injection framework for Kotlin Multiplatform applications that provides effortless dependency retrieval and container management. It enables lazy instantiation of dependencies, eliminates concerns about initialization order, and supports binding classes or interfaces to their instances or providers with a declarative DSL.
3
4
## Package Information
5
6
- **Package Name**: kodein-di
7
- **Package Type**: maven
8
- **Language**: Kotlin Multiplatform
9
- **Installation**: `implementation("org.kodein.di:kodein-di:7.26.1")`
10
11
## Core Imports
12
13
```kotlin
14
import org.kodein.di.*
15
```
16
17
For specific functionality:
18
19
```kotlin
20
import org.kodein.di.DI
21
import org.kodein.di.DIAware
22
import org.kodein.di.DirectDI
23
import org.kodein.di.bindSingleton
24
import org.kodein.di.bindProvider
25
import org.kodein.di.bindFactory
26
import org.kodein.di.instance
27
import org.kodein.di.provider
28
import org.kodein.di.factory
29
```
30
31
## Basic Usage
32
33
```kotlin
34
import org.kodein.di.*
35
36
// Define interfaces and classes
37
interface DataSource
38
class SqliteDataSource : DataSource
39
interface UserService
40
class UserServiceImpl(private val dataSource: DataSource) : UserService
41
42
// Create DI container
43
val di = DI {
44
bind<DataSource>() with singleton { SqliteDataSource() }
45
bind<UserService>() with provider { UserServiceImpl(instance()) }
46
constant("appName") with "MyApp"
47
}
48
49
// Use dependency injection
50
class MyController : DIAware {
51
override val di: DI = di
52
53
private val userService: UserService by instance()
54
private val appName: String by constant()
55
56
fun handleRequest() {
57
// Use injected dependencies
58
println("Handling request in $appName")
59
}
60
}
61
62
// Direct access (immediate retrieval)
63
val directDI = di.direct
64
val userService = directDI.instance<UserService>()
65
```
66
67
## Architecture
68
69
Kodein-DI is built around several key components:
70
71
- **DI Container**: Main dependency injection container that stores bindings and manages instances
72
- **Binding DSL**: Declarative syntax for configuring dependencies (singleton, provider, factory, instance, multiton)
73
- **Retrieval Patterns**: Both lazy property delegation (DIAware) and direct access (DirectDI) for dependency retrieval
74
- **Scoping System**: Context-aware dependency management with hierarchical scopes and custom scope definitions
75
- **Module System**: Reusable configuration modules for organizing and sharing binding definitions
76
- **Type Safety**: Full Kotlin type safety with generic preservation and TypeToken integration
77
78
## Capabilities
79
80
### Container Configuration
81
82
Core DI container creation and configuration with binding DSL for defining how dependencies are created and managed.
83
84
```kotlin { .api }
85
interface DI : DIAware {
86
val container: DIContainer
87
88
companion object {
89
operator fun invoke(
90
allowSilentOverride: Boolean = false,
91
init: MainBuilder.() -> Unit
92
): DI
93
94
fun lazy(
95
allowSilentOverride: Boolean = false,
96
init: MainBuilder.() -> Unit
97
): LazyDI
98
99
fun direct(
100
allowSilentOverride: Boolean = false,
101
init: MainBuilder.() -> Unit
102
): DirectDI
103
104
fun withDelayedCallbacks(
105
allowSilentOverride: Boolean = false,
106
init: MainBuilder.() -> Unit,
107
): Pair<DI, () -> Unit>
108
109
fun from(modules: List<Module>): DI
110
111
var defaultFullDescriptionOnError: Boolean
112
var defaultFullContainerTreeOnError: Boolean
113
}
114
}
115
116
data class Module(
117
val allowSilentOverride: Boolean = false,
118
val prefix: String = "",
119
val init: Builder.() -> Unit
120
) {
121
val name: String
122
constructor(
123
name: String,
124
allowSilentOverride: Boolean = false,
125
prefix: String = "",
126
init: Builder.() -> Unit,
127
)
128
operator fun getValue(thisRef: Any?, property: KProperty<*>): Module
129
}
130
```
131
132
[Container Configuration](./container-configuration.md)
133
134
### Binding DSL
135
136
Declarative syntax for binding types to their implementations with various creation patterns including singleton, provider, factory, instance, and multiton.
137
138
```kotlin { .api }
139
interface DI.Builder {
140
fun <T : Any> Bind(type: TypeToken<out T>, tag: Any? = null, overrides: Boolean? = null): TypeBinder<T>
141
fun <T : Any> Bind(tag: Any? = null, overrides: Boolean? = null, binding: DIBinding<*, *, T>)
142
fun constant(tag: Any, overrides: Boolean? = null): ConstantBinder
143
fun <T : Any> Delegate(type: TypeToken<out T>, tag: Any? = null, overrides: Boolean? = null): DelegateBinder<T>
144
fun import(module: Module, allowOverride: Boolean = false)
145
fun importAll(vararg modules: Module, allowOverride: Boolean = false)
146
fun importOnce(module: Module, allowOverride: Boolean = false)
147
fun onReady(cb: DirectDI.() -> Unit)
148
149
// Set binding methods
150
fun <T : Any> BindInSet(tag: Any? = null, overrides: Boolean? = null, type: TypeToken<out T>, creator: SetBinder<T>.() -> Unit)
151
fun <T : Any> InBindSet(tag: Any? = null, overrides: Boolean? = null, type: TypeToken<out T>, creator: SetBinder<T>.() -> Unit)
152
fun <T : Any> AddBindInSet(tag: Any? = null, overrides: Boolean? = null, binding: DIBinding<*, *, T>)
153
}
154
155
fun <T : Any> DI.BindBuilder<*>.singleton(
156
creator: NoArgBindingDI<*>.() -> T
157
): Singleton<*, T>
158
159
fun <T : Any> DI.BindBuilder<*>.provider(
160
creator: NoArgBindingDI<*>.() -> T
161
): Provider<*, T>
162
163
fun <A, T : Any> DI.BindBuilder<*>.factory(
164
creator: BindingDI<*>.(A) -> T
165
): Factory<*, A, T>
166
```
167
168
[Binding DSL](./binding-dsl.md)
169
170
### Lazy Property Delegation
171
172
Property delegation pattern for lazy dependency retrieval using DIAware interface with automatic initialization and caching.
173
174
```kotlin { .api }
175
interface DIAware {
176
val di: DI
177
val diContext: DIContext<*>
178
val diTrigger: DITrigger?
179
}
180
181
fun <T : Any> DIAware.instance(tag: Any? = null): LazyDelegate<T>
182
fun <T : Any> DIAware.provider(tag: Any? = null): LazyDelegate<() -> T>
183
fun <A, T : Any> DIAware.factory(tag: Any? = null): LazyDelegate<(A) -> T>
184
fun <T : Any> DIAware.constant(): LazyDelegate<T>
185
```
186
187
[Lazy Property Delegation](./lazy-property-delegation.md)
188
189
### Direct Access
190
191
Immediate dependency retrieval without property delegation for cases requiring direct access to dependencies.
192
193
```kotlin { .api }
194
interface DirectDI : DirectDIBase {
195
fun <T : Any> Instance(type: TypeToken<T>, tag: Any? = null): T
196
fun <T : Any> Provider(type: TypeToken<T>, tag: Any? = null): () -> T
197
fun <A, T : Any> Factory(argType: TypeToken<in A>, type: TypeToken<T>, tag: Any? = null): (A) -> T
198
fun On(context: DIContext<*>): DirectDI
199
}
200
201
interface DirectDIAware {
202
val directDI: DirectDI
203
}
204
```
205
206
[Direct Access](./direct-access.md)
207
208
### Scoping and Context
209
210
Context-aware dependency management with support for hierarchical scopes, context translation, and lifecycle management.
211
212
```kotlin { .api }
213
interface DIContext<C : Any> {
214
val type: TypeToken<in C>
215
val value: C
216
217
data class Value<C : Any>(override val type: TypeToken<in C>, override val value: C) : DIContext<C>
218
class Lazy<C : Any>(override val type: TypeToken<in C>, val getValue: () -> C) : DIContext<C>
219
}
220
221
interface Scope<C> {
222
fun getRegistry(context: C): ScopeRegistry
223
}
224
225
interface ContextTranslator<C, S> {
226
fun translate(key: DI.Key<*, *, *>, context: C): S?
227
}
228
```
229
230
[Scoping and Context](./scoping-and-context.md)
231
232
### Advanced Features
233
234
Advanced dependency injection patterns including constructor injection, external sources, binding search, and sub-DI creation.
235
236
```kotlin { .api }
237
fun <T> DirectDIAware.new(constructor: () -> T): T
238
fun <P1, T> DirectDIAware.new(constructor: (P1) -> T): T
239
240
interface ExternalSource {
241
fun <C : Any, A, T : Any> getFactory(
242
key: DI.Key<C, A, T>,
243
context: C
244
): ((A) -> T)?
245
}
246
247
fun DirectDIAware.subDI(
248
allowSilentOverride: Boolean = false,
249
copy: Copy = Copy.NonCached,
250
init: DI.MainBuilder.() -> Unit
251
): DI
252
```
253
254
[Advanced Features](./advanced-features.md)
255
256
## Exception Handling
257
258
Kodein-DI defines several specific exception types for different error conditions:
259
260
```kotlin { .api }
261
class DI.NotFoundException(val key: Key<*, *, *>, message: String) : RuntimeException(message)
262
class DI.DependencyLoopException(message: String) : RuntimeException(message)
263
class DI.OverridingException(message: String) : RuntimeException(message)
264
class DI.NoResultException(val search: SearchSpecs, message: String) : RuntimeException(message)
265
class DI.UnusedParameterException(message: String, cause: Exception? = null) : RuntimeException(message, cause)
266
```
267
268
## Type System
269
270
```kotlin { .api }
271
data class DI.Key<in C : Any, in A, out T : Any>(
272
val contextType: TypeToken<in C>,
273
val argType: TypeToken<in A>,
274
val type: TypeToken<out T>,
275
val tag: Any?
276
)
277
278
interface Typed<A> {
279
val type: TypeToken<A>
280
val value: A
281
}
282
```