0
# Koin Core - Dependency Injection Framework
1
2
Koin Core is a pragmatic lightweight dependency injection framework for Kotlin Multiplatform applications with iOS Simulator ARM64 target support. It provides a simple DSL to declare your application components and manages their lifecycle automatically.
3
4
## Overview
5
6
Koin Core offers several key capabilities for dependency injection:
7
8
- **Application Setup & Configuration** - Initialize and configure your Koin context
9
- **Core Dependency Injection** - Inject dependencies throughout your application
10
- **Module System & Definitions** - Organize dependencies into reusable modules
11
- **Scope Management** - Manage component lifecycles with scoped dependencies
12
- **Component Integration** - Integrate DI into your classes with component interfaces
13
- **Qualifiers & Parameters** - Distinguish between similar dependencies and pass parameters
14
- **Error Handling** - Comprehensive exception system for DI failures
15
16
## Quick Start
17
18
```kotlin { .api }
19
import org.koin.core.Koin
20
import org.koin.core.KoinApplication
21
import org.koin.dsl.*
22
23
// Define a module
24
val appModule = module {
25
single<Repository> { DatabaseRepository() }
26
factory<UseCase> { GetDataUseCase(get()) }
27
}
28
29
// Start Koin
30
val koinApp = koinApplication {
31
modules(appModule)
32
}
33
34
// Get dependencies
35
val repository: Repository = koinApp.koin.get()
36
```
37
38
## Application Setup & Configuration
39
40
Koin applications are configured using `KoinApplication` which provides the main entry point and configuration options.
41
42
### Core Application Functions
43
44
```kotlin { .api }
45
// Create and configure a Koin application
46
fun koinApplication(
47
createEagerInstances: Boolean = true,
48
appDeclaration: KoinAppDeclaration? = null
49
): KoinApplication
50
51
fun koinApplication(appDeclaration: KoinAppDeclaration?): KoinApplication
52
fun koinApplication(configuration: KoinConfiguration?): KoinApplication
53
fun koinApplication(createEagerInstances: Boolean): KoinApplication
54
55
// Type aliases
56
typealias KoinAppDeclaration = KoinApplication.() -> Unit
57
```
58
59
### KoinApplication Class
60
61
```kotlin { .api }
62
class KoinApplication {
63
val koin: Koin
64
65
// Module management
66
fun modules(modules: Module): KoinApplication
67
fun modules(vararg modules: Module): KoinApplication
68
fun modules(modules: List<Module>): KoinApplication
69
70
// Configuration
71
fun allowOverride(override: Boolean): Unit
72
fun properties(values: Map<String, Any>): KoinApplication
73
fun logger(logger: Logger): KoinApplication
74
fun printLogger(level: Level = Level.INFO): KoinApplication
75
fun options(vararg optionValue: Pair<KoinOption, Any>): KoinApplication
76
77
// Lifecycle
78
fun createEagerInstances(): Unit
79
fun close(): Unit
80
81
companion object {
82
fun init(): KoinApplication
83
}
84
}
85
```
86
87
**→ [Application Setup & Configuration](application-setup.md)**
88
89
## Core Dependency Injection
90
91
The `Koin` class provides the main dependency resolution and injection capabilities.
92
93
### Primary Injection Methods
94
95
```kotlin { .api }
96
class Koin {
97
// Direct resolution
98
inline fun <reified T : Any> get(
99
qualifier: Qualifier? = null,
100
noinline parameters: ParametersDefinition? = null
101
): T
102
103
// Lazy injection
104
inline fun <reified T : Any> inject(
105
qualifier: Qualifier? = null,
106
mode: LazyThreadSafetyMode = KoinPlatformTools.defaultLazyMode(),
107
noinline parameters: ParametersDefinition? = null
108
): Lazy<T>
109
110
// Nullable variants
111
inline fun <reified T : Any> getOrNull(/* ... */): T?
112
inline fun <reified T : Any> injectOrNull(/* ... */): Lazy<T?>
113
114
// Non-reified variants
115
fun <T> get(clazz: KClass<*>, qualifier: Qualifier?, parameters: ParametersDefinition?): T
116
fun <T> getOrNull(clazz: KClass<*>, qualifier: Qualifier?, parameters: ParametersDefinition?): T?
117
118
// Collections
119
inline fun <reified T> getAll(): List<T>
120
121
// Instance declaration
122
inline fun <reified T> declare(
123
instance: T,
124
qualifier: Qualifier? = null,
125
secondaryTypes: List<KClass<*>> = emptyList(),
126
allowOverride: Boolean = true
127
)
128
129
// Property management
130
fun <T : Any> getProperty(key: String, defaultValue: T): T
131
fun <T : Any> getProperty(key: String): T?
132
fun setProperty(key: String, value: Any)
133
fun deleteProperty(key: String)
134
135
// Scope management
136
fun deleteScope(scopeId: ScopeID)
137
fun getScopeOrNull(scopeId: ScopeID): Scope?
138
139
// Module management
140
fun loadModules(modules: List<Module>, allowOverride: Boolean = true, createEagerInstances: Boolean = false)
141
fun unloadModules(modules: List<Module>)
142
}
143
```
144
145
**→ [Core Dependency Injection](dependency-injection.md)**
146
147
## Module System & Definitions
148
149
Modules organize your dependencies using a simple DSL for defining singletons, factories, and scoped instances.
150
151
### Module Creation
152
153
```kotlin { .api }
154
// Create module
155
fun module(createdAtStart: Boolean = false, moduleDeclaration: ModuleDeclaration): Module
156
157
typealias ModuleDeclaration = Module.() -> Unit
158
```
159
160
### Definition DSL
161
162
```kotlin { .api }
163
class Module {
164
val id: String
165
val isLoaded: Boolean
166
var eagerInstances: LinkedHashSet<SingleInstanceFactory<*>>
167
168
// Core definitions
169
inline fun <reified T> single(
170
qualifier: Qualifier? = null,
171
createdAtStart: Boolean = false,
172
definition: Definition<T>
173
): KoinDefinition<T>
174
175
inline fun <reified T> factory(
176
qualifier: Qualifier? = null,
177
definition: Definition<T>
178
): KoinDefinition<T>
179
180
// Scope definitions
181
fun scope(qualifier: Qualifier, scopeSet: ScopeDSL.() -> Unit)
182
inline fun <reified T> scope(scopeSet: ScopeDSL.() -> Unit)
183
184
// Module composition
185
fun includes(vararg module: Module)
186
fun includes(module: Collection<Module>)
187
operator fun plus(module: Module): List<Module>
188
}
189
190
// Type aliases
191
typealias Definition<T> = Scope.(ParametersHolder) -> T
192
```
193
194
**→ [Module System & Definitions](modules-and-definitions.md)**
195
196
## Scope Management
197
198
Scopes provide lifecycle management for dependencies, allowing you to create and destroy sets of related instances.
199
200
### Scope Class
201
202
```kotlin { .api }
203
class Scope {
204
val scopeQualifier: Qualifier
205
val id: ScopeID
206
val isRoot: Boolean
207
val closed: Boolean
208
209
// Resolution methods
210
inline fun <reified T : Any> inject(/* ... */): Lazy<T>
211
inline fun <reified T : Any> get(/* ... */): T
212
inline fun <reified T : Any> getAll(): List<T>
213
214
// Scope operations
215
fun linkTo(vararg scopes: Scope)
216
fun unlink(vararg scopes: Scope)
217
fun close()
218
}
219
220
typealias ScopeID = String
221
```
222
223
### Scope DSL
224
225
```kotlin { .api }
226
class ScopeDSL {
227
inline fun <reified T> scoped(
228
qualifier: Qualifier? = null,
229
definition: Definition<T>
230
): KoinDefinition<T>
231
232
inline fun <reified T> factory(
233
qualifier: Qualifier? = null,
234
definition: Definition<T>
235
): KoinDefinition<T>
236
}
237
```
238
239
**→ [Scope Management](scoping.md)**
240
241
## Component Integration
242
243
Component interfaces provide automatic dependency injection capabilities to your classes.
244
245
### Core Component Interfaces
246
247
```kotlin { .api }
248
interface KoinComponent {
249
fun getKoin(): Koin
250
}
251
252
interface KoinScopeComponent : KoinComponent {
253
val scope: Scope
254
}
255
256
// Extension functions for KoinComponent
257
inline fun <reified T : Any> KoinComponent.get(/* ... */): T
258
inline fun <reified T : Any> KoinComponent.inject(/* ... */): Lazy<T>
259
260
// Extension functions for KoinScopeComponent
261
fun <T : Any> T.getScopeId(): String
262
fun <T : Any> T.getScopeName(): TypeQualifier
263
fun <T : KoinScopeComponent> T.createScope(/* ... */): Scope
264
```
265
266
**→ [Component Integration](components.md)**
267
268
## Qualifiers & Parameters
269
270
Qualifiers distinguish between different instances of the same type, while parameters allow passing runtime values during injection.
271
272
### Qualifier System
273
274
```kotlin { .api }
275
interface Qualifier {
276
val value: QualifierValue
277
}
278
279
typealias QualifierValue = String
280
281
// Qualifier creation functions
282
fun named(name: String): StringQualifier
283
fun <E : Enum<E>> named(enum: Enum<E>): Qualifier
284
fun qualifier(name: String): StringQualifier
285
inline fun <reified T> named(): TypeQualifier
286
fun _q(name: String): StringQualifier
287
288
// Qualifier implementations
289
class StringQualifier : Qualifier
290
class TypeQualifier : Qualifier
291
```
292
293
### Parameter System
294
295
```kotlin { .api }
296
class ParametersHolder {
297
val values: List<Any?>
298
var index: Int
299
300
// Access methods
301
operator fun <T> get(i: Int): T
302
inline fun <reified T : Any> get(): T
303
inline operator fun <reified T> component1(): T // through component5()
304
305
// Utility methods
306
fun size(): Int
307
fun isEmpty(): Boolean
308
fun add(value: Any): ParametersHolder
309
}
310
311
// Parameter creation functions
312
fun parametersOf(vararg parameters: Any?): ParametersHolder
313
fun emptyParametersHolder(): ParametersHolder
314
315
typealias ParametersDefinition = () -> ParametersHolder
316
```
317
318
**→ [Qualifiers & Parameters](qualifiers-parameters.md)**
319
320
## Error Handling
321
322
Koin provides comprehensive exception handling for dependency injection failures.
323
324
### Core Exception Types
325
326
```kotlin { .api }
327
// Resolution failures
328
class NoDefinitionFoundException : RuntimeException
329
class InstanceCreationException : RuntimeException
330
class NoParameterFoundException : RuntimeException
331
332
// Scope failures
333
class ClosedScopeException : RuntimeException
334
class ScopeNotCreatedException : RuntimeException
335
class ScopeAlreadyCreatedException : RuntimeException
336
class NoScopeDefFoundException : RuntimeException
337
class MissingScopeValueException : RuntimeException
338
339
// Configuration failures
340
class DefinitionOverrideException : RuntimeException
341
class DefinitionParameterException : RuntimeException
342
class MissingPropertyException : RuntimeException
343
class NoPropertyFileFoundException : RuntimeException
344
class KoinApplicationAlreadyStartedException : RuntimeException
345
```
346
347
**→ [Error Handling](error-handling.md)**
348
349
## Platform Integration
350
351
```kotlin { .api }
352
// Platform-specific utilities
353
object KoinPlatformTools {
354
fun defaultLazyMode(): LazyThreadSafetyMode
355
fun generateId(): String
356
}
357
358
// Thread-local storage
359
expect class ThreadLocal<T>
360
361
// Time utilities
362
class KoinPlatformTimeTools
363
```
364
365
This comprehensive framework enables clean, testable dependency injection across your Kotlin Multiplatform applications with minimal boilerplate and maximum flexibility.