feat(core): implement Abstract Class-Based DI with @primary and @nAmed decorators

Add comprehensive dependency injection pattern using abstract classes as contracts:

Features:
- @implements decorator: register implementations for abstract classes
- @primary decorator: select default implementation when multiple exist
- @nAmed decorator: qualified injection for specific named implementations
- Full registry tracking and container resolution
- Support for both property and constructor injection
- Combine @primary with @nAmed for default + specific access

Changes:
- Add 16 comprehensive tests
- Update documentation with examples

Author: riktar

docs/guide/dependency-injection.md

@@ -7,6 +7,7 @@ The Rikta DI container with full autowiring support.
 - **Automatic resolution** via TypeScript metadata
 - **Single decorator**: `@Autowired()` for everything
 - **Token-based injection** for interfaces
+- **Abstract class-based injection** for contracts (Strategy pattern)
 - **Zero configuration** - just decorate!
 
 ## @Autowired() - The Universal Decorator
@@ -222,3 +223,255 @@ class RequestLogger { }
 | `container.registerProvider(provider)` | Register custom provider |
 | `container.resolve(token)` | Get instance |
 | `container.resolveOptional(token)` | Get instance or undefined |
+
+## Abstract Class-Based Injection
+
+For complex contracts and the Strategy pattern, use abstract classes instead of tokens.
+
+### Why Abstract Classes?
+
+| Aspect | InjectionToken | Abstract Class |
+|--------|----------------|----------------|
+| **Type Safety** | ⚠️ Requires explicit type | ✅ Inferred automatically |
+| **Boilerplate** | ⚠️ Create token separately | ✅ Just the abstract class |
+| **Refactoring** | ⚠️ Update token everywhere | ✅ Rename works automatically |
+| **Shared Methods** | ❌ Not possible | ✅ Add utility methods |
+
+### Define the Contract
+
+```typescript
+// contracts/notification.strategy.ts
+export abstract class NotificationStrategy {
+  abstract send(recipient: string, message: string): Promise<boolean>;
+  abstract isAvailable(): boolean;
+  
+  // Shared utility method available to all implementations
+  protected log(message: string): void {
+    console.log(`[${this.constructor.name}] ${message}`);
+  }
+}
+```
+
+### Implement with `@Implements`
+
+```typescript
+// strategies/email.strategy.ts
+import { Injectable, Implements, Primary } from '@riktajs/core';
+import { NotificationStrategy } from '../contracts/notification.strategy';
+
+@Injectable()
+@Implements(NotificationStrategy)
+@Primary()  // This is the default implementation
+export class EmailStrategy extends NotificationStrategy {
+  async send(recipient: string, message: string): Promise<boolean> {
+    this.log(`Sending email to ${recipient}`);
+    // ... email logic
+    return true;
+  }
+  
+  isAvailable(): boolean {
+    return true;
+  }
+}
+```
+
+```typescript
+// strategies/sms.strategy.ts
+@Injectable()
+@Implements(NotificationStrategy)
+export class SmsStrategy extends NotificationStrategy {
+  async send(recipient: string, message: string): Promise<boolean> {
+    this.log(`Sending SMS to ${recipient}`);
+    // ... SMS logic
+    return true;
+  }
+  
+  isAvailable(): boolean {
+    return process.env.TWILIO_ENABLED === 'true';
+  }
+}
+```
+
+### Inject the Abstract Class
+
+```typescript
+@Controller('/notifications')
+export class NotificationController {
+  // Automatically resolved to EmailStrategy (the @Primary)
+  @Autowired()
+  private strategy!: NotificationStrategy;
+  
+  @Post('/send')
+  async send(@Body() data: { to: string; message: string }) {
+    if (!this.strategy.isAvailable()) {
+      throw new Error('Notification strategy not available');
+    }
+    return this.strategy.send(data.to, data.message);
+  }
+}
+```
+
+### Strategy Pattern with Factory
+
+For runtime strategy selection, combine with a Factory pattern:
+
+```typescript
+// factory/notification.factory.ts
+@Injectable()
+export class NotificationFactory {
+  @Autowired()
+  private emailStrategy!: EmailStrategy;
+  
+  @Autowired()
+  private smsStrategy!: SmsStrategy;
+  
+  @Autowired()
+  private pushStrategy!: PushStrategy;
+  
+  getStrategy(channel: 'email' | 'sms' | 'push'): NotificationStrategy {
+    switch (channel) {
+      case 'email': return this.emailStrategy;
+      case 'sms': return this.smsStrategy;
+      case 'push': return this.pushStrategy;
+    }
+  }
+  
+  getAvailableStrategies(): NotificationStrategy[] {
+    return [this.emailStrategy, this.smsStrategy, this.pushStrategy]
+      .filter(s => s.isAvailable());
+  }
+}
+
+// services/notification.service.ts
+@Injectable()
+export class NotificationService {
+  @Autowired()
+  private factory!: NotificationFactory;
+  
+  @Autowired()
+  private defaultStrategy!: NotificationStrategy;  // Gets @Primary
+  
+  async notify(
+    recipient: string,
+    message: string,
+    channel?: 'email' | 'sms' | 'push'
+  ): Promise<boolean> {
+    const strategy = channel 
+      ? this.factory.getStrategy(channel)
+      : this.defaultStrategy;
+    
+    return strategy.send(recipient, message);
+  }
+  
+  async notifyAll(recipient: string, message: string): Promise<void> {
+    const strategies = this.factory.getAvailableStrategies();
+    await Promise.all(strategies.map(s => s.send(recipient, message)));
+  }
+}
+```
+
+### Multiple Implementations Rules
+
+1. **Single implementation**: Automatically used, no `@Primary` needed
+2. **Multiple implementations with `@Primary`**: The `@Primary` is the default
+3. **Multiple implementations without `@Primary`**: Error at resolution time
+4. **Multiple implementations with `@Named`**: Use qualified injection by name
+
+```typescript
+// ✅ Single implementation - works
+@Injectable()
+@Implements(CacheStrategy)
+export class RedisCache extends CacheStrategy { }
+
+// ✅ Multiple with @Primary - works  
+@Injectable()
+@Implements(PaymentGateway)
+@Primary()
+export class StripeGateway extends PaymentGateway { }
+
+@Injectable()
+@Implements(PaymentGateway)
+export class PayPalGateway extends PaymentGateway { }
+
+// ❌ Multiple without @Primary - throws error
+@Injectable()
+@Implements(Logger)
+export class FileLogger extends Logger { }
+
+@Injectable()
+@Implements(Logger)
+export class ConsoleLogger extends Logger { }
+// Error: Multiple implementations found. Use @Primary() to mark one as default.
+```
+
+### Named Implementations with @Named
+
+When you have multiple implementations and want to inject specific ones by name:
+
+```typescript
+import { Injectable, Implements, Named, Primary, Autowired } from '@riktajs/core';
+
+// Abstract contract
+abstract class Mailer {
+  abstract send(to: string, body: string): Promise<void>;
+}
+
+// Named implementations
+@Injectable()
+@Implements(Mailer)
+@Named('smtp')
+@Primary() // Also the default
+export class SmtpMailer extends Mailer {
+  async send(to: string, body: string): Promise<void> {
+    console.log('[SMTP]', to, body);
+  }
+}
+
+@Injectable()
+@Implements(Mailer)
+@Named('sendgrid')
+export class SendGridMailer extends Mailer {
+  async send(to: string, body: string): Promise<void> {
+    console.log('[SendGrid]', to, body);
+  }
+}
+
+// Inject by name
+@Injectable()
+export class MailService {
+  @Autowired(Mailer)
+  private defaultMailer!: Mailer; // Gets SmtpMailer (Primary)
+
+  @Autowired(Mailer, 'smtp')
+  private smtpMailer!: Mailer;
+
+  @Autowired(Mailer, 'sendgrid')
+  private sendgridMailer!: Mailer;
+}
+
+// Also works with constructor injection
+@Injectable()
+export class CampaignService {
+  constructor(
+    @Autowired(Mailer, 'sendgrid') private bulkMailer: Mailer,
+    @Autowired(Mailer, 'smtp') private transactionalMailer: Mailer
+  ) {}
+}
+```
+
+### Explicit Registration (Override)
+
+You can also register implementations explicitly, overriding `@Implements`:
+
+```typescript
+// main.ts
+import { container } from '@riktajs/core';
+
+// Override based on environment
+if (process.env.NODE_ENV === 'test') {
+  container.registerProvider({
+    provide: NotificationStrategy,
+    useClass: MockNotificationStrategy,
+  });
+}
+```

examples/example/README.md

@@ -16,7 +16,14 @@ example/
     │   └── logger.provider.ts       # @Provider for LOGGER (with dependencies!)
     ├── controllers/
     │   ├── app.controller.ts        # Root & health endpoints
+    │   ├── notification.controller.ts # Strategy Pattern demo
     │   └── user.controller.ts       # User CRUD endpoints
+    ├── strategies/
+    │   ├── notification.strategy.ts # Abstract strategy contract
+    │   ├── email.strategy.ts        # @Primary email implementation
+    │   ├── sms.strategy.ts          # SMS implementation
+    │   ├── push.strategy.ts         # Push notification implementation
+    │   └── notification.factory.ts  # Factory for runtime selection
     └── services/
         ├── database.service.ts      # In-memory database (priority: 100)
         ├── health.service.ts        # Health check + OnApplicationListen
@@ -43,6 +50,10 @@ Server starts at `http://localhost:3000`
 | POST | `/users` | Create user |
 | PUT | `/users/:id` | Update user |
 | DELETE | `/users/:id` | Delete user |
+| GET | `/notifications/channels` | List notification channels |
+| GET | `/notifications/status` | Notification system status |
+| POST | `/notifications/send` | Send notification |
+| POST | `/notifications/broadcast` | Broadcast to all channels |
 
 ## 🔄 Lifecycle Demonstrations
 
@@ -136,6 +147,55 @@ export class DatabaseService {
 }
 ```
 
+### Strategy Pattern with Abstract Class DI
+
+```typescript
+// Abstract contract
+abstract class NotificationStrategy {
+  abstract send(recipient: string, message: string): Promise<boolean>;
+  abstract isAvailable(): boolean;
+}
+
+// Primary implementation (default)
+@Injectable()
+@Primary()
+@Implements(NotificationStrategy)
+export class EmailStrategy extends NotificationStrategy {
+  async send(recipient: string, message: string): Promise<boolean> {
+    // Email logic...
+    return true;
+  }
+  
+  isAvailable(): boolean {
+    return true;
+  }
+}
+
+// Factory for runtime selection
+@Injectable()
+export class NotificationFactory {
+  @Autowired()
+  private emailStrategy!: EmailStrategy;
+  
+  @Autowired()
+  private smsStrategy!: SmsStrategy;
+  
+  getStrategy(channel: 'email' | 'sms'): NotificationStrategy {
+    return channel === 'email' ? this.emailStrategy : this.smsStrategy;
+  }
+}
+
+// Inject abstract class - auto-resolved to @Primary
+@Injectable()
+export class NotificationService {
+  @Autowired()
+  private strategy!: NotificationStrategy; // Gets EmailStrategy
+  
+  @Autowired()
+  private factory!: NotificationFactory;
+}
+```
+
 ## 🧪 Test with cURL
 
 ```bash
@@ -152,6 +212,24 @@ curl -X POST http://localhost:3000/users \
 
 # List users
 curl http://localhost:3000/users
+
+# Notification channels
+curl http://localhost:3000/notifications/channels
+
+# Send notification via default channel (email)
+curl -X POST http://localhost:3000/notifications/send \
+  -H "Content-Type: application/json" \
+  -d '{"recipient": "user@example.com", "message": "Hello!"}'
+
+# Send notification via specific channel
+curl -X POST http://localhost:3000/notifications/send \
+  -H "Content-Type: application/json" \
+  -d '{"recipient": "+1234567890", "message": "Your OTP is 123456", "channel": "sms"}'
+
+# Broadcast to all available channels
+curl -X POST http://localhost:3000/notifications/broadcast \
+  -H "Content-Type: application/json" \
+  -d '{"recipient": "user123", "message": "Important announcement!"}'
 ```
 
 ## 🔑 Key Features Demonstrated
@@ -165,6 +243,11 @@ curl http://localhost:3000/users
 | `OnApplicationListen` hook | `services/health.service.ts` |
 | `@On()` decorator | `services/monitoring.service.ts` |
 | Auto-discovery | `main.ts` (autowired: ['./src']) |
+| Strategy Pattern | `strategies/*.ts` |
+| Abstract Class DI | `strategies/notification.strategy.ts` |
+| `@Implements` decorator | `strategies/email.strategy.ts` |
+| `@Primary` decorator | `strategies/email.strategy.ts` |
+| Factory Pattern | `strategies/notification.factory.ts` |
 
 ## 📦 Path Resolution