Socket.IO v4+ Integration (Typed Events, Ack & Connection State Recovery)
Unlike raw browser WebSocket, Socket.IO v4+ handles namespace multiplexing, rooms, automatic reconnection, packet buffering during disconnects, and delivery Acknowledgements.
When integrating Socket.IO into a @pravosleva/reactive-engine v3.0.1 service, follow modern Socket.IO v4 best practices:
- Strict event contracts (
Socket<ServerToClientEvents, ClientToServerEvents>): Define all incoming and outgoing events using TypeScript interfaces withoutany. - Dynamic
authcallback (auth: (cb) => cb({ token })): Instead of passing a static object at initialization time, read the auth token from a reactive signal on every initial connection and automatic reconnect. - Promise-based acknowledgements (
emitWithAck): Usesocket.timeout(5000).emitWithAck(...)instead of legacy nested callbacks. - Checking
socket.recovered: Leverage Connection State Recovery so the service knows whether missed packets were automatically replayed by the server or if history must be re-fetched viaresource.refresh().
Practical Example: Typed Chat & Presence (ChatSocketService.ts)
typescript
import { io, type Socket } from 'socket.io-client'
import { AbstractService } from '@pravosleva/reactive-engine'
export interface ChatMessage {
id: string
roomId: string
author: string
text: string
sentAt: number
}
// 1. Strict contract for server-to-client events
interface ServerToClientEvents {
'message:new': (msg: ChatMessage) => void
'room:onlineCount': (payload: { roomId: string; count: number }) => void
}
// 2. Strict contract for client-to-server events (with Ack support)
interface ClientToServerEvents {
'room:join': (
roomId: string,
ack: (response: { ok: boolean; error?: string }) => void
) => void
'message:send': (
payload: { roomId: string; text: string },
ack: (response: { ok: boolean; message?: ChatMessage; error?: string }) => void
) => void
}
type TypedChatSocket = Socket<ServerToClientEvents, ClientToServerEvents>
export class ChatSocketService extends AbstractService {
// Reactive auth and active room parameters
public authToken = this.engine.signal<string | null>(null, 'sio:authToken')
public activeRoomId = this.engine.signal<string | null>('general', 'sio:activeRoom')
// Reactive connection and data state
public isConnected = this.engine.signal(false, 'sio:isConnected')
public isRecovered = this.engine.signal(false, 'sio:isRecovered')
public onlineCount = this.engine.signal(0, 'sio:onlineCount')
public messages = this.engine.signal<ChatMessage[]>([], 'sio:messages')
private socket: TypedChatSocket | null = null
// Reactive lifecycle controller: connects the socket only when an auth token is present
private stopConnectionEffect = this.engine.effect(() => {
const token = this.authToken.value
if (!token) {
this.teardownSocket()
return
}
if (!this.socket) {
this.initSocket()
}
if (this.socket && !this.socket.connected) {
this.socket.connect()
}
}, 'sio:connectionEffect')
// Reactive room controller: re-subscribes whenever activeRoomId changes
private stopRoomEffect = this.engine.effect(() => {
const roomId = this.activeRoomId.value
const connected = this.isConnected.value
if (!connected || !roomId || !this.socket) return
this.messages.value = []
void this.joinRoom(roomId)
}, 'sio:roomEffect')
private initSocket() {
const socket: TypedChatSocket = io('https://example.com', {
autoConnect: false,
transports: ['websocket', 'polling'],
// Dynamic auth callback (Socket.IO v4 standard):
// reads the latest token on every initial connect and automatic reconnect
auth: (cb) => {
cb({ token: this.authToken.value })
},
})
socket.on('connect', () => {
this.isConnected.value = true
// Check Connection State Recovery flag (Socket.IO v4.6+):
// if false, session state was not restored and we must explicitly rejoin the room
this.isRecovered.value = socket.recovered
if (!socket.recovered && this.activeRoomId.value) {
void this.joinRoom(this.activeRoomId.value)
}
})
socket.on('disconnect', () => {
this.isConnected.value = false
})
socket.on('message:new', (msg) => {
// Filter incoming frames for the currently active room
if (msg.roomId === this.activeRoomId.value) {
this.messages.value = [...this.messages.value, msg]
}
})
socket.on('room:onlineCount', ({ roomId, count }) => {
if (roomId === this.activeRoomId.value) {
this.onlineCount.value = count
}
})
this.socket = socket
}
/**
* Joins the target room on the server and awaits an acknowledgement within 5 seconds.
*
* @param roomId Room identifier read from `this.activeRoomId.value`.
*/
private async joinRoom(roomId: string) {
if (!this.socket?.connected) return
try {
const ack = await this.socket.timeout(5000).emitWithAck('room:join', roomId)
if (!ack.ok) {
console.warn(`Failed to join room ${roomId}:`, ack.error)
}
} catch {
console.warn(`Acknowledgement timed out while joining room ${roomId}`)
}
}
/**
* Sends a message to the active room and resolves with the server-confirmed payload.
*/
public async sendMessage(text: string): Promise<ChatMessage | null> {
const roomId = this.activeRoomId.value
if (!this.socket?.connected || !roomId || !text.trim()) {
return null
}
const ack = await this.socket
.timeout(5000)
.emitWithAck('message:send', { roomId, text: text.trim() })
if (!ack.ok || !ack.message) {
throw new Error(ack.error || 'Server rejected the message')
}
return ack.message
}
private teardownSocket() {
if (this.socket) {
this.socket.removeAllListeners()
this.socket.disconnect()
this.socket = null
}
this.isConnected.value = false
this.isRecovered.value = false
}
public dispose() {
this.stopConnectionEffect()
this.stopRoomEffect()
this.teardownSocket()
}
}Usage in Vanilla JS or UI Layer
typescript
import { ReactiveEngine } from '@pravosleva/reactive-engine'
import { ChatSocketService } from './ChatSocketService.js'
const engine = new ReactiveEngine()
const chat = engine.inject(ChatSocketService)
// Observe connection state, online user count, and incoming messages
engine.effect(() => {
console.log(
`[Socket.IO] connected=${chat.isConnected.value} | recovered=${chat.isRecovered.value} | online=${chat.onlineCount.value}`
)
})
engine.effect(() => {
console.log('Messages in room:', chat.messages.value.length)
})
// 1. Setting the auth token automatically triggers io().connect() with fresh credentials
chat.authToken.value = 'Bearer eyJhbGciOiJIUzI1Ni...'
// 2. Switching rooms automatically dispatches room:join via emitWithAck
chat.activeRoomId.value = 'engineering'
// 3. Send a message and await server confirmation (5-second timeout)
await chat.sendMessage('Hello, team!')
// 4. Clean up on logout or module unmount
// chat.authToken.value = null
// chat.dispose()Production Best Practices (Socket.IO v4+)
- Use
autoConnect: falsewith a dynamicauthcallback: Passingauth: { token: signal.value }as a static object duringio()initialization causes automatic reconnects to replay an expired JWT. Usingauth: (cb) => cb({ token: this.authToken.value })ensures the freshest token is read on every reconnection attempt. - Handle
socket.recoveredfor hybrid sync: In Socket.IO v4.6+, Connection State Recovery automatically replays missed packets after brief disconnects (socket.recovered === true). For longer outages (socket.recovered === false), bind a history-fetchingengine.resourceto this flag so missed messages are restored cleanly. - Call
socket.removeAllListeners()beforedisconnect(): Explicitly stripping listeners insideteardownSocket()prevents closure leaks when a user logs in and out multiple times during a single SPA session.