@vytches/ddd-events

@vytches/ddd-events

Domain events, integration events, and a unified event bus for DDD applications

Installation

pnpm add @vytches/ddd-events

What's included

Event classes

Export	Kind	Description
DomainEvent	class	Base class for domain events (aggregate-level state changes)
IntegrationEvent	class	Base class for cross-boundary integration events

Buses and dispatchers

Export	Kind	Description
BaseEventBus	class	Abstract base for custom event bus implementations
UnifiedEventBus	class	Concrete bus that handles domain, integration, and audit events
UniversalEventDispatcher	class	Dispatches events to all registered buses simultaneously

Integration event processing

Export	Kind	Description
IntegrationEventProcessor	class	Processes raw IntegrationEvent objects through registered handlers
DomainToIntegrationTransformer	class	Transforms DomainEvent instances into IntegrationEvent instances

Decorators and discovery

Export	Kind	Description
EventHandler	decorator	Marks a class as a handler for specific event type(s)
EventDiscoveryPlugin	class	IHandlerDiscoveryPlugin that discovers @EventHandler-decorated classes
eventDiscoveryPlugin	object	Pre-built singleton instance of EventDiscoveryPlugin
EventHandlerOptions	interface	Options accepted by @EventHandler
DIHandlerMetadata	interface	Metadata stored on handler classes by the decorator

Bus interfaces

Export	Kind	Description
IDomainEventBus	interface	Bus for domain events
IIntegrationEventBus	interface	Bus for integration events
IAuditEventBus	interface	Bus for audit events
UnifiedEventHandler	interface	Handler contract accepted by UnifiedEventBus

Internal symbol (advanced use)

Export	Kind	Description
CUSTOM_MIDDLEWARE_SYMBOL	symbol	Marker for custom middleware attached to buses; not part of the stable consumer API

Quick start

Define and publish a domain event

import { DomainEvent, UnifiedEventBus } from '@vytches/ddd-events';

class OrderPlaced extends DomainEvent<{ orderId: string; total: number }> {
  constructor(payload: { orderId: string; total: number }) {
    super('OrderPlaced', payload, { version: 1, source: 'OrderContext' });
  }
}

const eventBus = new UnifiedEventBus();

eventBus.subscribe('OrderPlaced', async event => {
  console.log('Order placed:', event.payload.orderId);
});

await eventBus.publish(new OrderPlaced({ orderId: 'ord-1', total: 99.99 }));

Handler decorator

import { EventHandler } from '@vytches/ddd-events';

@EventHandler(OrderPlaced)
class SendConfirmationEmailHandler {
  async handle(event: OrderPlaced): Promise<void> {
    await emailService.send(event.payload.orderId);
  }
}

Integration events

import {
  IntegrationEvent,
  DomainToIntegrationTransformer,
} from '@vytches/ddd-events';

class OrderCreatedIntegrationEvent extends IntegrationEvent<{
  orderId: string;
}> {
  constructor(orderId: string) {
    super('OrderCreated', { orderId }, { source: 'OrderContext' });
  }
}

const transformer = new DomainToIntegrationTransformer([
  {
    domainEventName: 'OrderPlaced',
    transform: domainEvent =>
      new OrderCreatedIntegrationEvent(domainEvent.payload.orderId),
  },
]);

Package boundaries

@vytches/ddd-events depends on:

• @vytches/ddd-contracts — IDomainEvent, IEventBus, IEventHandler, metadata keys
• @vytches/ddd-logging — internal logging

License

MIT