WebSocket Event Patterns¶

Semaphore Chat uses three distinct patterns for handling WebSocket events on the frontend. This guide defines when to use each and why.

This is not a style preference -- each pattern exists for specific technical reasons.

The Three Patterns¶

Pattern 1: Direct Cache Update (setQueryData)¶

The WebSocket event carries the full data object. The frontend writes it directly into the TanStack Query cache. No HTTP refetch occurs.

// Example: messageHandlers.ts
export const handleNewMessage: SocketEventHandler = (payload, queryClient) => {
  queryClient.setQueryData(queryKey, (old) => {
    return { ...old, pages: [[payload.message, ...old.pages[0]], ...old.pages.slice(1)] };
  });
};

Pattern 2: Cache Invalidation (invalidateQueries)¶

The WebSocket event carries a minimal signal (e.g., IDs). The frontend marks the cache as stale, triggering a refetch from the REST API.

// Example: communityHandlers.ts
export const handleChannelCreated: SocketEventHandler = (payload, queryClient) => {
  queryClient.invalidateQueries({
    queryKey: channelsControllerFindAllForCommunityQueryKey({
      path: { communityId: payload.communityId },
    }),
  });
};

Pattern 3: Ephemeral UI State (no cache)¶

The event drives transient component state via useServerEvent(). Not registered in handlerRegistry. No TanStack Query involvement.

// Example: useTypingUsers.ts
useServerEvent(ServerEvents.USER_TYPING, (payload) => {
  setTypingUsers((prev) => { /* local state only */ });
});

Decision Framework¶

Ask these five questions for each new WebSocket event:

If most answers point to one column, use that pattern. When in doubt, default to invalidation -- it's simpler and guarantees consistency.

Current Event Inventory¶

Direct Cache Updates (high-frequency, latency-sensitive)¶

Cache Invalidation (low-frequency, structural)¶

Ephemeral UI State (no cache)¶

The Hybrid Pattern (Voice Handlers)¶

Voice presence handlers demonstrate a best practice for mid-frequency events:

const existing = queryClient.getQueryData(queryKey);
if (existing) {
  // Cache is warm (user is viewing) -- update directly for instant UX
  queryClient.setQueryData(queryKey, (draft) => { /* merge update */ });
} else {
  // Cache is cold -- just invalidate, refetch when needed
  invalidateVoiceQueries(queryClient);
}

This gives you the best of both worlds: instant updates when the user is looking, zero wasted work when they're not.

Backend Event Emission¶

Domain Events via EventEmitter2¶

Services that don't have WebsocketService injected emit domain events through EventEmitter2. The centralized RoomSubscriptionHandler translates these into WebSocket room operations.

// In the service
this.eventEmitter.emit(RoomEvents.COMMUNITY_UPDATED, {
  communityId, name, description, avatar, banner,
});

// In RoomSubscriptionHandler
@OnEvent(RoomEvents.COMMUNITY_UPDATED)
onCommunityUpdated(event: CommunityUpdatedEvent): void {
  this.websocketService.sendToRoom(
    RoomName.community(event.communityId),
    ServerEvents.COMMUNITY_UPDATED,
    event,
  );
}

Used by: community, roles, user, membership, channel-membership, direct-messages, alias-groups

Direct WebsocketService¶

Gateways and services that already have WebsocketService may call sendToRoom() directly.

// In messages.gateway.ts
this.websocketService.sendToRoom(channelId, ServerEvents.NEW_MESSAGE, { message });

Used by: messages gateway, channels (hybrid), moderation (hybrid), voice-presence

When to use which¶

• New service needs to emit events? Use EventEmitter2 + add a handler in RoomSubscriptionHandler.
• Already in a gateway with WebsocketService? Direct sendToRoom() is fine.
• Event requires room management (join/leave)? Must use EventEmitter2 + RoomSubscriptionHandler.

Adding a New WebSocket Event¶

1. Decide the pattern using the decision framework above
2. Shared types: Add ServerEvents enum value + payload interface in @semaphore-chat/shared
3. Backend: Emit from service (EventEmitter2) or gateway (direct)
4. Frontend handler: Create handler function in socket-hub/handlers/
5. Register: Add to handlerRegistry in handlers/index.ts (skip for ephemeral events)
6. For ephemeral events: Use useServerEvent() in the consuming component instead

References¶

• TKDodo -- Using WebSockets with React Query
• TanStack Query -- Query Invalidation