Realtime API

All realtime types are exported from the rhttp.io/socket.io.client entry point.

Factory functions

import {
  createRealtimeClient,
  initializeSocketClient,
  getSocketClient,
  socket,
} from "rhttp.io/socket.io.client";

Function	Description
`createRealtimeClient(c)`	Creates a new `RealtimeClient` instance.
`initializeSocketClient(c)`	Creates (or returns existing) singleton.
`getSocketClient()`	Returns the singleton or `null`.
`socket`	Object with `.instance`, `.create()`, `.connect()`, `.disconnect()`, `.destroy()`.

`RealtimeClientConfig`

interface RealtimeClientConfig {
  socketUrl: string;
  withCredentials?: boolean;
  extraHeaders?: Record<string, string>;
  auth?: {
    token?: string;
    scheme?: string;
    getToken?: () => Promise<string | null>;
    authFactory?: () => Promise<Record<string, any>>;
  };
  csrf?: {
    enabled: boolean;
    fetchEndpoint: string;
    headerName?: string;    // default: "X-CSRF-Token"
    cookieName?: string;    // default: "csrf-token"
    fetchOptions?: RequestInit;
  };
  rooms?: {
    autoRejoin?: boolean;
    autoJoin?: string[];
  };
  offlineQueue?: {
    enabled: boolean;
    maxSize?: number;       // default: 100
    storageKey?: string;    // default: "rhttp.io/realtime:offline-queue"
  };
  reconnection?: boolean;            // default: true
  reconnectionDelay?: number;        // default: 1000 ms
  reconnectionDelayMax?: number;     // default: 5000 ms
  reconnectionAttempts?: number;     // default: Infinity
  transports?: string[];             // default: ["websocket", "polling"]
  socketOptions?: Record<string, any>;
  logger?: boolean | any;
  eventValidator?: (event: string, data: any, direction: "emit" | "receive") => boolean | Promise<boolean>;
  eventTransformer?: (event: string, data: any, direction: "emit" | "receive") => any | Promise<any>;
  hooks?: {
    onConnect?: () => void | Promise<void>;
    onDisconnect?: (reason: string) => void | Promise<void>;
    onError?: (error: any) => void | Promise<void>;
  };
}

`RealtimeClientInstance`

The full client interface returned by createRealtimeClient().

Connection

isConnected: boolean;
isConnecting: boolean;
isReconnecting: boolean;
connect(): Promise<void>;     // idempotent, 10s timeout
disconnect(): void;
destroy(): void;              // disconnect + clear all state

Events

emit(event: string, data?: any, callback?: (response: any) => void): void;
emitWithAck(event: string, data?: any, timeout?: number): Promise<any>;
on(event: string, handler: (data: any) => void): () => void;       // returns unsubscribe
off(event: string, handler?: (data: any) => void): void;
once(event: string, handler: (data: any) => void): () => void;    // returns unsubscribe

Rooms

joinRoom(room: string): Promise<void>;
leaveRoom(room: string): Promise<void>;
getRooms(): string[];
isInRoom(room: string): boolean;

Offline queue

getQueueLength(): number;
clearQueue(): void;
flushQueue(): Promise<void>;

State & metrics

onStateChange(handler: (state: ConnectionState) => void): () => void;
getMetrics(): RealtimeMetrics;

`RealtimeMetrics`

interface RealtimeMetrics {
  totalEventsEmitted: number;
  totalEventsReceived: number;
  reconnectAttempts: number;
  queuedMessages: number;
  uptime: number;
  averageLatency: number;
  connectionStartTime: number | null;
}

`ConnectionState`

interface ConnectionState {
  connected: boolean;
  connecting: boolean;
  reconnecting: boolean;
}

`OfflineMessage`

interface OfflineMessage {
  id: string;
  event: string;
  data: any;
  timestamp: number;
  room?: string;
}

React hooks

All hooks are imported from rhttp.io/socket.io.client and require a <RealtimeProvider> ancestor.

import {
  RealtimeProvider,
  useRealtimeClient,
  useConnectionState,
  useSocketEvent,
  useSocketEventOnce,
  useSocketEvents,
  useRoomEvent,
  useSocketEmit,
  useSocketEmitWithAck,
  useRoomManagement,
  useOfflineQueue,
  useConnectionMetrics,
  useSocketConnection,
} from "rhttp.io/socket.io.client";

Hook signatures

Hook	Returns
`useRealtimeClient()`	`RealtimeClientInstance` — throws if no provider
`useConnectionState()`	`{ connected: boolean; connecting: boolean; reconnecting: boolean }`
`useSocketEvent(event, handler)`	`void` — subscribes, auto-cleans on unmount
`useSocketEventOnce(event, handler)`	`void` — one-shot listener, auto-cleans
`useSocketEvents(events)`	`void` — `events: Record<string, handler>`
`useRoomEvent(room, event, handler)`	`void` — joins room on mount, listens, leaves on unmount
`useSocketEmit()`	`(event: string, data?: any, callback?: (res: any) => void) => void`
`useSocketEmitWithAck()`	`(event: string, data?: any, timeout?: number) => Promise<any>`
`useRoomManagement()`	`{ joinRoom, leaveRoom, getRooms, isInRoom }`
`useOfflineQueue()`	`{ getQueueLength, clearQueue, flushQueue }`
`useConnectionMetrics()`	`RealtimeMetrics`
`useSocketConnection()`	`{ connected, connecting, reconnecting, connect, disconnect }`

`RealtimeProvider` props

<RealtimeProvider
  client={RealtimeClientInstance}    // required
  autoConnect?: boolean              // default: true
  prefetchCsrf?: boolean             // default: true
  onConnected?: () => void
  onDisconnected?: (reason: string) => void
  onError?: (error: Error) => void
>
  {children}
</RealtimeProvider>

Realtime errors

import {
  RealtimeError,
  ConnectionError,
  RoomError,
  TimeoutError as RealtimeTimeoutError,
} from "rhttp.io/socket.io.client";

Class	Code	Thrown when
`RealtimeError`	—	Base error for the realtime module
`ConnectionError`	`CONNECTION_ERROR`	Connection timeout or failure
`RoomError`	`ROOM_ERROR`	Server rejects a room join
`RealtimeTimeoutError`	`TIMEOUT_ERROR`	`emitWithAck` exceeds timeout

Realtime Guide — usage guide with examples.
React Integration — HTTP queries in React.

Suggest changes to this page