Skip to main content

​
Presence Tracking

The PresenceManager helps you track which users are currently online and their status. It’s useful for showing active users, user lists, or online indicators.

​
Installation

Presence tracking is included in the main socket-serve package: 
import { PresenceManager } from 'socket-serve/utils/presence';

​
Basic Usage

import { SocketServer } from 'socket-serve/server';
import { PresenceManager } from 'socket-serve/utils/presence';

const server = new SocketServer({
  redisUrl: process.env.REDIS_URL!,
});

const presence = new PresenceManager(server);

// Track when users come online
presence.onJoin((userId, metadata) => {
  console.log(`${userId} is now online`);
  
  // Notify all users
  server.broadcast('user:online', {
    userId,
    ...metadata
  });
});

// Track when users go offline
presence.onLeave((userId) => {
  console.log(`${userId} went offline`);
  
  server.broadcast('user:offline', { userId });
});

​
Track User Status

// Set user status when they connect
server.onConnect(async (socket) => {
  const userId = socket.get('userId');
  
  await presence.setStatus(userId, {
    status: 'online',
    lastSeen: Date.now(),
    device: 'web'
  });
});

// Update status
server.onMessage('status:update', async (socket, data) => {
  const userId = socket.get('userId');
  
  await presence.setStatus(userId, {
    status: data.status, // 'online', 'away', 'busy', etc.
    customMessage: data.message
  });
  
  // Broadcast status change
  await socket.broadcast('user:status', {
    userId,
    status: data.status
  });
});

​
Get Online Users

// Get all online users
const onlineUsers = await presence.getOnlineUsers();
console.log(`${onlineUsers.length} users online`);

// Get users in a specific room
const roomUsers = await presence.getUsersInRoom('chat-room-1');

// Check if specific user is online
const isOnline = await presence.isOnline('user-123');

​
User Metadata

Store additional information about users: 
await presence.setStatus(userId, {
  status: 'online',
  name: 'John Doe',
  avatar: 'https://example.com/avatar.jpg',
  location: 'New York',
  lastActivity: Date.now()
});

// Retrieve user metadata
const userInfo = await presence.getUserInfo(userId);

​
Presence in Rooms

Track presence per room: 
// User joins a room
server.onMessage('join:room', async (socket, { roomId }) => {
  const userId = socket.get('userId');
  
  await socket.join(roomId);
  await presence.joinRoom(userId, roomId);
  
  // Get all users in room
  const roomMembers = await presence.getUsersInRoom(roomId);
  
  // Notify room
  await socket.broadcastToRoom(roomId, 'room:members', {
    users: roomMembers
  });
});

// User leaves a room
server.onMessage('leave:room', async (socket, { roomId }) => {
  const userId = socket.get('userId');
  
  await socket.leave(roomId);
  await presence.leaveRoom(userId, roomId);
});

​
Heartbeat & Timeouts

Automatically detect when users disconnect: 
const presence = new PresenceManager(server, {
  heartbeatInterval: 30000, // 30 seconds
  timeout: 60000 // 1 minute
});

// Client sends heartbeat
server.onMessage('heartbeat', async (socket) => {
  const userId = socket.get('userId');
  await presence.heartbeat(userId);
});

// Automatically clean up stale connections
presence.onTimeout((userId) => {
  console.log(`${userId} timed out`);
  server.broadcast('user:timeout', { userId });
});

​
API Reference

​
PresenceManager

​
Constructor

new PresenceManager(server: SocketServer, options?: PresenceOptions)
Options:
  • heartbeatInterval?: number - How often to check for heartbeats (default: 30000)
  • timeout?: number - When to consider user offline (default: 60000)

​
Methods

setStatus(userId: string, metadata: object)
Set user’s online status and metadata. 
await presence.setStatus('user-123', {
  status: 'online',
  customData: {}
});
getOnlineUsers(): Promise<string[]>
Get list of all online user IDs.
getUserInfo(userId: string): Promise<object | null>
Get user’s presence information.
isOnline(userId: string): Promise<boolean>
Check if user is currently online.
getUsersInRoom(roomId: string): Promise<string[]>
Get all users in a specific room.
joinRoom(userId: string, roomId: string): Promise<void>
Mark user as present in a room.
leaveRoom(userId: string, roomId: string): Promise<void>
Remove user from room presence.
heartbeat(userId: string): Promise<void>
Update user’s last activity timestamp.

​
Events

onJoin(callback: (userId: string, metadata: object) => void)
Called when a user comes online.
onLeave(callback: (userId: string) => void)
Called when a user goes offline.
onTimeout(callback: (userId: string) => void)
Called when a user times out due to inactivity.

​
Example: Online Users List

import { SocketServer } from 'socket-serve/server';
import { PresenceManager } from 'socket-serve/utils/presence';

const server = new SocketServer({
  redisUrl: process.env.REDIS_URL!,
});

const presence = new PresenceManager(server);

// Send online users list to new connections
server.onConnect(async (socket) => {
  const userId = socket.get('userId');
  const onlineUsers = await presence.getOnlineUsers();
  
  await socket.emit('users:online', { users: onlineUsers });
  
  // Mark user as online
  await presence.setStatus(userId, {
    status: 'online',
    connectedAt: Date.now()
  });
});

// Handle disconnections
server.onDisconnect(async (socket) => {
  const userId = socket.get('userId');
  await presence.setStatus(userId, {
    status: 'offline',
    lastSeen: Date.now()
  });
});

​
Best Practices

  • Always clean up presence data on disconnect
  • Use heartbeats for accurate presence tracking
  • Store minimal metadata to reduce Redis memory
  • Implement timeout handling for abandoned connections
  • Consider using rooms for large-scale presence tracking
  • Cache online user lists for frequently accessed data

​
Next Steps

Rooms

Learn about rooms

State Management

Managing state in Redis