@royaltics/ui - WebSocket Store & Hooks

The WebSocket system provides a global Zustand store for managing connections and subscriptions, removing the need for local state management or complex context providers. It's designed for high-performance SaaS applications with automatic resubscription and flexible configuration.

1. Global Socket Initialization

Via SocketProvider (Recommended)

The SocketProvider is the most scalable way to initialize the socket in React. It automatically handles connection lifecycle based on props.

import { SocketProvider } from '@royaltics/ui/socket';

export const App = ({ userToken }) => {
  return (
    <SocketProvider 
      socketUrl="https://api.example.com" 
      token={userToken}
      path="/ws" // Optional, default: /ws
      transports={['websocket']} // Optional, default: ['websocket']
    >
      <MainLayout />
    </SocketProvider>
  );
};

Via initSocketOptions (Imperative)

If you need to initialize the socket outside of a React component (e.g., in a service or interceptor):

import { initSocketOptions } from '@royaltics/ui/socket';

initSocketOptions({
  socketUrl: 'https://socket.example.com',
  token: 'YOUR_AUTH_TOKEN_HERE',
  path: '/ws',
  onAuthError: (err) => console.error("Socket Auth failed", err)
});

2. Managing Subscriptions

The system features an Auto-Resubscription engine. When you subscribe to a topic, the store keeps track of it. If the connection drops and reconnects, the store will automatically re-emit the subscription events.

useSocketSubscription

Designed for NestJS-compatible @SubscribeMessage handlers. It manages the full lifecycle (subscribe on mount, unsubscribe on unmount).

import { useSocketSubscription } from '@royaltics/ui/socket';

export const ChatRoom = ({ roomId }) => {
    // Sends { rooms: [roomId] } to 'subscribe' event
    useSocketSubscription(`room-${roomId}`, [roomId]);

    return <div>Room: {roomId}</div>;
}

3. Emitting & Listening

useSocketState

Read connection status and access the raw emit function.

import { useSocketState } from '@royaltics/ui/socket';

export const ChatInput = () => {
    const { emit, isConnected, status } = useSocketState();

    const sendMessage = () => {
        if (!isConnected) return;
        emit('chat:message', { text: 'Hello!' });
    };

    return <button disabled={status !== 'connected'} onClick={sendMessage}>Send</button>;
};

useSocketEvent

Handle specific incoming events.

import { useSocketEvent } from '@royaltics/ui/socket';

export const NotificationToast = () => {
    useSocketEvent('notification:new', (data) => {
        console.log('New notification:', data);
    });

    return null;
}

4. Advanced Configuration

setToken(token)

Update the authentication token without resetting the entire configuration.

const { setToken } = useSocketState();
setToken('NEW_JWT_TOKEN');

SaaS Scalability

The store allows overriding the subscription event name (default: 'subscribe') and handles multi-transport fallbacks if needed.

[!TIP] Always prefer SocketProvider for React applications to ensure the socket state is strictly synced with your authentication state.