Configuration class final

Configuration annotation for configuration classes

This annotation marks a class as a source of pod definitions.

Example Usage:

@Configuration()
class AppConfig {
  @Pod()
  DatabaseConnection databaseConnection() {
    return DatabaseConnection(
      host: 'localhost',
      port: 5432,
      database: 'myapp',
    );
  }
  
  @Pod()
  @Primary()
  EmailService emailService() {
    return SmtpEmailService();
  }
  
  @Pod('alternativeEmailService')
  EmailService alternativeEmailService() {
    return SendGridEmailService();
  }
}

Designates a class as a manual configuration source for defining pods.

The @Configuration annotation is used to explicitly declare a class that provides pod definitions using annotated methods (e.g., with @Pod()). These pods are registered into the application's DI container and can be injected throughout the application.

Unlike @AutoConfiguration, which is discovered automatically (e.g., through scanning), classes annotated with @Configuration must be explicitly imported and included in the application setup.

🧩 Purpose:

• Centralizes pod creation logic in a dedicated configuration class.
• Encourages clean separation between configuration and business logic.
• Supports advanced setup such as conditional pods, external parameters, etc.

📦 Typical Use Cases:

• Registering pods that require constructor parameters or factory logic
• Defining external service clients or adapters
• Grouping related configuration logic (e.g., security, database)

🧪 Example:

@Configuration()
class AppConfig {
  @Pod()
  AppService appService() => AppService();

  @Pod()
  Logger logger() => Logger(level: 'debug');
}

🧱 Pod Method Requirements:

• Must be annotated with @Pod()
• Must return the object to be registered in the container
• May return singletons or scoped instances depending on framework support

🔧 Usage Notes:

• Unlike @Component, the annotated class is not the pod itself, but a pod provider.
• @Configuration is itself a @Component, meaning it is also managed by the container.
• You may inject dependencies into the configuration class via its constructor.

@Configuration()
class WebConfig {
  final AppProperties props;

  WebConfig(this.props);

  @Pod()
  Client httpClient() => Client(baseUrl: props.apiUrl);
}

🆚 Configuration vs AutoConfiguration:

🛠️ Internals:

• Frameworks may scan @Configuration methods at bootstrap to build the pod graph.
• The class may also participate in lifecycle hooks (e.g., @PostConstruct, @PreDestroy)

🎯 Target:

• Can only be applied to class declarations

@Configuration()
class CacheConfig {
  @Pod()
  CacheManager cache() => CacheManager();
}

🧩 Related Annotations:

• @Pod – defines individual pods inside a configuration class
• @Component – base annotation for injectable classes
• @AutoConfiguration – auto-discovered configuration class
• @Import – (planned) to import other configuration classes