Event Handlers - Learning Module

Loading content...

0/246

Single vs Multiple Handlers

The Handler Multiplicity Decision

When an event occurs, how many handlers should respond? Should a single, comprehensive handler orchestrate all reactions? Or should multiple focused handlers each handle one aspect independently?

This is not merely an implementation detail—it's an architectural decision that affects fault isolation, testability, scalability, and system complexity. Both approaches have legitimate use cases, and understanding when to apply each is essential for effective event-driven design.

What You Will Learn

By the end of this page, you will understand when to use single handlers vs multiple handlers, the trade-offs of each approach, and how to evolve from one pattern to another. You'll gain clear decision criteria and implementation strategies for both patterns.

The Single Handler Approach

A single handler approach means one handler class responds to each event type. All logic triggered by that event lives in this one handler—potentially organized into private methods, but executed as a single unit.

single-handler.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
// Single handler approach - one handler does everything
class OrderPlacedHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(
        private readonly inventoryService: InventoryService,
        private readonly paymentService: PaymentService,
        private readonly notificationService: NotificationService,
        private readonly analyticsService: AnalyticsService,
        private readonly fraudService: FraudService
    ) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        // Step 1: Reserve inventory
        await this.reserveInventory(event);
        
        // Step 2: Authorize payment
        await this.authorizePayment(event);
        
        // Step 3: Send confirmation
        await this.sendConfirmation(event);
        
        // Step 4: Track analytics
        await this.trackAnalytics(event);
        
        // Step 5: Check for fraud
        await this.checkFraud(event);
    }
    
    private async reserveInventory(event: OrderPlacedEvent): Promise<void> {
        await this.inventoryService.reserve(event.payload.items);
    }
    
    private async authorizePayment(event: OrderPlacedEvent): Promise<void> {
        await this.paymentService.authorize(
            event.payload.paymentMethodId,
            event.payload.totalAmount
        );
    }
    
    private async sendConfirmation(event: OrderPlacedEvent): Promise<void> {
        await this.notificationService.sendOrderConfirmation(
            event.payload.customerId,
            event.payload.orderId
        );
    }
    
    private async trackAnalytics(event: OrderPlacedEvent): Promise<void> {
        await this.analyticsService.track('order_placed', {
            orderId: event.payload.orderId,
            amount: event.payload.totalAmount,
            itemCount: event.payload.items.length
        });
    }
    
    private async checkFraud(event: OrderPlacedEvent): Promise<void> {
        await this.fraudService.analyze(event.payload);
    }
}

When Single Handler Works Well

•Tightly coupled operations — When all operations must succeed or fail together (e.g., inventory reservation and payment authorization)
•Strict ordering requirements — When steps must execute in a specific sequence with no parallelism
•Simple, early-stage systems — When you have few concerns and the overhead of multiple handlers isn't justified
•Saga/workflow orchestration — When the handler acts as an orchestrator managing a complex business process
•Performance-critical paths — When avoiding the overhead of multiple handler invocations matters

The Monolith Within

A single handler that grows to encompass many unrelated concerns becomes a 'monolith within a microservice.' It centralizes logic that should be independent, making changes risky and testing difficult. Monitor handler size and complexity as signals to split.

The Multiple Handler Approach

A multiple handler approach means several independent handlers subscribe to the same event type. Each handler focuses on one concern and executes independently of others.

multiple-handlers.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
// Multiple handler approach - each handler has one job
// Handler 1: Inventory concern
class InventoryReservationHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(private readonly inventoryService: InventoryService) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.inventoryService.reserve(event.payload.items);
    }
}
 
// Handler 2: Payment concern
class PaymentAuthorizationHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(private readonly paymentService: PaymentService) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.paymentService.authorize(
            event.payload.paymentMethodId,
            event.payload.totalAmount
        );
    }
}
 
// Handler 3: Notification concern
class OrderConfirmationHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(private readonly notificationService: NotificationService) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.notificationService.sendOrderConfirmation(
            event.payload.customerId,
            event.payload.orderId
        );
    }
}
 
// Handler 4: Analytics concern
class OrderAnalyticsHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(private readonly analyticsService: AnalyticsService) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.analyticsService.track('order_placed', {
            orderId: event.payload.orderId,
            amount: event.payload.totalAmount,
            itemCount: event.payload.items.length
        });
    }
}
 
// Handler 5: Fraud concern
class FraudDetectionHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(private readonly fraudService: FraudService) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.fraudService.analyze(event.payload);
    }
}

When Multiple Handlers Work Well

•Independent concerns — When operations don't depend on each other (notifications don't affect inventory)
•Fault isolation needed — When one failure shouldn't block others (email failure shouldn't block analytics)
•Different reliability requirements — When some handlers can tolerate failures while others are critical
•Different scaling needs — When some handlers process quickly while others are slow
•Different teams/ownership — When different teams own different reactions to the same event
•Evolving systems — When new reactions are added frequently without modifying existing handlers

The Open/Closed Principle

Multiple handlers exemplify the Open/Closed Principle: the system is open for extension (add new handlers) but closed for modification (existing handlers untouched). Adding a new reaction to an event means adding a new handler file, not modifying existing code.

Comparative Analysis

Understanding the trade-offs between single and multiple handlers requires examining multiple dimensions. Each approach excels in different areas.

Single vs Multiple Handlers: Trade-off Analysis
Dimension	Single Handler	Multiple Handlers
Fault Isolation	❌ One failure fails all	✅ Failures are isolated
Testability	❌ Must mock many dependencies	✅ Test each handler independently
Code Locality	✅ All logic in one place	❌ Logic spread across files
Execution Order	✅ Explicit, controlled order	❌ Order may be non-deterministic
Performance	✅ Single handler invocation	❌ Multiple invocations overhead
Parallelism	❌ Sequential by default	✅ Natural parallelism
Scaling	❌ All-or-nothing scaling	✅ Scale handlers independently
Complexity	✅ Simple for few concerns	✅ Scalable for many concerns
Team Ownership	❌ Single owner for all logic	✅ Different teams can own handlers
Adding Features	❌ Modify existing handler	✅ Add new handler
Debugging	✅ Single stack trace	❌ Distributed across handlers
Transactional Integrity	✅ Single transaction scope	❌ Separate transactions

Key insight: The trade-offs favor single handlers for tightly coupled, transactional operations, and multiple handlers for loosely coupled, independently failing operations. Most mature systems use a mix of both approaches based on the nature of each event.

Decision Framework

Use this decision framework to choose between single and multiple handlers for a given event:

Decision Questions

•Do operations need to succeed or fail together? → Yes: Single handler with transaction → No: Multiple handlers
•Is there a strict ordering requirement between operations? → Yes: Single handler or explicit ordering mechanism → No: Multiple handlers with parallel execution
•Should one operation's failure block others? → Yes: Single handler → No: Multiple handlers with independent error handling
•Do operations have different reliability requirements? → Yes: Multiple handlers (critical vs best-effort) → No: Either approach works
•Are different teams responsible for different reactions? → Yes: Multiple handlers (team ownership) → No: Either approach works
•How often do you add new reactions to this event? → Frequently: Multiple handlers (Open/Closed) → Rarely: Either approach works
•Is the handler becoming too complex or hard to test? → Yes: Split into multiple handlers → No: Single handler is fine

decision-examples.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// Example 1: Single handler - operations must succeed together
// Payment capture and inventory deduction are transactionally coupled
class OrderConfirmedHandler implements EventHandler<OrderConfirmedEvent> {
    readonly eventTypes = ['OrderConfirmed'];
    
    constructor(
        private readonly paymentService: PaymentService,
        private readonly inventoryService: InventoryService,
        private readonly db: Database
    ) {}
    
    async handle(event: OrderConfirmedEvent): Promise<void> {
        // Single transaction - both must succeed
        await this.db.transaction(async (tx) => {
            await this.paymentService.capture(event.payload.paymentId, tx);
            await this.inventoryService.deduct(event.payload.items, tx);
        });
    }
}
 
// Example 2: Multiple handlers - independent concerns
// Notifications, analytics, and integrations are completely independent
 
class CustomerNotificationHandler implements EventHandler<OrderConfirmedEvent> {
    readonly eventTypes = ['OrderConfirmed'];
    // Email failure shouldn't affect anything else
    async handle(event: OrderConfirmedEvent): Promise<void> {
        await this.emailService.sendOrderConfirmation(event.payload);
    }
}
 
class OrderAnalyticsHandler implements EventHandler<OrderConfirmedEvent> {
    readonly eventTypes = ['OrderConfirmed'];
    // Analytics is best-effort, can fail silently
    async handle(event: OrderConfirmedEvent): Promise<void> {
        await this.analytics.track('order_confirmed', event.payload);
    }
}
 
class ERPIntegrationHandler implements EventHandler<OrderConfirmedEvent> {
    readonly eventTypes = ['OrderConfirmed'];
    // ERP sync can be retried independently
    async handle(event: OrderConfirmedEvent): Promise<void> {
        await this.erpClient.syncOrder(event.payload);
    }
}
 
class LoyaltyPointsHandler implements EventHandler<OrderConfirmedEvent> {
    readonly eventTypes = ['OrderConfirmed'];
    // Points can be added later if this fails
    async handle(event: OrderConfirmedEvent): Promise<void> {
        await this.loyaltyService.awardPoints(event.payload);
    }
}

The Hybrid Approach

Many systems use a hybrid approach: a primary handler for critical, transactionally coupled operations, and multiple secondary handlers for independent concerns. The primary handler handles payment and inventory; secondary handlers handle notifications, analytics, and integrations.

Execution Semantics

When multiple handlers subscribe to an event, the event system must decide how to execute them. Different execution semantics have different implications for performance, ordering, and error handling.

Parallel execution invokes all handlers concurrently. This maximizes throughput but provides no ordering guarantees and complicates error handling.

TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
class ParallelEventBus implements EventBus {
    private handlers: Map<string, EventHandler<Event>[]> = new Map();
    
    async publish(event: Event): Promise<void> {
        const handlers = this.handlers.get(event.type) || [];
        
        // Execute all handlers in parallel
        const results = await Promise.allSettled(
            handlers.map(handler => handler.handle(event))
        );
        
        // Check for failures
        const failures = results.filter(
            (r): r is PromiseRejectedResult => r.status === 'rejected'
        );
        
        if (failures.length > 0) {
            // Log failures but don't fail the publish
            failures.forEach(f => 
                console.error('Handler failed:', f.reason)
            );
        }
    }
}
 
// Characteristics:
// ✅ Maximum throughput - all handlers run simultaneously
// ✅ No handler blocks another
// ❌ No guaranteed order
// ❌ Complex error semantics - what does "failure" mean?
// ❌ Resource contention possible

Error Handling in Multi-Handler Scenarios

When multiple handlers process an event, error handling becomes more complex. What happens if one handler fails? Should others continue? Should the event be retried for all handlers or just the failing one?

Error Handling Strategies for Multiple Handlers
Strategy	Behavior	Use Case
Fail Fast	Stop all handlers on first failure	Transactional - all-or-nothing
Continue on Error	Execute all handlers, collect failures	Independent handlers, best-effort
Retry Failed Only	Only retry handlers that failed	Optimize retry cost
Retry All	Retry event for all handlers (idempotent)	Simple, requires idempotency
Quarantine Failed	Dead-letter just the failed handler's state	Granular error recovery

multi-handler-errors.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
// Strategy: Continue on Error with Granular Tracking
class ResilientEventBus implements EventBus {
    async publish(event: Event): Promise<PublishResult> {
        const handlers = this.getHandlers(event.type);
        const results: HandlerResult[] = [];
        
        // Execute all handlers, don't stop on failure
        await Promise.all(handlers.map(async (handler) => {
            const startTime = Date.now();
            try {
                await handler.handle(event);
                results.push({
                    handler: handler.constructor.name,
                    status: 'success',
                    durationMs: Date.now() - startTime
                });
            } catch (error) {
                results.push({
                    handler: handler.constructor.name,
                    status: 'failed',
                    error: error.message,
                    durationMs: Date.now() - startTime
                });
            }
        }));
        
        // Report results for monitoring
        const failed = results.filter(r => r.status === 'failed');
        if (failed.length > 0) {
            await this.reportFailures(event, failed);
        }
        
        return { event, results };
    }
    
    private async reportFailures(
        event: Event, 
        failures: HandlerResult[]
    ): Promise<void> {
        // Option 1: Log for alerting
        console.error('Some handlers failed', { 
            eventId: event.id, 
            failures 
        });
        
        // Option 2: Dead-letter with handler-specific metadata
        for (const failure of failures) {
            await this.deadLetterQueue.send({
                event,
                failedHandler: failure.handler,
                error: failure.error,
                timestamp: new Date()
            });
        }
        
        // Option 3: Schedule retry for failed handlers only
        for (const failure of failures) {
            await this.retryQueue.schedule({
                event,
                handlerName: failure.handler,
                retryCount: 1,
                retryAt: new Date(Date.now() + 60000)
            });
        }
    }
}
 
// Handler-specific retry mechanism
class HandlerRetryProcessor {
    async processRetry(retry: RetryRecord): Promise<void> {
        const handler = this.getHandler(retry.handlerName);
        
        try {
            await handler.handle(retry.event);
            console.log(`Retry succeeded: ${retry.handlerName}`);
        } catch (error) {
            if (retry.retryCount >= this.maxRetries) {
                // Max retries exceeded - dead-letter
                await this.deadLetterQueue.send({
                    ...retry,
                    finalError: error.message
                });
            } else {
                // Schedule another retry with backoff
                await this.retryQueue.schedule({
                    ...retry,
                    retryCount: retry.retryCount + 1,
                    retryAt: this.calculateBackoff(retry.retryCount)
                });
            }
        }
    }
}

Idempotency Enables Retry-All

The simplest approach—retrying the event for all handlers—works when all handlers are idempotent. Handlers that already succeeded will detect the duplicate and skip. This simplifies the event bus but requires disciplined handler design.

Evolution Patterns

Systems rarely stay static. A single handler that was appropriate at launch may need to become multiple handlers as the system grows. Understanding how to evolve handler architecture safely is important for long-term maintainability.

Pattern: Strangler Fig for Handlers

When splitting a single handler into multiple handlers, use the strangler fig pattern:

Create the new focused handler alongside the existing one
Have both handlers active, but new handler handles real traffic
Original handler continues for comparison/fallback
Once confident, remove logic from original handler
Eventually delete the empty original handler

handler-evolution.ts
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
// Phase 1: Original monolithic handler
class OriginalOrderHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.reserveInventory(event);    // Concern 1
        await this.sendConfirmation(event);    // Concern 2
        await this.trackAnalytics(event);      // Concern 3
    }
    // ... private methods
}
 
// Phase 2: Extract first concern to new handler
// Both handlers run on same event
class InventoryHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        await this.inventoryService.reserve(event.payload.items);
    }
}
 
// Original handler with feature flag
class OriginalOrderHandler implements EventHandler<OrderPlacedEvent> {
    async handle(event: OrderPlacedEvent): Promise<void> {
        // Feature flag: let new handler do inventory
        if (!this.featureFlags.isEnabled('new-inventory-handler')) {
            await this.reserveInventory(event);  // Legacy path
        }
        
        await this.sendConfirmation(event);
        await this.trackAnalytics(event);
    }
}
 
// Phase 3: Extract more concerns, remove from original
class NotificationHandler implements EventHandler<OrderPlacedEvent> { /*...*/ }
class AnalyticsHandler implements EventHandler<OrderPlacedEvent> { /*...*/ }
 
// Original handler now empty - safe to delete
class OriginalOrderHandler implements EventHandler<OrderPlacedEvent> {
    async handle(event: OrderPlacedEvent): Promise<void> {
        // All concerns extracted to dedicated handlers
        // This handler can now be removed
    }
}
 
// Phase 4: Final state - clean, focused handlers
// InventoryHandler, NotificationHandler, AnalyticsHandler
// OriginalOrderHandler deleted

Evolution Best Practices

•Use feature flags — Control which handler path executes during transition
•Run in parallel first — Have old and new handlers run together for comparison
•Monitor closely — Watch metrics for both handlers during transition
•Rollback capability — Keep old handler functional until confident in new approach
•Incremental extraction — Extract one concern at a time, not all at once

Summary: Single vs Multiple Handlers

The choice between single and multiple handlers is an architectural decision with significant implications. Here's what we've learned:

Key Takeaways

•Single handlers suit coupled operations — When operations must succeed/fail together or execute in strict order.
•Multiple handlers suit independent concerns — When operations can fail independently and have different reliability needs.
•The trade-offs are real — Fault isolation vs code locality, parallelism vs ordering, extensibility vs simplicity.
•Use the decision framework — Ask the key questions about coupling, ordering, failure modes, and team ownership.
•Execution semantics matter — Parallel, sequential, or prioritized execution each have different implications.
•Error handling is complex — Decide whether to fail-fast, continue, or retry at the handler or event level.
•Systems evolve — Use strangler fig pattern to safely split handlers as systems grow.

What's next:

With handler multiplicity addressed, we'll explore handler ordering—when and how to control the sequence in which multiple handlers execute. The next page covers ordering guarantees, explicit ordering mechanisms, and patterns for coordinating handler execution.

Page Complete

You now understand when to use single vs multiple handlers, the trade-offs involved, and how to evolve between approaches. This knowledge enables you to design handler architectures that match your system's needs.