Module Definition

/**
 * Creates a new dependency module with DSL configuration
 * @param createdAtStart - Whether module definitions should be created at application start (default: false)
 * @param moduleDeclaration - DSL block for defining dependencies
 * @return Module instance containing the defined dependencies
 */
fun module(createdAtStart: Boolean = false, moduleDeclaration: ModuleDeclaration): Module

import org.koin.dsl.module

// Basic module
val appModule = module {
    single { UserService() }
    factory { UserController(get()) }
}

// Module with eager creation
val coreModule = module(createdAtStart = true) {
    single { DatabaseClient() }
    single { ConfigService() }
}

class Module {
    /** Unique identifier for this module */
    val id: String
    
    /** Whether this module has been loaded into a Koin application */
    val isLoaded: Boolean
    
    /**
     * Define a singleton dependency
     * @param qualifier - Optional qualifier to distinguish multiple instances of the same type
     * @param createdAtStart - Whether to create this instance at application start
     * @param definition - Factory function that creates the instance
     * @return KoinDefinition for additional configuration
     */
    inline fun <reified T> single(qualifier: Qualifier? = null, createdAtStart: Boolean = false, noinline definition: Definition<T>): KoinDefinition<T>
    
    /**
     * Define a factory dependency (new instance on each request)
     * @param qualifier - Optional qualifier to distinguish multiple instances of the same type
     * @param definition - Factory function that creates the instance
     * @return KoinDefinition for additional configuration
     */
    inline fun <reified T> factory(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
    
    /**
     * Define a scope with qualifier
     * @param qualifier - Scope qualifier
     * @param scopeSet - DSL block for defining scoped dependencies
     */
    fun scope(qualifier: Qualifier, scopeSet: ScopeDSL.() -> Unit)
    
    /**
     * Define a scope with type qualifier
     * @param scopeSet - DSL block for defining scoped dependencies
     */
    inline fun <reified T> scope(scopeSet: ScopeDSL.() -> Unit)
    
    /**
     * Include other modules in this module
     * @param module - Variable number of modules to include
     */
    fun includes(vararg module: Module)
    
    /**
     * Include a collection of modules in this module
     * @param module - Collection of modules to include
     */
    fun includes(module: Collection<Module>)
    
    /**
     * Combine this module with another module
     * @param module - Module to combine with
     * @return List containing both modules
     */
    operator fun plus(module: Module): List<Module>
    
    /**
     * Combine this module with a list of modules
     * @param modules - List of modules to combine with
     * @return List containing all modules
     */
    operator fun plus(modules: List<Module>): List<Module>
}

import org.koin.dsl.module
import org.koin.core.qualifier.named

// Service definitions
class UserService(private val database: DatabaseClient)
class UserController(private val userService: UserService)
class DatabaseClient(private val url: String)

// Module with various definition types
val appModule = module {
    // Singleton - same instance shared
    single { DatabaseClient(getProperty("db.url")) }
    
    // Singleton with qualifier
    single(named("primary")) { UserService(get()) }
    
    // Factory - new instance each time
    factory { UserController(get(named("primary"))) }
    
    // Eager singleton - created at startup
    single(createdAtStart = true) { LoggingService() }
}

// Module composition
val databaseModule = module {
    single { DatabaseClient(getProperty("db.url")) }
}

val serviceModule = module {
    single { UserService(get()) }
    factory { UserController(get()) }
}

// Combine modules
val fullModule = databaseModule + serviceModule

// Include modules
val mainModule = module {
    includes(databaseModule, serviceModule)
    single { ApplicationService(get(), get()) }
}

class ScopeDSL {
    /** Qualifier of the scope being defined */
    val scopeQualifier: Qualifier
    
    /** Parent module containing this scope */
    val module: Module
    
    /**
     * Define a scoped dependency (lifecycle tied to scope)
     * @param qualifier - Optional qualifier
     * @param definition - Factory function for the scoped instance
     * @return KoinDefinition for additional configuration
     */
    inline fun <reified T> scoped(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
    
    /**
     * Define a factory dependency within the scope
     * @param qualifier - Optional qualifier
     * @param definition - Factory function for the instance
     * @return KoinDefinition for additional configuration
     */
    inline fun <reified T> factory(qualifier: Qualifier? = null, noinline definition: Definition<T>): KoinDefinition<T>
}

import org.koin.dsl.module
import org.koin.core.qualifier.named

// Module with scoped dependencies
val webModule = module {
    // Define a scope for web requests
    scope<WebRequestScope> {
        scoped { RequestContext() }
        scoped { UserSession(get()) }
        factory { RequestLogger(get()) }
    }
    
    // Named scope
    scope(named("api")) {
        scoped { ApiContext() }
        scoped { ApiValidator(get()) }
    }
}

// Usage in components
class WebController : KoinScopeComponent {
    override val scope: Scope by lazy { 
        getKoin().createScope<WebRequestScope>("request-${generateId()}")
    }
    
    private val requestContext: RequestContext by scope.inject()
    private val userSession: UserSession by scope.inject()
}

/**
 * Bind a definition to an additional class type
 * @param clazz - Class to bind to
 * @return Same KoinDefinition for chaining
 */
infix fun <S : Any> KoinDefinition<out S>.bind(clazz: KClass<S>): KoinDefinition<out S>

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

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

/**
 * Add close callback to definition
 * @param onClose - Callback function called when instance is closed
 * @return Same KoinDefinition for chaining
 */
infix fun <T> KoinDefinition<T>.onClose(onClose: OnCloseCallback<T>): KoinDefinition<T>

import org.koin.dsl.module
import org.koin.dsl.bind

interface UserRepository
interface NotificationService

class DatabaseUserRepository : UserRepository
class EmailNotificationService : NotificationService

val serviceModule = module {
    // Bind to interface
    single { DatabaseUserRepository() } bind UserRepository::class
    
    // Bind using reified type
    single { EmailNotificationService() }.bind<NotificationService>()
    
    // Bind to multiple types
    single { CompositeService() } binds arrayOf(ServiceA::class, ServiceB::class)
    
    // Add close callback
    single { ResourceManager() } onClose { resource ->
        resource.cleanup()
    }
}

/**
 * Type alias for module configuration DSL blocks
 */
typealias ModuleDeclaration = Module.() -> Unit

/**
 * Type alias for dependency definition functions
 */
typealias Definition<T> = Scope.() -> T

/**
 * Type alias for close callback functions
 */
typealias OnCloseCallback<T> = (T) -> Unit

/**
 * Container for dependency definition with metadata
 */
class KoinDefinition<T> {
    /** Parent module containing this definition */
    val module: Module
    
    /** Instance factory for creating instances */
    val factory: InstanceFactory<T>
}

/**
 * Marker class for scope archetypes
 */
class ScopeArchetype