@allem-sdk/realtime

WebSocket and SSE abstraction for React. Subscribe to channels, track presence, and monitor connection status with a provider-agnostic adapter interface.

Installation

npm install @allem-sdk/realtime

Usage

import { RealtimeProvider, useChannel, usePresence, useConnectionStatus } from "@allem-sdk/realtime";

function App() {
  return (
    <RealtimeProvider adapter={myRealtimeAdapter}>
      <ChatRoom />
    </RealtimeProvider>
  );
}

function ChatRoom() {
  const [messages, setMessages] = useState([]);
  const status = useConnectionStatus();
  const members = usePresence("room-1", { name: "Ahmed" });

  const { publish } = useChannel("room-1", (data) => {
    setMessages((prev) => [...prev, data]);
  });

  return (
    <div>
      <p>Status: {status}</p>
      <p>{members.length} online</p>
      {messages.map((m, i) => <div key={i}>{m.text}</div>)}
      <button onClick={() => publish({ text: "Hello!" })}>Send</button>
    </div>
  );
}

RealtimeAdapter Interface

Implement this interface for your WebSocket/SSE provider:

import type { RealtimeAdapter } from "@allem-sdk/realtime";

const myRealtimeAdapter: RealtimeAdapter = {
  // Required
  subscribe: (channel, callback) => {
    const ws = new WebSocket(`wss://example.com/${channel}`);
    ws.onmessage = (e) => callback(JSON.parse(e.data));
    return () => ws.close();
  },
  publish: (channel, data) => { /* send to server */ },
  getStatus: () => "connected",

  // Optional — for presence support
  subscribePresence: (channel, callback) => { /* ... */ return () => {}; },
  enterPresence: (channel, info) => { /* ... */ },
  leavePresence: (channel) => { /* ... */ },
  disconnect: () => { /* ... */ },
};

useChannel

Subscribe to a channel and get a publish function.

const { publish } = useChannel(channel: string, onMessage: (data: unknown) => void)

| Param | Type | Description | |-------|------|-------------| | channel | string | Channel name to subscribe to | | onMessage | (data: unknown) => void | Callback for incoming messages |

Returns { publish } — sends data to the same channel. Automatically unsubscribes on unmount.

usePresence

Track who is present on a channel. Joins on mount, leaves on unmount.

const members = usePresence(channel: string, info?: Record<string, unknown>)

| Param | Type | Description | |-------|------|-------------| | channel | string | Channel name | | info | Record<string, unknown> | Your presence info (name, avatar, etc.) |

Returns PresenceMember[]:

| Property | Type | Description | |----------|------|-------------| | id | string | Member identifier | | info | Record<string, unknown> | Presence info | | joinedAt | number | Join timestamp (ms since epoch) |

Requires subscribePresence and enterPresence on the adapter. No-ops if not provided.

useConnectionStatus

Returns the current connection status of the adapter.

const status = useConnectionStatus()
// "connecting" | "connected" | "disconnected" | "error"

Uses useSyncExternalStore with 1-second polling. Returns "disconnected" during SSR.

Exports

| Export | Type | Description | |--------|------|-------------| | RealtimeProvider | Component | Context provider accepting a realtime adapter | | useChannel | Hook | Subscribe to a channel, returns { publish } | | usePresence | Hook | Track and join presence on a channel | | useConnectionStatus | Hook | Current connection status string | | useRealtimeAdapter | Hook | Access the raw adapter directly |

Part of Allem SDK

This package can be used standalone or as part of the full SDK. Install allem-sdk to get all packages in one install.

Support

If you find Allem SDK useful, consider supporting its development:

License

MIT - Ahmed Allem