the-sunken-reach/frontend/src/hooks/useCampaignSocket.ts

import { useEffect } from 'react';
import { useQueryClient, type QueryKey } from '@tanstack/react-query';
import { io, type Socket } from 'socket.io-client';
import { API_URL } from '../api/client';
import { useAuth } from '../auth/useAuth';

let sharedSocket: Socket | null = null;

function getSocket(token: string): Socket {
  if (!sharedSocket) {
    sharedSocket = io(API_URL, { auth: { token }, transports: ['websocket', 'polling'] });
  }
  return sharedSocket;
}

// One change on the server often sends two or three events together. They are
// gathered for this long and answered with one refetch per query.
const FLUSH_MS = 50;

// Joins the Socket.io room for a campaign and keeps React Query's cache in
// sync with server-pushed events (HP/condition changes, encounter rounds,
// new characters) so every open tab in the campaign updates live.
export function useCampaignSocket(campaignId: string | undefined) {
  const { token } = useAuth();
  const qc = useQueryClient();

  useEffect(() => {
    if (!campaignId || !token) return;
    const socket = getSocket(token);
    socket.emit('campaign:join', campaignId);

    const pending = new Map<string, QueryKey>();
    let timer: ReturnType<typeof setTimeout> | undefined;
    const flush = () => {
      timer = undefined;
      const keys = [...pending.values()];
      pending.clear();
      // A wider key covers a narrower one waiting beside it: ['encounter'] takes in ['encounter', id].
      const covered = (key: QueryKey) => keys.some((other) => other.length < key.length && other.every((part, i) => part === key[i]));
      for (const queryKey of keys) if (!covered(queryKey)) qc.invalidateQueries({ queryKey });
    };
    const invalidate = (queryKey: QueryKey) => {
      pending.set(JSON.stringify(queryKey), queryKey);
      timer ??= setTimeout(flush, FLUSH_MS);
    };
    // An event names what changed when it is one thing, and nothing when it may be many.
    const one = (root: string, id?: string) => invalidate(id ? [root, id] : [root]);

    const onCharacterUpdated = ({ characterId }: { characterId?: string } = {}) => {
      invalidate(['campaign', campaignId, 'characters']);
      one('character', characterId);
      invalidate(['encounter']); // a character combatant shows the sheet HP
      // A character arriving somewhere new adds it to the places their player can see.
      invalidate(['campaign', campaignId, 'locations']);
    };
    const onCharacterCreated = () => {
      invalidate(['campaign', campaignId, 'characters']);
    };
    const onParticipantUpdated = ({ encounterId }: { encounterId?: string } = {}) => {
      one('encounter', encounterId);
      // A player's list only holds the encounters their characters are in.
      invalidate(['campaign', campaignId, 'encounters']);
    };
    const onRoundAdvanced = ({ encounterId }: { encounterId?: string } = {}) => {
      one('encounter', encounterId);
    };
    const onCampaignDeleted = () => {
      invalidate(['campaigns']);
      invalidate(['campaign', campaignId]);
    };

    socket.on('character:updated', onCharacterUpdated);
    socket.on('character:created', onCharacterCreated);
    socket.on('encounter:participant-updated', onParticipantUpdated);
    socket.on('encounter:round-advanced', onRoundAdvanced);
    socket.on('campaign:deleted', onCampaignDeleted);

    return () => {
      if (timer) {
        clearTimeout(timer);
        flush();
      }
      socket.emit('campaign:leave', campaignId);
      socket.off('character:updated', onCharacterUpdated);
      socket.off('character:created', onCharacterCreated);
      socket.off('encounter:participant-updated', onParticipantUpdated);
      socket.off('encounter:round-advanced', onRoundAdvanced);
      socket.off('campaign:deleted', onCampaignDeleted);
    };
  }, [campaignId, token, qc]);
}