Socket Client

The Socket Client provides raw WebSocket messaging through named channels. Join channels, publish messages, send direct messages, and track presence.

Access the Socket Client via realtime.socketClient:

const socketClient = realtime.socketClient;

Methods

`joinChannel(channel)`

Join a named channel. You will receive events published to this channel by other clients.

joinChannel(channel: string): void

Parameter	Type	Required	Description
`channel`	`string`	Yes	Channel name to join. Arbitrary string — you define the naming convention (e.g. `"chat:room1"`, `"notifications:user123"`)

Returns: void — the join is fire-and-forget; the server confirms via the underlying Socket.IO ack.

realtime.socketClient.joinChannel('chat:room1');

`leaveChannel(channel)`

Leave a previously joined channel. You will stop receiving events from this channel.

leaveChannel(channel: string): void

Parameter	Type	Required	Description
`channel`	`string`	Yes	Channel name to leave

Returns: void

realtime.socketClient.leaveChannel('chat:room1');

`publish(channel, event, data)`

Send a message to all members of a channel.

publish(channel: string, event: string, data: unknown): void

Parameter	Type	Required	Description
`channel`	`string`	Yes	Target channel name (e.g. `"chat:room1"`)
`event`	`string`	Yes	Event name — a label for the type of message (e.g. `"message"`, `"typing"`, `"reaction"`)
`data`	`unknown`	Yes	Event payload — any JSON-serializable value (object, string, number, array, etc.)

Returns: void — the publish is fire-and-forget. All members of the channel (except the sender) receive the event.

realtime.socketClient.publish('chat:room1', 'message', {
  text: 'Hello everyone!',
  sender: 'user123',
  timestamp: Date.now(),
});

realtime.socketClient.publish('chat:room1', 'typing', {
  userId: 'user123',
  isTyping: true,
});

`directMessage(targetSocketId, event, data)`

Send a message directly to a specific connected client identified by their socket ID.

directMessage(targetSocketId: string, event: string, data: unknown): void

Parameter	Type	Required	Description
`targetSocketId`	`string`	Yes	The Socket.IO socket ID of the recipient client (e.g. `"abc123"`)
`event`	`string`	Yes	Event name for the message (e.g. `"notification"`, `"invite"`)
`data`	`unknown`	Yes	Message payload — any JSON-serializable value

Returns: void — only the targeted client receives the event. No channel membership is required.

realtime.socketClient.directMessage('abc123', 'notification', {
  text: 'You have a new message',
  from: 'user456',
});

realtime.socketClient.directMessage(targetSocketId, 'invite', {
  roomId: 'chat:room2',
  invitedBy: currentUser.name,
});

Listening for Messages

Use the RealtimeClient's event system to listen for incoming socket events:

// Global listener — receives events from ALL subscribed topics
realtime.on('event', (event) => {
  if (event.source === 'socket') {
    console.log('Channel:', event.topic);
    console.log('Data:', event.payload);
  }
});

// Topic-specific listener
realtime.subscribe({ topic: 'chat:room1' });
realtime.on('event:chat:room1', (event) => {
  console.log('Chat message:', event.payload);
});

Channel Naming

Channel names are arbitrary strings. Common patterns:

chat:room1              # Chat room
notifications:user123   # User notifications
game:match5             # Game session
dashboard:team-alpha    # Team dashboard

Example: Chat Room

import { RealtimeClient } from '@smarterservices/realtime';

const realtime = new RealtimeClient({
  url: 'http://localhost:3000',
  token: userToken,
});

// Join the room
realtime.socketClient.joinChannel('chat:room1');

// Subscribe to messages
realtime.subscribe({ topic: 'chat:room1' });
realtime.on('event:chat:room1', (event) => {
  displayMessage(event.payload);
});

// Send a message
function sendMessage(text: string) {
  realtime.socketClient.publish('chat:room1', 'message', {
    text,
    sender: currentUser.id,
    timestamp: Date.now(),
  });
}

// Leave when done
function leaveRoom() {
  realtime.socketClient.leaveChannel('chat:room1');
}