npm package: @royaltics/ui
Description: 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 resubscriptio
Latest version: 2.0.2

# @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.

```tsx
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):

```tsx
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).

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.