Event Handlers - Learning Module

Loading content...

0/246

What is an Event Handler

The Reactive Building Blocks

In event-driven systems, events represent facts that have occurred—something happened in the system that may be of interest to other components. But events alone are inert; they are merely notifications floating in the ether. The component that breathes life into these events, that takes action in response to their occurrence, is the event handler.

Understanding event handlers is fundamental to building event-driven systems. They are the reactive building blocks that translate events into behavior, transforming passive notifications into active system responses. Yet despite their central importance, event handlers are often treated as an afterthought—leading to brittle, untestable, and unmaintainable code.

What You Will Learn

By the end of this page, you will understand what event handlers are at a conceptual and implementation level. You'll learn how they differ from traditional request handlers, their core responsibilities, and the fundamental contract they establish with the event-driven system. This foundation is critical before exploring design principles, multiplicity, and ordering.

Defining Event Handlers

An event handler is a software component that subscribes to specific event types and executes logic when those events occur. The handler doesn't know or care who published the event—it only cares that the event happened and what information the event carries.

This is fundamentally different from traditional request-response programming:

In request-response, a caller explicitly invokes a function and waits for a return value.
In event-driven programming, a publisher emits an event and continues without waiting. Handlers execute independently, often asynchronously.

This distinction creates a profound shift in how we design software. Handlers are not "called"—they are "triggered." They don't return values to a waiting caller—they perform side effects or publish new events.

The Fundamental Contract

An event handler establishes a contract: "When event X occurs, I will perform action Y." The handler promises to react to certain event types, but makes no promises about timing, order relative to other handlers, or mutual exclusion with concurrent handlers—unless the system explicitly provides such guarantees.

Request Handler vs Event Handler
Aspect	Request Handler	Event Handler
Invocation	Explicit call from client	Triggered by event occurrence
Caller awareness	Caller knows the handler exists	Publisher unaware of handlers
Return value	Expected and awaited	None (fire-and-forget)
Coupling	Tight coupling to caller	Loose coupling via events
Error handling	Exception propagates to caller	Handler manages errors locally
Concurrency	Caller controls timing	Multiple handlers may run concurrently
Testability	Test by invoking directly	Test by publishing events

The Anatomy of an Event Handler

While implementations vary across languages and frameworks, every event handler shares a common structure. Understanding this anatomy helps you design handlers that are consistent, readable, and maintainable.

Core Components of an Event Handler

•Event Type Binding — The handler declares which event types it responds to. This is the subscription contract. The handler says "I care about OrderPlaced events" and the event system ensures it receives them.
•Event Parameter — The handler receives the event object containing all relevant data. This is the only input the handler has—it cannot request additional context from the publisher.
•Handle Logic — The core business logic that processes the event. This may involve validation, state updates, external service calls, or publishing downstream events.
•Error Handling — Since there's no caller to propagate exceptions to, the handler must decide how to handle failures: retry, dead-letter, log and continue, or compensate.
•Idempotency Mechanism — For at-least-once delivery systems, handlers typically implement idempotency checks to safely handle duplicate event deliveries.

event-handler-anatomy.ts
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
// Basic structure of an event handler
interface Event {
    id: string;           // Unique event identifier
    type: string;         // Event type for routing
    timestamp: Date;      // When the event occurred
    payload: unknown;     // Event-specific data
}
 
// Handler interface - the contract
interface EventHandler<T extends Event> {
    // Which event type(s) this handler responds to
    readonly eventTypes: string[];
    
    // The handle method - receives event, returns nothing
    handle(event: T): Promise<void>;
}
 
// Concrete handler implementation
class OrderPlacedHandler implements EventHandler<OrderPlacedEvent> {
    readonly eventTypes = ['OrderPlaced'];
    
    constructor(
        private readonly orderService: OrderService,
        private readonly notificationService: NotificationService,
        private readonly idempotencyStore: IdempotencyStore
    ) {}
    
    async handle(event: OrderPlacedEvent): Promise<void> {
        // 1. Idempotency check - have we processed this event before?
        if (await this.idempotencyStore.hasProcessed(event.id)) {
            console.log(`Event ${event.id} already processed, skipping`);
            return;
        }
        
        try {
            // 2. Core business logic
            await this.orderService.confirmOrder(event.payload.orderId);
            await this.notificationService.sendOrderConfirmation(
                event.payload.customerId,
                event.payload.orderId
            );
            
            // 3. Mark as processed (idempotency)
            await this.idempotencyStore.markProcessed(event.id);
            
        } catch (error) {
            // 4. Error handling - handler must manage its own errors
            console.error(`Failed to handle OrderPlaced event: ${event.id}`, error);
            
            // Option A: Rethrow to trigger retry (if infrastructure supports it)
            throw error;
            
            // Option B: Send to dead-letter queue for manual review
            // await this.deadLetterQueue.send(event, error);
            
            // Option C: Log and continue (for non-critical handlers)
            // return;
        }
    }
}

The Void Return Type

Notice that event handlers return void (or Promise<void>). This is not an oversight—it's a fundamental characteristic. Since the publisher doesn't wait for handlers and doesn't receive their output, there's nothing meaningful to return. Handlers communicate through side effects: database writes, external API calls, or publishing new events.

Handler Responsibilities

A well-designed event handler has clear, bounded responsibilities. Understanding what a handler should and should not do is crucial for building maintainable event-driven systems.

Handler SHOULD

•React to a single event type — Keep handlers focused on responding to one conceptual event
•Be idempotent — Handle the same event multiple times without adverse effects
•Manage its own errors — Decide whether to retry, dead-letter, or compensate
•Execute quickly — Long-running work should be delegated to background jobs
•Be independently testable — Accept dependencies via constructor injection
•Log meaningful context — Include event ID, type, and correlation IDs
•Respect transaction boundaries — Complete its unit of work atomically

Handler SHOULD NOT

•Make assumptions about ordering — Unless guaranteed by the system
•Depend on other handlers — Handlers should be independent
•Perform blocking I/O synchronously — Use async patterns
•Throw uncaught exceptions — Handle errors explicitly
•Modify the event — Events are immutable facts
•Communicate back to publishers — That breaks the decoupling model
•Contain complex orchestration — That belongs in sagas or process managers

The Single Responsibility Principle applies strongly to handlers. Each handler should do one thing well. If you find a handler doing multiple unrelated things—sending an email, updating inventory, and calculating loyalty points—consider splitting it into multiple focused handlers that each subscribe to the same event.

The Fat Handler Anti-Pattern

Beware the "fat handler" that grows to encompass all reactions to an event. This centralizes logic, makes testing difficult, and creates a single point of failure. If the email-sending code breaks, it shouldn't prevent inventory updates. Split handlers to achieve fault isolation.

Event Handler Lifecycle

Understanding the lifecycle of an event handler—from registration to execution to completion—helps you design handlers that work correctly within the event system's execution model.

Handler Lifecycle Phases

•Registration — The handler declares its interest in specific event types. This typically happens at application startup when the DI container wires handlers to the event bus.
•Subscription Activation — The event system records the handler's subscription. For message queue-based systems, this might create queue bindings.
•Event Reception — When a matching event arrives, the system deserializes it and invokes the handler's handle method.
•Execution — The handler performs its logic. This phase may include validation, business logic, database operations, and external calls.
•Completion — The handler signals completion (success or failure). For queue-based systems, this typically involves acknowledging or rejecting the message.
•Error Handling — If the handler fails, the system applies the configured retry/dead-letter policy.

handler-lifecycle.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
// Event bus with lifecycle hooks
interface EventBus {
    // Registration phase - called at startup
    register<T extends Event>(handler: EventHandler<T>): void;
    
    // Publishing phase - routes events to registered handlers
    publish(event: Event): Promise<void>;
}
 
class InMemoryEventBus implements EventBus {
    private handlers: Map<string, EventHandler<Event>[]> = new Map();
    
    // 1. Registration phase
    register<T extends Event>(handler: EventHandler<T>): void {
        for (const eventType of handler.eventTypes) {
            const existing = this.handlers.get(eventType) || [];
            existing.push(handler as EventHandler<Event>);
            this.handlers.set(eventType, existing);
            
            console.log(`Registered handler for event type: ${eventType}`);
        }
    }
    
    // 2. Event dispatch - triggers handler lifecycle
    async publish(event: Event): Promise<void> {
        const handlers = this.handlers.get(event.type) || [];
        
        console.log(`Dispatching ${event.type} to ${handlers.length} handlers`);
        
        // Execute all handlers (could be parallel or sequential)
        const promises = handlers.map(async (handler) => {
            const handlerName = handler.constructor.name;
            
            try {
                console.log(`[${handlerName}] Executing...`);
                
                // 3. Handler execution
                await handler.handle(event);
                
                // 4. Successful completion
                console.log(`[${handlerName}] Completed successfully`);
                
            } catch (error) {
                // 5. Error handling
                console.error(`[${handlerName}] Failed: ${error}`);
                
                // In a real system, apply retry policy or dead-letter
                throw error;
            }
        });
        
        // Wait for all handlers (this is a policy decision)
        await Promise.allSettled(promises);
    }
}
 
// Application startup - registration phase
function bootstrap() {
    const eventBus = new InMemoryEventBus();
    
    // Register all handlers
    eventBus.register(new OrderPlacedHandler(/* dependencies */));
    eventBus.register(new InventoryReservationHandler(/* dependencies */));
    eventBus.register(new NotificationHandler(/* dependencies */));
    
    return eventBus;
}

Lifetime Management

Handler instances may be singletons (one instance handles all events), transient (new instance per event), or scoped (instance per request/batch). The choice affects how you manage state and dependencies. Singletons must be thread-safe; transient handlers can hold request-specific state.

Handler Dependency Injection

Event handlers rarely operate in isolation. They typically need access to repositories, services, external clients, and cross-cutting concerns like logging. How you inject these dependencies significantly impacts testability, maintainability, and runtime behavior.

handler-di.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
94
95
96
97
98
99
// Well-structured handler with constructor injection
class OrderFulfillmentHandler implements EventHandler<OrderPaidEvent> {
    readonly eventTypes = ['OrderPaid'];
    
    constructor(
        // Domain services
        private readonly orderRepository: OrderRepository,
        private readonly inventoryService: InventoryService,
        private readonly shippingService: ShippingService,
        
        // Infrastructure services
        private readonly eventBus: EventBus,
        private readonly logger: Logger,
        
        // Cross-cutting concerns
        private readonly metrics: MetricsClient,
        private readonly tracer: Tracer
    ) {}
    
    async handle(event: OrderPaidEvent): Promise<void> {
        // Create trace span for observability
        const span = this.tracer.startSpan('OrderFulfillmentHandler.handle');
        span.setAttribute('event.id', event.id);
        span.setAttribute('order.id', event.payload.orderId);
        
        try {
            this.logger.info('Processing order fulfillment', {
                eventId: event.id,
                orderId: event.payload.orderId
            });
            
            // Business logic using injected dependencies
            const order = await this.orderRepository.findById(event.payload.orderId);
            
            if (!order) {
                this.logger.warn('Order not found', { orderId: event.payload.orderId });
                return; // Idempotent - order might have been deleted
            }
            
            // Reserve inventory
            await this.inventoryService.reserveItems(order.items);
            
            // Create shipping request
            const shipment = await this.shippingService.createShipment(order);
            
            // Update order status
            order.markAsFulfilling(shipment.trackingNumber);
            await this.orderRepository.save(order);
            
            // Publish downstream event
            await this.eventBus.publish({
                id: generateId(),
                type: 'OrderFulfillmentStarted',
                timestamp: new Date(),
                payload: {
                    orderId: order.id,
                    shipmentId: shipment.id,
                    trackingNumber: shipment.trackingNumber
                }
            });
            
            // Record metrics
            this.metrics.increment('order.fulfillment.started');
            this.metrics.timing('order.fulfillment.latency', Date.now() - event.timestamp.getTime());
            
            span.setStatus({ code: SpanStatusCode.OK });
            
        } catch (error) {
            span.recordException(error);
            span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
            
            this.logger.error('Order fulfillment failed', {
                eventId: event.id,
                orderId: event.payload.orderId,
                error: error.message
            });
            
            this.metrics.increment('order.fulfillment.failed');
            
            throw error;
            
        } finally {
            span.end();
        }
    }
}
 
// DI container registration (example with tsyringe)
container.register('EventHandler', {
    useFactory: (c) => new OrderFulfillmentHandler(
        c.resolve(OrderRepository),
        c.resolve(InventoryService),
        c.resolve(ShippingService),
        c.resolve(EventBus),
        c.resolve(Logger),
        c.resolve(MetricsClient),
        c.resolve(Tracer)
    )
});

Explicit Dependencies

Prefer explicit constructor injection over service locators or global registries. Explicit dependencies make handlers testable (you can inject mocks/stubs), self-documenting (the constructor tells you what the handler needs), and maintainable (changes to dependencies are tracked at compile time).

Testing Event Handlers

Event handlers are inherently testable when designed correctly. The key is that handlers have a single entry point (the handle method), take a well-defined input (the event), and produce observable outputs (side effects). This makes test setup predictable and assertions straightforward.

handler-testing.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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
import { describe, it, expect, beforeEach, vi } from 'vitest';
 
describe('OrderFulfillmentHandler', () => {
    // Mock dependencies
    let mockOrderRepository: jest.Mocked<OrderRepository>;
    let mockInventoryService: jest.Mocked<InventoryService>;
    let mockShippingService: jest.Mocked<ShippingService>;
    let mockEventBus: jest.Mocked<EventBus>;
    let mockLogger: jest.Mocked<Logger>;
    
    let handler: OrderFulfillmentHandler;
    
    beforeEach(() => {
        // Create fresh mocks for each test
        mockOrderRepository = {
            findById: vi.fn(),
            save: vi.fn(),
        };
        mockInventoryService = {
            reserveItems: vi.fn(),
        };
        mockShippingService = {
            createShipment: vi.fn(),
        };
        mockEventBus = {
            publish: vi.fn(),
        };
        mockLogger = {
            info: vi.fn(),
            warn: vi.fn(),
            error: vi.fn(),
        };
        
        // Inject mocks into handler
        handler = new OrderFulfillmentHandler(
            mockOrderRepository,
            mockInventoryService,
            mockShippingService,
            mockEventBus,
            mockLogger
        );
    });
    
    describe('handle', () => {
        it('should fulfill order and publish downstream event', async () => {
            // Arrange
            const event = createOrderPaidEvent({ orderId: 'order-123' });
            const order = createOrder({ id: 'order-123', items: [{ sku: 'ABC', qty: 2 }] });
            const shipment = { id: 'ship-456', trackingNumber: 'TRACK123' };
            
            mockOrderRepository.findById.mockResolvedValue(order);
            mockShippingService.createShipment.mockResolvedValue(shipment);
            
            // Act
            await handler.handle(event);
            
            // Assert - verify all expected side effects
            expect(mockOrderRepository.findById).toHaveBeenCalledWith('order-123');
            expect(mockInventoryService.reserveItems).toHaveBeenCalledWith(order.items);
            expect(mockShippingService.createShipment).toHaveBeenCalledWith(order);
            expect(mockOrderRepository.save).toHaveBeenCalled();
            expect(mockEventBus.publish).toHaveBeenCalledWith(
                expect.objectContaining({
                    type: 'OrderFulfillmentStarted',
                    payload: expect.objectContaining({
                        orderId: 'order-123',
                        trackingNumber: 'TRACK123'
                    })
                })
            );
        });
        
        it('should be idempotent when order not found', async () => {
            // Arrange
            const event = createOrderPaidEvent({ orderId: 'deleted-order' });
            mockOrderRepository.findById.mockResolvedValue(null);
            
            // Act - should not throw
            await handler.handle(event);
            
            // Assert - no downstream actions taken
            expect(mockInventoryService.reserveItems).not.toHaveBeenCalled();
            expect(mockShippingService.createShipment).not.toHaveBeenCalled();
            expect(mockEventBus.publish).not.toHaveBeenCalled();
            expect(mockLogger.warn).toHaveBeenCalledWith(
                'Order not found',
                expect.objectContaining({ orderId: 'deleted-order' })
            );
        });
        
        it('should propagate errors for retry', async () => {
            // Arrange
            const event = createOrderPaidEvent({ orderId: 'order-123' });
            const order = createOrder({ id: 'order-123' });
            const inventoryError = new Error('Insufficient inventory');
            
            mockOrderRepository.findById.mockResolvedValue(order);
            mockInventoryService.reserveItems.mockRejectedValue(inventoryError);
            
            // Act & Assert
            await expect(handler.handle(event)).rejects.toThrow('Insufficient inventory');
            
            // Verify error was logged
            expect(mockLogger.error).toHaveBeenCalledWith(
                'Order fulfillment failed',
                expect.objectContaining({ error: 'Insufficient inventory' })
            );
        });
    });
});
 
// Helper factory for test events
function createOrderPaidEvent(overrides = {}) {
    return {
        id: 'event-' + Math.random().toString(36).slice(2),
        type: 'OrderPaid',
        timestamp: new Date(),
        payload: {
            orderId: 'order-default',
            customerId: 'customer-default',
            amount: 99.99,
            ...overrides
        }
    };
}

Handler Testing Best Practices

•Test the happy path — Verify that valid events trigger the expected side effects
•Test idempotency — Ensure handling the same event twice doesn't cause issues
•Test error scenarios — Verify errors are logged, metrics recorded, and appropriate actions taken
•Test edge cases — Missing data, null values, boundary conditions
•Use factory functions — Create test events with sensible defaults
•Mock at the right level — Mock direct dependencies, not transitive ones
•Assert on behavior, not implementation — Verify observable outcomes

Real-World Handler Patterns

In production systems, event handlers often follow recognizable patterns. Understanding these patterns helps you design handlers that are battle-tested and proven in real-world scenarios.

Purpose: Send notifications (email, SMS, push) in response to domain events.

Characteristics:

Typically low-priority and can tolerate some latency
Should be idempotent (don't spam users on retries)
Often uses templates and personalization
May batch multiple events into a single notification

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
class OrderShippedNotificationHandler implements EventHandler<OrderShippedEvent> {
    readonly eventTypes = ['OrderShipped'];
    
    constructor(
        private readonly emailService: EmailService,
        private readonly templateEngine: TemplateEngine,
        private readonly customerRepo: CustomerRepository,
        private readonly idempotencyStore: IdempotencyStore
    ) {}
    
    async handle(event: OrderShippedEvent): Promise<void> {
        // Idempotency - don't send duplicate emails
        const idempotencyKey = `notification-order-shipped-${event.payload.orderId}`;
        if (await this.idempotencyStore.hasProcessed(idempotencyKey)) {
            return;
        }
        
        const customer = await this.customerRepo.findById(event.payload.customerId);
        if (!customer?.email) {
            return; // No email on file, skip gracefully
        }
        
        const emailContent = this.templateEngine.render('order-shipped', {
            customerName: customer.name,
            orderId: event.payload.orderId,
            trackingNumber: event.payload.trackingNumber,
            carrier: event.payload.carrier,
            estimatedDelivery: event.payload.estimatedDelivery
        });
        
        await this.emailService.send({
            to: customer.email,
            subject: `Your order #${event.payload.orderId} has shipped!`,
            html: emailContent
        });
        
        await this.idempotencyStore.markProcessed(idempotencyKey);
    }
}

Summary: What is an Event Handler

We've established the foundational understanding of event handlers—the reactive building blocks that transform events into system behavior. Let's consolidate the key concepts:

Key Takeaways

•Event handlers are reactive components — They subscribe to event types and execute when events occur, without being explicitly called.
•Handlers differ fundamentally from request handlers — No return values, no caller awareness, loose coupling through events.
•Core anatomy includes — Event type binding, event parameter, handle logic, error handling, and idempotency.
•Handlers have clear responsibilities — Be focused, idempotent, manage their own errors, and execute quickly.
•Lifecycle spans — Registration, subscription, reception, execution, and completion phases.
•Dependency injection enables testability — Explicit dependencies make handlers unit-testable with mocks.
•Common patterns include — Notification handlers, projection handlers, and integration handlers.

What's next:

Now that we understand what event handlers are, we'll explore the design principles that guide their construction. The next page examines how to design handlers that are robust, maintainable, and resilient—covering error handling strategies, idempotency patterns, and the principles that separate good handlers from great ones.

Page Complete

You now understand what event handlers are, their anatomy, responsibilities, and lifecycle. This foundation prepares you for designing handlers that follow proven principles and patterns in the next page.