0
# Module Definition & Dependencies
1

2
DSL-based module definition system for declaring and organizing dependencies. Supports multiple definition types including singletons, factories, and scoped instances with type-safe dependency resolution.
3

4
## Capabilities
5

6
### Module Creation
7

8
Create modules to organize and declare dependencies using the DSL.
9

10
```kotlin { .api }
11
/**
12
 * Create a new Module with dependency definitions
13
 * @param createdAtStart - Whether to create instances at application start
14
 * @param moduleDeclaration - DSL block for defining dependencies
15
 * @return Module instance with defined dependencies
16
 */
17
fun module(createdAtStart: Boolean = false, moduleDeclaration: ModuleDeclaration): Module
18
```
19

20
**Usage Examples:**
21

22
```kotlin
23
import org.koin.dsl.module
24

25
// Basic module
26
val appModule = module {
27
    single<UserService> { UserServiceImpl() }
28
    factory<UserRepository> { UserRepositoryImpl() }
29
}
30

31
// Module with eager creation
32
val eagerModule = module(createdAtStart = true) {
33
    single<DatabaseConnection> { DatabaseConnectionImpl() }
34
}
35

36
// Module with dependencies
37
val serviceModule = module {
38
    single<Database> { PostgreSQLDatabase() }
39
    single<UserRepository> { UserRepositoryImpl(get()) }
40
    factory<UserService> { UserServiceImpl(get()) }
41
}
42
```
43

44
### Singleton Definitions
45

46
Define singleton instances that are created once and reused throughout the application.
47

48
```kotlin { .api }
49
/**
50
 * Define a singleton instance
51
 * @param qualifier - Optional qualifier to distinguish instances
52
 * @param createdAtStart - Whether to create instance at application start
53
 * @param definition - Factory function to create the instance
54
 * @return KoinDefinition for additional configuration
55
 */
56
inline fun <reified T> Module.single(
57
    qualifier: Qualifier? = null,
58
    createdAtStart: Boolean = false,
59
    noinline definition: Definition<T>
60
): KoinDefinition<T>
61

62
/**
63
 * Define a singleton using constructor reference (up to 22 parameters)
64
 * @param qualifier - Optional qualifier to distinguish instances
65
 * @param createdAtStart - Whether to create instance at application start
66
 * @return KoinDefinition for additional configuration
67
 */
68
inline fun <reified T> Module.singleOf(
69
    constructor: () -> T,
70
    qualifier: Qualifier? = null,
71
    createdAtStart: Boolean = false
72
): KoinDefinition<T>
73
```
74

75
**Usage Examples:**
76

77
```kotlin
78
import org.koin.dsl.module
79
import org.koin.core.qualifier.named
80

81
val singletonModule = module {
82
    // Simple singleton
83
    single<ApiService> { ApiServiceImpl() }
84
    
85
    // Singleton with dependencies
86
    single<UserRepository> { UserRepositoryImpl(get()) }
87
    
88
    // Singleton with qualifier
89
    single<Database>(named("primary")) { PostgreSQLDatabase() }
90
    single<Database>(named("cache")) { RedisDatabase() }
91
    
92
    // Eager singleton (created at startup)
93
    single<Logger>(createdAtStart = true) { LoggerImpl() }
94
    
95
    // Constructor reference singleton
96
    singleOf(::UserServiceImpl)
97
    singleOf(::ApiClientImpl, qualifier = named("v1"))
98
}
99
```
100

101
### Factory Definitions
102

103
Define factory instances that create a new instance every time they are requested.
104

105
```kotlin { .api }
106
/**
107
 * Define a factory instance (new instance per request)
108
 * @param qualifier - Optional qualifier to distinguish instances
109
 * @param definition - Factory function to create instances
110
 * @return KoinDefinition for additional configuration
111
 */
112
inline fun <reified T> Module.factory(
113
    qualifier: Qualifier? = null,
114
    noinline definition: Definition<T>
115
): KoinDefinition<T>
116

117
/**
118
 * Define a factory using constructor reference (up to 22 parameters)
119
 * @param qualifier - Optional qualifier to distinguish instances
120
 * @return KoinDefinition for additional configuration
121
 */
122
inline fun <reified T> Module.factoryOf(
123
    constructor: () -> T,
124
    qualifier: Qualifier? = null
125
): KoinDefinition<T>
126
```
127

128
**Usage Examples:**
129

130
```kotlin
131
import org.koin.dsl.module
132
import org.koin.core.qualifier.named
133

134
val factoryModule = module {
135
    // Simple factory
136
    factory<HttpClient> { HttpClientImpl() }
137
    
138
    // Factory with dependencies
139
    factory<OrderService> { OrderServiceImpl(get(), get()) }
140
    
141
    // Factory with qualifier
142
    factory<Validator>(named("email")) { EmailValidator() }
143
    factory<Validator>(named("phone")) { PhoneValidator() }
144
    
145
    // Constructor reference factory
146
    factoryOf(::RequestHandlerImpl)
147
    factoryOf(::DataProcessorImpl, qualifier = named("json"))
148
}
149
```
150

151
### Scoped Definitions
152

153
Define scoped instances that are tied to a specific scope lifecycle.
154

155
```kotlin { .api }
156
/**
157
 * Create scope definition block
158
 * @param qualifier - Scope qualifier
159
 * @param scopeSet - DSL block for defining scoped dependencies
160
 */
161
fun Module.scope(qualifier: Qualifier, scopeSet: ScopeDSL.() -> Unit)
162

163
class ScopeDSL {
164
    /**
165
     * Define a scoped instance
166
     * @param qualifier - Optional qualifier to distinguish instances
167
     * @param definition - Factory function to create the instance
168
     * @return KoinDefinition for additional configuration
169
     */
170
    inline fun <reified T> scoped(
171
        qualifier: Qualifier? = null,
172
        noinline definition: Definition<T>
173
    ): KoinDefinition<T>
174
    
175
    /**
176
     * Define a scoped instance using constructor reference
177
     * @param qualifier - Optional qualifier to distinguish instances
178
     * @return KoinDefinition for additional configuration
179
     */
180
    inline fun <reified T> scopedOf(
181
        constructor: () -> T,
182
        qualifier: Qualifier? = null
183
    ): KoinDefinition<T>
184
    
185
    /**
186
     * Define a factory instance within scope
187
     * @param qualifier - Optional qualifier to distinguish instances
188
     * @param definition - Factory function to create instances
189
     * @return KoinDefinition for additional configuration
190
     */
191
    inline fun <reified T> factory(
192
        qualifier: Qualifier? = null,
193
        noinline definition: Definition<T>
194
    ): KoinDefinition<T>
195
}
196
```
197

198
**Usage Examples:**
199

200
```kotlin
201
import org.koin.dsl.module
202
import org.koin.core.qualifier.named
203

204
// Define scope qualifier
205
val userScope = named<UserScope>()
206

207
val scopedModule = module {
208
    scope(userScope) {
209
        // Scoped instance - one per scope
210
        scoped<UserSession> { UserSessionImpl(get()) }
211
        
212
        // Factory within scope - new instance per request within scope
213
        factory<UserAction> { UserActionImpl(get()) }
214
        
215
        // Constructor reference scoped
216
        scopedOf(::UserPreferencesImpl)
217
    }
218
}
219
```
220

221
### Definition Binding
222

223
Bind additional types to existing definitions for interface/implementation mapping.
224

225
```kotlin { .api }
226
/**
227
 * Bind additional type to the definition
228
 * @param secondaryType - Additional type to bind
229
 * @return KoinDefinition for chaining
230
 */
231
inline fun <reified T, reified U> KoinDefinition<T>.bind(): KoinDefinition<T>
232

233
/**
234
 * Bind multiple types to the definition
235
 * @param types - Array of additional types to bind
236
 * @return KoinDefinition for chaining
237
 */
238
fun <T> KoinDefinition<T>.binds(vararg types: KClass<*>): KoinDefinition<T>
239

240
/**
241
 * Add close callback to the definition
242
 * @param onClose - Callback function executed when instance is closed
243
 * @return KoinDefinition for chaining
244
 */
245
fun <T> KoinDefinition<T>.onClose(onClose: OnCloseCallback<T>): KoinDefinition<T>
246
```
247

248
**Usage Examples:**
249

250
```kotlin
251
import org.koin.dsl.module
252

253
val bindingModule = module {
254
    // Bind interface to implementation
255
    single<UserRepositoryImpl> { UserRepositoryImpl(get()) }
256
        .bind<UserRepository>()
257
    
258
    // Bind multiple interfaces
259
    single<DatabaseServiceImpl> { DatabaseServiceImpl() }
260
        .binds(arrayOf(DatabaseService::class, HealthCheckable::class))
261
    
262
    // Add close callback
263
    single<ConnectionPool> { ConnectionPoolImpl() }
264
        .onClose { pool -> pool.closeAllConnections() }
265
}
266
```
267

268
### Module Composition
269

270
Combine and organize modules using module operations.
271

272
```kotlin { .api }
273
class Module {
274
    /**
275
     * Include other modules in this module
276
     * @param modules - Modules to include
277
     */
278
    fun includes(vararg modules: Module): Module
279
    
280
    /**
281
     * Add this module to another module
282
     * @param module - Target module
283
     * @return Combined module
284
     */
285
    operator fun plus(module: Module): Module
286
}
287
```
288

289
**Usage Examples:**
290

291
```kotlin
292
import org.koin.dsl.module
293

294
val coreModule = module {
295
    single<Logger> { LoggerImpl() }
296
}
297

298
val dataModule = module {
299
    single<Database> { DatabaseImpl() }
300
}
301

302
val serviceModule = module {
303
    includes(coreModule, dataModule)
304
    single<UserService> { UserServiceImpl(get(), get()) }
305
}
306

307
// Module composition with plus operator
308
val combinedModule = coreModule + dataModule + serviceModule
309
```
310

311
## Types
312

313
```kotlin { .api }
314
typealias ModuleDeclaration = Module.() -> Unit
315
typealias Definition<T> = Scope.(ParametersHolder) -> T
316
typealias OnCloseCallback<T> = (T?) -> Unit
317

318
class Module(val createdAtStart: Boolean = false) {
319
    val id: String
320
    val isLoaded: Boolean
321
}
322

323
class KoinDefinition<T>(
324
    val qualifier: Qualifier?,
325
    val definition: Definition<T>,
326
    val kind: Kind,
327
    val secondaryTypes: List<KClass<*>>
328
) {
329
    enum class Kind { Single, Factory, Scoped }
330
}
331

332
class ScopeDSL(val qualifier: Qualifier, val module: Module)
333
```