0
# Module Definition
1

2
DSL-based module system for organizing and defining dependencies with lifecycle management.
3

4
## Capabilities
5

6
### Module Creation
7

8
Creates a new dependency module with DSL configuration.
9

10
```kotlin { .api }
11
/**
12
 * Creates a new dependency module with DSL configuration
13
 * @param createdAtStart - Whether module definitions should be created at application start (default: false)
14
 * @param moduleDeclaration - DSL block for defining dependencies
15
 * @return Module instance containing the 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() }
28
    factory { UserController(get()) }
29
}
30

31
// Module with eager creation
32
val coreModule = module(createdAtStart = true) {
33
    single { DatabaseClient() }
34
    single { ConfigService() }
35
}
36
```
37

38
### Module Class
39

40
Container for dependency definitions with composition and lifecycle management.
41

42
```kotlin { .api }
43
class Module {
44
    /** Unique identifier for this module */
45
    val id: String
46
    
47
    /** Whether this module has been loaded into a Koin application */
48
    val isLoaded: Boolean
49
    
50
    /**
51
     * Define a singleton dependency
52
     * @param qualifier - Optional qualifier to distinguish multiple instances of the same type
53
     * @param createdAtStart - Whether to create this instance at application start
54
     * @param definition - Factory function that creates the instance
55
     * @return KoinDefinition for additional configuration
56
     */
57
    inline fun <reified T> single(qualifier: Qualifier? = null, createdAtStart: Boolean = false, noinline definition: Definition<T>): KoinDefinition<T>
58
    
59
    /**
60
     * Define a factory dependency (new instance on each request)
61
     * @param qualifier - Optional qualifier to distinguish multiple instances of the same type
62
     * @param definition - Factory function that creates the instance
63
     * @return KoinDefinition for additional configuration
64
     */
65
    inline fun <reified T> factory(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
66
    
67
    /**
68
     * Define a scope with qualifier
69
     * @param qualifier - Scope qualifier
70
     * @param scopeSet - DSL block for defining scoped dependencies
71
     */
72
    fun scope(qualifier: Qualifier, scopeSet: ScopeDSL.() -> Unit)
73
    
74
    /**
75
     * Define a scope with type qualifier
76
     * @param scopeSet - DSL block for defining scoped dependencies
77
     */
78
    inline fun <reified T> scope(scopeSet: ScopeDSL.() -> Unit)
79
    
80
    /**
81
     * Include other modules in this module
82
     * @param module - Variable number of modules to include
83
     */
84
    fun includes(vararg module: Module)
85
    
86
    /**
87
     * Include a collection of modules in this module
88
     * @param module - Collection of modules to include
89
     */
90
    fun includes(module: Collection<Module>)
91
    
92
    /**
93
     * Combine this module with another module
94
     * @param module - Module to combine with
95
     * @return List containing both modules
96
     */
97
    operator fun plus(module: Module): List<Module>
98
    
99
    /**
100
     * Combine this module with a list of modules
101
     * @param modules - List of modules to combine with
102
     * @return List containing all modules
103
     */
104
    operator fun plus(modules: List<Module>): List<Module>
105
}
106
```
107

108
**Usage Examples:**
109

110
```kotlin
111
import org.koin.dsl.module
112
import org.koin.core.qualifier.named
113

114
// Service definitions
115
class UserService(private val database: DatabaseClient)
116
class UserController(private val userService: UserService)
117
class DatabaseClient(private val url: String)
118

119
// Module with various definition types
120
val appModule = module {
121
    // Singleton - same instance shared
122
    single { DatabaseClient(getProperty("db.url")) }
123
    
124
    // Singleton with qualifier
125
    single(named("primary")) { UserService(get()) }
126
    
127
    // Factory - new instance each time
128
    factory { UserController(get(named("primary"))) }
129
    
130
    // Eager singleton - created at startup
131
    single(createdAtStart = true) { LoggingService() }
132
}
133

134
// Module composition
135
val databaseModule = module {
136
    single { DatabaseClient(getProperty("db.url")) }
137
}
138

139
val serviceModule = module {
140
    single { UserService(get()) }
141
    factory { UserController(get()) }
142
}
143

144
// Combine modules
145
val fullModule = databaseModule + serviceModule
146

147
// Include modules
148
val mainModule = module {
149
    includes(databaseModule, serviceModule)
150
    single { ApplicationService(get(), get()) }
151
}
152
```
153

154
### Scope Definition
155

156
DSL for defining scoped dependencies within modules.
157

158
```kotlin { .api }
159
class ScopeDSL {
160
    /** Qualifier of the scope being defined */
161
    val scopeQualifier: Qualifier
162
    
163
    /** Parent module containing this scope */
164
    val module: Module
165
    
166
    /**
167
     * Define a scoped dependency (lifecycle tied to scope)
168
     * @param qualifier - Optional qualifier
169
     * @param definition - Factory function for the scoped instance
170
     * @return KoinDefinition for additional configuration
171
     */
172
    inline fun <reified T> scoped(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
173
    
174
    /**
175
     * Define a factory dependency within the scope
176
     * @param qualifier - Optional qualifier
177
     * @param definition - Factory function for the instance
178
     * @return KoinDefinition for additional configuration
179
     */
180
    inline fun <reified T> factory(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
181
}
182
```
183

184
**Usage Examples:**
185

186
```kotlin
187
import org.koin.dsl.module
188
import org.koin.core.qualifier.named
189

190
// Module with scoped dependencies
191
val webModule = module {
192
    // Define a scope for web requests
193
    scope<WebRequestScope> {
194
        scoped { RequestContext() }
195
        scoped { UserSession(get()) }
196
        factory { RequestLogger(get()) }
197
    }
198
    
199
    // Named scope
200
    scope(named("api")) {
201
        scoped { ApiContext() }
202
        scoped { ApiValidator(get()) }
203
    }
204
}
205

206
// Usage in components
207
class WebController : KoinScopeComponent {
208
    override val scope: Scope by lazy { 
209
        getKoin().createScope<WebRequestScope>("request-${generateId()}")
210
    }
211
    
212
    private val requestContext: RequestContext by scope.inject()
213
    private val userSession: UserSession by scope.inject()
214
}
215
```
216

217
### Definition Binding
218

219
Bind definitions to additional types for polymorphic resolution.
220

221
```kotlin { .api }
222
/**
223
 * Bind a definition to an additional class type
224
 * @param clazz - Class to bind to
225
 * @return Same KoinDefinition for chaining
226
 */
227
infix fun <S : Any> KoinDefinition<out S>.bind(clazz: KClass<S>): KoinDefinition<out S>
228

229
/**
230
 * Bind a definition to an additional reified type
231
 * @return Same KoinDefinition for chaining
232
 */
233
inline fun <reified S : Any> KoinDefinition<out S>.bind(): KoinDefinition<out S>
234

235
/**
236
 * Bind a definition to multiple class types
237
 * @param classes - Array of classes to bind to
238
 * @return Same KoinDefinition for chaining
239
 */
240
infix fun KoinDefinition<*>.binds(classes: Array<KClass<*>>): KoinDefinition<*>
241

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

250
**Usage Examples:**
251

252
```kotlin
253
import org.koin.dsl.module
254
import org.koin.dsl.bind
255

256
interface UserRepository
257
interface NotificationService
258

259
class DatabaseUserRepository : UserRepository
260
class EmailNotificationService : NotificationService
261

262
val serviceModule = module {
263
    // Bind to interface
264
    single { DatabaseUserRepository() } bind UserRepository::class
265
    
266
    // Bind using reified type
267
    single { EmailNotificationService() }.bind<NotificationService>()
268
    
269
    // Bind to multiple types
270
    single { CompositeService() } binds arrayOf(ServiceA::class, ServiceB::class)
271
    
272
    // Add close callback
273
    single { ResourceManager() } onClose { resource ->
274
        resource.cleanup()
275
    }
276
}
277
```
278

279
## Type Definitions
280

281
```kotlin { .api }
282
/**
283
 * Type alias for module configuration DSL blocks
284
 */
285
typealias ModuleDeclaration = Module.() -> Unit
286

287
/**
288
 * Type alias for dependency definition functions
289
 */
290
typealias Definition<T> = Scope.() -> T
291

292
/**
293
 * Type alias for close callback functions
294
 */
295
typealias OnCloseCallback<T> = (T) -> Unit
296

297
/**
298
 * Container for dependency definition with metadata
299
 */
300
class KoinDefinition<T> {
301
    /** Parent module containing this definition */
302
    val module: Module
303
    
304
    /** Instance factory for creating instances */
305
    val factory: InstanceFactory<T>
306
}
307

308
/**
309
 * Marker class for scope archetypes
310
 */
311
class ScopeArchetype
312
```