Component class

Component annotation for generic Jet components

This is the most generic stereotype annotation. Other annotations like @Service, @Repository are specializations of @Component.

Example Usage:

@Component()
class EmailService {
  final EmailProvider emailProvider;
  
  EmailService(this.emailProvider);
  
  Future<void> sendWelcomeEmail(String email) async {
    await emailProvider.send(
      to: email,
      subject: 'Welcome!',
      body: 'Welcome to our application!',
    );
  }
}

@Component('customValidator')
class CustomValidator implements Validator<String> {
  @override
  List<ValidationError> validate(String value, String fieldName) {
    final errors = <ValidationError>[];
    
    if (value.contains('forbidden')) {
      errors.add(ValidationError(
        field: fieldName,
        message: 'Value contains forbidden content',
        rejectedValue: value,
        validationType: 'CustomValidator',
      ));
    }
    
    return errors;
  }
  
  @override
  bool supports(Type type) => type == String;
}

Declares a class as a component to be automatically detected, instantiated, and managed by the dependency injection (DI) container.

The @Component annotation is the most generic stereotype used to register a class as a candidate for DI. It serves as a foundational annotation from which more specialized stereotypes like @Service, @Repository, and @Controller may derive.

🧩 Purpose:

• Enables automatic scanning and registration of classes at build or runtime.
• Indicates that the annotated class is a singleton-like pod managed by the framework.
• Promotes modular design and reusability by decoupling instantiation logic from usage.

📦 Typical Use Cases:

• Utility classes
• Service classes that do not fit under more specific roles
• Infrastructure or middleware components
• Shared helpers

🧪 Example:

@Component()
class MyHelper {
  void assist() => print("Helping...");
}

This class will be automatically instantiated and injected wherever it’s needed.

🔧 Usage Notes:

• Components are singleton by default, unless otherwise scoped.
• Use @Component for generic roles; for business logic, prefer @Service, and for data access, prefer @Repository, if available.
• Constructor injection is recommended for dependent classes:

@Component()
class Processor {
  final MyHelper helper;

  Processor(this.helper);

  void process() {
    helper.assist();
  }
}

🔁 Lifecycle:

- During DI container bootstrap:
  1. The framework scans for @Component-annotated classes.
  2. Each is instantiated, respecting its constructor dependencies.
  3. The instance is cached in the container.
  4. Other pods can declare dependencies on this class.

🏷️ Specializations:

While @Component is fully functional on its own, frameworks may define more semantically meaningful subtypes like:

• @Service – for business logic and application services
• @Repository – for data access layers
• @Controller – for routing or API layers

These may provide additional behavior (e.g., AOP, transactions, naming) while still inheriting core @Component capabilities.

🧱 Related Annotations:

• @Service
• @Repository
• @Inject / @Autowired
• @Pod / @Configuration

🎯 Target:

This annotation must be applied to class declarations only.

@Component()
class NotificationDispatcher { ... }

✅ Best Practices:

• Keep component responsibilities focused (single responsibility principle).
• Favor constructor injection over field/method injection.
• Combine with configuration and module patterns to enable composable application design.

📚 See Also:

• Dependency Injection (DI)
• Inversion of Control (IoC)