websocket-broadcasting

WebSocket Broadcasting

Broadcasts domain events to connected frontend clients via Socket.IO. Simple pattern: @EventsHandler -> enrich if needed -> WsGatewayPort.emit().

---

Flow

Entity.apply(event)           <- domain (queued)
  -> entity.commit()          <- handler (dispatch via EventBus)
    -> @EventsHandler         <- bridge handler
      -> (optional) repo.findById() to enrich payload
      -> gateway.emitToOrganization(orgId, event, data)
        -> Socket.IO server.to(`org:${orgId}`).emit()
          -> Redis Pub/Sub (multi-pod)
            -> connected clients

---

1. WsGatewayPort (hexagonal abstraction)

Define in shared/ports/ or the BC's application/ports/:

export const WS_GATEWAY_TOKEN = Symbol('WsGateway');

export interface WsGatewayPort {
  emitToOrganization(orgId: string, event: string, data: Record<string, unknown>): void;
  emitToUser(userId: string, event: string, data: Record<string, unknown>): void;
  emitGlobal(event: string, data: Record<string, unknown>): void;
}

Register in module: { provide: WS_GATEWAY_TOKEN, useExisting: AppGateway }

See references/ws-gateway-port.md for full implementation + mock for testing.

---

2. Bridge Handler (the only pattern you need)

For each domain event that needs to reach the frontend, create an @EventsHandler:

@EventsHandler(OrderCreatedEvent)
export class OrderCreatedBroadcastHandler implements IEventHandler<OrderCreatedEvent> {
  private readonly logger = new Logger(OrderCreatedBroadcastHandler.name);

  constructor(
    @Inject(WS_GATEWAY_TOKEN) private readonly gateway: WsGatewayPort,
    @Inject(ORDER_REPOSITORY) private readonly repo: OrderRepository.Repository,
  ) {}

  async handle(event: OrderCreatedEvent): Promise<void> {
    try {
      // Enrich if needed (optional — skip if event payload is sufficient)
      const order = await this.repo.findById(event.aggregateId);
      if (!order) return;

      this.gateway.emitToOrganization(event.organizationId, 'order:created', {
        id: order.id,
        total: order.total,
        status: order.status,
      });
    } catch (error) {
      // Log but never re-throw — don't break the event chain
      this.logger.error(`Failed to broadcast order:created`, error);
    }
  }
}