0
# Koin Core
1

2
Koin is a pragmatic lightweight dependency injection framework for Kotlin developers. It provides a simple, pragmatic approach to dependency injection using a Kotlin DSL and works seamlessly across all Kotlin platforms including JVM, Android, JavaScript, and Native targets.
3

4
## Package Information
5

6
- **Package Name**: koin-core
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Maven Coordinates**: `io.insert-koin:koin-core:4.1.0`
10
- **Installation**: Add to your Kotlin project's dependencies
11

12
For Gradle:
13
```kotlin
14
implementation("io.insert-koin:koin-core:4.1.0")
15
```
16

17
For Maven:
18
```xml
19
<dependency>
20
  <groupId>io.insert-koin</groupId>
21
  <artifactId>koin-core</artifactId>
22
  <version>4.1.0</version>
23
</dependency>
24
```
25

26
## Core Imports
27

28
```kotlin
29
import org.koin.core.KoinApplication
30
import org.koin.core.component.KoinComponent
31
import org.koin.core.component.inject
32
import org.koin.core.context.startKoin  // JVM/Android only
33
import org.koin.dsl.module
34
```
35

36
## Basic Usage
37

38
```kotlin
39
import org.koin.core.component.KoinComponent
40
import org.koin.core.component.inject
41
import org.koin.core.context.startKoin
42
import org.koin.dsl.module
43

44
// Define your services
45
interface Repository
46
class DatabaseRepository : Repository
47

48
interface Service
49
class BusinessService(private val repository: Repository) : Service
50

51
// Define a module
52
val appModule = module {
53
    single<Repository> { DatabaseRepository() }
54
    single<Service> { BusinessService(get()) }
55
}
56

57
// Start Koin
58
fun main() {
59
    startKoin {
60
        modules(appModule)
61
    }
62
}
63

64
// Use dependency injection in your components
65
class MyController : KoinComponent {
66
    private val service: Service by inject()
67
    
68
    fun doSomething() {
69
        // Use injected service
70
    }
71
}
72
```
73

74
## Architecture
75

76
Koin is built around several key concepts:
77

78
- **Modules**: Containers that group related dependency definitions
79
- **DSL**: Kotlin DSL for declaring dependencies (`single`, `factory`, `scoped`)
80
- **Components**: `KoinComponent` interface for classes that need dependency injection
81
- **Application**: `KoinApplication` class for configuring and starting the DI container
82
- **Scopes**: Lifecycle-aware dependency containers for managing object lifetimes
83
- **Qualifiers**: Named or typed identifiers for distinguishing between multiple implementations
84

85
## Capabilities
86

87
### Module Definition and DSL
88

89
Core DSL for defining dependency injection modules with singleton, factory, and scoped lifecycles.
90

91
```kotlin { .api }
92
fun module(createdAtStart: Boolean = false, moduleDeclaration: Module.() -> Unit): Module
93

94
// Within a module
95
inline fun <reified T> single(
96
    qualifier: Qualifier? = null,
97
    createdAtStart: Boolean = false,
98
    noinline definition: Definition<T>
99
): KoinDefinition<T>
100

101
inline fun <reified T> factory(
102
    qualifier: Qualifier? = null,
103
    noinline definition: Definition<T>
104
): KoinDefinition<T>
105
```
106

107
[Module DSL and Definition](./module-dsl.md)
108

109
### Component Integration
110

111
Provides `KoinComponent` interface and extension functions for easy dependency injection into Kotlin classes.
112

113
```kotlin { .api }
114
interface KoinComponent {
115
    fun getKoin(): Koin
116
}
117

118
inline fun <reified T : Any> KoinComponent.get(
119
    qualifier: Qualifier? = null,
120
    noinline parameters: ParametersDefinition? = null
121
): T
122

123
inline fun <reified T : Any> KoinComponent.inject(
124
    qualifier: Qualifier? = null,
125
    mode: LazyThreadSafetyMode = KoinPlatformTools.defaultLazyMode(),
126
    noinline parameters: ParametersDefinition? = null
127
): Lazy<T>
128
```
129

130
[Component Integration](./components.md)
131

132
### Scoped Dependencies
133

134
Lifecycle-aware dependency management for controlling object creation and destruction within specific scopes.
135

136
```kotlin { .api }
137
interface KoinScopeComponent : KoinComponent {
138
    val scope: Scope
139
}
140

141
class Scope {
142
    inline fun <reified T> get(
143
        qualifier: Qualifier? = null,
144
        noinline parameters: ParametersDefinition? = null
145
    ): T
146
    
147
    fun close()
148
}
149
```
150

151
[Scoped Dependencies](./scopes.md)
152

153
### Application Configuration
154

155
`KoinApplication` class for configuring modules, properties, logging, and starting the dependency injection container.
156

157
```kotlin { .api }
158
fun koinApplication(
159
    createEagerInstances: Boolean = true,
160
    appDeclaration: KoinAppDeclaration? = null
161
): KoinApplication
162

163
class KoinApplication {
164
    fun modules(modules: List<Module>): KoinApplication
165
    fun properties(values: Map<String, Any>): KoinApplication
166
    fun logger(logger: Logger): KoinApplication
167
    fun createEagerInstances()
168
}
169
```
170

171
[Application Configuration](./application.md)
172

173
### Global Context (Platform Specific)
174

175
Global dependency injection context management for simplified usage patterns. Available on JVM/Android platforms.
176

177
```kotlin { .api }
178
interface KoinContext {
179
    fun get(): Koin
180
    fun getOrNull(): Koin?
181
    fun startKoin(koinApplication: KoinApplication): KoinApplication
182
    fun startKoin(appDeclaration: KoinAppDeclaration): KoinApplication
183
    fun stopKoin()
184
    fun loadKoinModules(module: Module, createEagerInstances: Boolean = false)
185
    fun unloadKoinModules(module: Module)
186
}
187

188
// Platform-specific global functions (JVM/Android)
189
fun startKoin(appDeclaration: KoinAppDeclaration): KoinApplication
190
fun stopKoin()
191
```
192

193
*Note: Global context functions are platform-specific and may not be available on all Kotlin targets.*
194

195
## Type Definitions
196

197
```kotlin { .api }
198
typealias Definition<T> = Scope.(ParametersDefinition?) -> T
199
typealias ModuleDeclaration = Module.() -> Unit
200
typealias KoinAppDeclaration = KoinApplication.() -> Unit
201
typealias ParametersDefinition = () -> ParametersHolder
202
typealias ScopeID = String
203

204
interface Qualifier {
205
    val value: String
206
}
207

208
class StringQualifier(override val value: String) : Qualifier
209
class TypeQualifier(val kclass: KClass<*>) : Qualifier
210

211
enum class Kind {
212
    Singleton, Factory, Scoped
213
}
214

215
enum class Level {
216
    DEBUG, INFO, WARNING, ERROR, NONE
217
}
218

219
// Utility functions
220
fun named(name: String): StringQualifier
221
fun parametersOf(vararg parameters: Any?): ParametersHolder
222
```
223

224
## Error Types
225

226
```kotlin { .api }
227
class KoinApplicationAlreadyStartedException : RuntimeException
228
class ClosedScopeException : RuntimeException
229
class DefinitionOverrideException : RuntimeException
230
class InstanceCreationException(message: String, cause: Exception?) : RuntimeException
231
class NoDefinitionFoundException : RuntimeException
232
class ScopeNotCreatedException : RuntimeException
233
class ScopeAlreadyCreatedException : RuntimeException
234
class MissingPropertyException : RuntimeException
235
class NoParameterFoundException : RuntimeException
236
class NoPropertyFileFoundException : RuntimeException
237
class NoScopeDefFoundException : RuntimeException
238
class MissingScopeValueException : RuntimeException
239
class DefinitionParameterException : RuntimeException
240
```