Merge pull request #300 from InsertKoinIO/feat_safety_check_rework

Merge features - Jsr330 compat, Scope Archetypes, Configuration & Application boostrap

Author: arnaudgiuliani

docs/reference/koin-annotations/definitions.md

@@ -207,3 +207,137 @@ public class ComponentWithProps(
 ```
 
 The generated DSL equivalent will be `factory { ComponentWithProps(getProperty("id", ComponentWithProps.DEFAAULT_ID)) }`
+
+## JSR-330 Compatibility Annotations
+
+Koin Annotations provides JSR-330 (Jakarta Inject) compatible annotations through the `koin-jsr330` module. These annotations are particularly useful for developers migrating from other JSR-330 compatible frameworks like Hilt, Dagger, or Guice.
+
+### Setup
+
+Add the `koin-jsr330` dependency to your project:
+
+```kotlin
+dependencies {
+    implementation "io.insert-koin:koin-jsr330:$koin_version"
+}
+```
+
+### Available JSR-330 Annotations
+
+#### @Singleton (jakarta.inject.Singleton)
+
+JSR-330 standard singleton annotation, equivalent to Koin's `@Single`:
+
+```kotlin
+import jakarta.inject.Singleton
+
+@Singleton
+class DatabaseService
+```
+
+This generates the same result as `@Single` - a singleton instance in Koin.
+
+#### @Named (jakarta.inject.Named)
+
+JSR-330 standard qualifier annotation for string-based qualifiers:
+
+```kotlin
+import jakarta.inject.Named
+import jakarta.inject.Singleton
+
+@Singleton
+@Named("inMemory")
+class InMemoryCache : Cache
+
+@Singleton  
+@Named("redis")
+class RedisCache : Cache
+```
+
+#### @Inject (jakarta.inject.Inject)
+
+JSR-330 standard injection annotation. While Koin Annotations doesn't require explicit constructor marking, `@Inject` can be used for JSR-330 compatibility:
+
+```kotlin
+import jakarta.inject.Inject
+import jakarta.inject.Singleton
+
+@Singleton
+class UserService @Inject constructor(
+    private val repository: UserRepository
+)
+```
+
+#### @Qualifier (jakarta.inject.Qualifier)
+
+Meta-annotation for creating custom qualifier annotations:
+
+```kotlin
+import jakarta.inject.Qualifier
+
+@Qualifier
+annotation class Database
+
+@Qualifier  
+annotation class Cache
+
+@Singleton
+@Database
+class DatabaseConfig
+
+@Singleton
+@Cache  
+class CacheConfig
+```
+
+#### @Scope (jakarta.inject.Scope)
+
+Meta-annotation for creating custom scope annotations:
+
+```kotlin
+import jakarta.inject.Scope
+
+@Scope
+annotation class RequestScoped
+
+// Use with Koin's scope system
+@Scope(name = "request") 
+@RequestScoped
+class RequestProcessor
+```
+
+### Mixed Usage
+
+You can freely mix JSR-330 annotations with Koin annotations in the same project:
+
+```kotlin
+// JSR-330 style
+@Singleton
+@Named("primary")
+class PrimaryDatabase : Database
+
+// Koin style  
+@Single
+@Named("secondary")
+class SecondaryDatabase : Database
+
+// Mixed in same class
+@Factory
+class DatabaseManager @Inject constructor(
+    @Named("primary") private val primary: Database,
+    @Named("secondary") private val secondary: Database  
+)
+```
+
+### Framework Migration Benefits
+
+Using JSR-330 annotations provides several advantages for framework migration:
+
+- **Familiar API**: Developers coming from Hilt, Dagger, or Guice can use known annotations
+- **Gradual Migration**: Existing JSR-330 annotated code works with minimal changes
+- **Standard Compliance**: Following JSR-330 ensures compatibility with dependency injection standards
+- **Team Onboarding**: Easier for teams familiar with other DI frameworks
+
+:::info
+JSR-330 annotations in Koin generate the same underlying DSL as their Koin equivalents. The choice between JSR-330 and Koin annotations is purely stylistic and based on team preferences or migration requirements.
+:::

docs/reference/koin-annotations/modules.md

@@ -122,3 +122,141 @@ fun main() {
     }
 }
 ```
+
+## Application Bootstrap with @KoinApplication
+
+To create a complete Koin application bootstrap, you can use the `@KoinApplication` annotation on an entry point class. This annotation helps generate Koin application bootstrap functions:
+
+```kotlin
+@KoinApplication(
+    configurations = ["default", "production"], 
+    modules = [MyModule::class]
+)
+class MyApp
+```
+
+This generates **two** functions for starting your Koin application:
+
+```kotlin
+// Use the generated application functions
+import org.koin.ksp.generated.*
+
+fun main() {
+    // Option 1: Start Koin directly
+    MyApp().startKoin()
+    
+    // Option 2: Get KoinApplication instance
+    val koinApp = MyApp().koinApplication()
+}
+```
+
+Both generated functions support custom configuration:
+
+```kotlin
+fun main() {
+    MyApp().startKoin {
+        printLogger()
+        // Add other Koin configuration
+    }
+    
+    // Or with koinApplication
+    MyApp().koinApplication {
+        printLogger()
+    }
+}
+```
+
+The `@KoinApplication` annotation supports:
+- `configurations`: Array of configuration names to scan and load
+- `modules`: Array of module classes to include directly (in addition to configurations)
+
+When no configurations are specified, it automatically loads the "default" configuration.
+
+## Configuration Management with @Configuration
+
+The `@Configuration` annotation allows you to organize modules into different configurations (environments, flavors, etc.). This is useful for organizing modules by deployment environment or feature sets.
+
+### Basic Configuration Usage
+
+```kotlin
+// Default configuration - these are equivalent
+@Module
+@Configuration
+class CoreModule
+
+@Module  
+@Configuration("default")
+class CoreModule
+```
+
+### Multiple Configuration Support
+
+A module can be associated with multiple configurations:
+
+```kotlin
+// This module is available in both "prod" and "test" configurations
+@Module
+@Configuration("prod", "test")
+class DatabaseModule {
+    @Single
+    fun database() = PostgreSQLDatabase()
+}
+
+// This module is available in default, test, and development
+@Module
+@Configuration("default", "test", "development") 
+class LoggingModule {
+    @Single
+    fun logger() = Logger()
+}
+```
+
+### Environment-Specific Configurations
+
+```kotlin
+// Development-only configuration
+@Module
+@Configuration("development")
+class DevDatabaseModule {
+    @Single
+    fun database() = InMemoryDatabase()
+}
+
+// Production-only configuration  
+@Module
+@Configuration("production")
+class ProdDatabaseModule {
+    @Single
+    fun database() = PostgreSQLDatabase()
+}
+
+// Available in multiple environments
+@Module
+@Configuration("default", "production", "development")
+class CoreModule {
+    @Single
+    fun logger() = Logger()
+}
+```
+
+### Using Configurations with @KoinApplication
+
+Reference these configurations in your application bootstrap:
+
+```kotlin
+@KoinApplication(configurations = ["default", "production"])
+class ProductionApp
+
+@KoinApplication(configurations = ["default", "development"])  
+class DevelopmentApp
+
+// Load only default configuration (same as @KoinApplication with no parameters)
+@KoinApplication
+class SimpleApp
+```
+
+:::info
+- Empty `@Configuration` is equivalent to `@Configuration("default")`
+- The "default" configuration is loaded automatically when no specific configurations are specified
+- Modules can belong to multiple configurations by listing them in the annotation
+:::