http-request-manager 18.15.32 → 18.15.34

package/src/docs/WEBSOCKET_SIGNALS_README.md

@@ -0,0 +1,641 @@
+<!-- markdownlint-disable MD031 MD060 -->
+
+# WebSocket Signals Manager Service
+
+The `WebSocketSignalsManagerService` provides signal-based WebSocket connection management for modern Angular applications, offering both signals and observables for maximum compatibility.
+
+## Overview
+
+This service is a **signal-based wrapper** around `WebSocketManagerService`, designed for Angular 19+ applications that want to use signals for WebSocket state while maintaining full backward compatibility.
+
+### Key Features
+
+- ✅ **Signal-Based State** - Connection status, messages, channels as signals
+- ✅ **Observable Interop** - Provides both signals and observables
+- ✅ **Singleton Pattern** - Shares single WebSocket connection
+- ✅ **Full API Parity** - All WebSocket methods available
+- ✅ **Automatic Sync** - Stays in sync with WebSocketManagerService
+
+## Installation
+
+```typescript
+import { WebSocketSignalsManagerService } from 'http-request-manager';
+```
+
+## Basic Usage
+
+### Connection Management Example
+
+```typescript
+import { Component, inject, effect } from '@angular/core';
+import { WebSocketSignalsManagerService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    <div class="chat">
+      <div class="status">
+        @if (connectionStatus()) {
+          <span class="connected">✓ Connected</span>
+        } @else {
+          <span class="disconnected">✗ Disconnected</span>
+        }
+      </div>
+      
+      <div class="messages">
+        @if (message()) {
+          <div class="message">
+            {{ message().content }}
+          </div>
+        }
+      </div>
+      
+      <div class="channels">
+        <h3>Channels ({{ channels().size }})</h3>
+        <ul>
+          @for (channel of channels(); track channel) {
+            <li>{{ channel }}</li>
+          }
+        </ul>
+      </div>
+    </div>
+  `
+})
+export class ChatComponent {
+  private wsManager = inject(WebSocketSignalsManagerService);
+  
+  // Signals for reactive state
+  connectionStatus = this.wsManager.connectionStatus;
+  message = this.wsManager.messages;
+  channels = this.wsManager.subscribedChannels;
+  
+  constructor() {
+    // Connect on init
+    this.wsManager.connect({
+      server: 'ws://localhost:8080',
+      path: ['chat']
+    }, 'jwt-token');
+    
+    // React to connection changes
+    effect(() => {
+      const connected = this.connectionStatus();
+      console.log('Connection status:', connected);
+    });
+  }
+  
+  sendMessage(content: string) {
+    this.wsManager.sendBroadcast({ content });
+  }
+  
+  joinChannel(channel: string) {
+    this.wsManager.subscribeToChannel(channel);
+  }
+  
+  leaveChannel(channel: string) {
+    this.wsManager.unsubscribeFromChannel(channel);
+  }
+  
+  disconnect() {
+    this.wsManager.disconnect();
+  }
+}
+```
+
+## API Reference
+
+### Connection Management
+
+#### `connect(options: WSOptions, jwtToken: string): void`
+
+Connects to WebSocket server.
+
+```typescript
+wsManager.connect({
+  server: 'ws://localhost:8080',
+  path: ['chat', 'notifications']
+}, 'jwt-token');
+```
+
+#### `disconnect(): void`
+
+Disconnects from WebSocket server.
+
+```typescript
+wsManager.disconnect();
+```
+
+### Channel Subscription
+
+#### `subscribeToChannel(channel: string): void`
+
+Subscribes to a WebSocket channel.
+
+```typescript
+wsManager.subscribeToChannel('chat-room-1');
+```
+
+#### `subscribeToChannels(channels: string[]): void`
+
+Subscribes to multiple channels.
+
+```typescript
+wsManager.subscribeToChannels(['chat-1', 'chat-2', 'notifications']);
+```
+
+#### `unsubscribeFromChannel(channel: string): void`
+
+Unsubscribes from a channel.
+
+```typescript
+wsManager.unsubscribeFromChannel('chat-room-1');
+```
+
+#### `getSubscribedChannels(): Set<string>`
+
+Gets currently subscribed channels.
+
+```typescript
+channels = this.wsManager.getSubscribedChannels();
+// Returns: Set { 'chat-1', 'chat-2' }
+```
+
+### Message Sending
+
+#### `sendBroadcast(content: any): void`
+
+Sends message to all connected clients.
+
+```typescript
+wsManager.sendBroadcast({
+  type: 'announcement',
+  content: 'Hello everyone!'
+});
+```
+
+#### `sendMessageInChannel(channel: string, content: any): void`
+
+Sends message in a specific channel.
+
+```typescript
+wsManager.sendMessageInChannel('chat-1', {
+  type: 'message',
+  content: 'Hi there!'
+});
+```
+
+#### `sendChannelMessage(channel: string, content: any): void`
+
+Sends channel message.
+
+```typescript
+wsManager.sendChannelMessage('chat-1', {
+  text: 'Hello channel!'
+});
+```
+
+#### `sendChannelMessageToChannels(channels: string[], content: any): void`
+
+Sends message to multiple channels.
+
+```typescript
+wsManager.sendChannelMessageToChannels(
+  ['chat-1', 'chat-2'],
+  { text: 'Broadcast to multiple channels' }
+);
+```
+
+#### `sendMessageToUser(user: string, content: any): void`
+
+Sends direct message to a user.
+
+```typescript
+wsManager.sendMessageToUser('user123', {
+  type: 'direct',
+  content: 'Private message'
+});
+```
+
+### Channel Management
+
+#### `getAllChannels(): void`
+
+Gets all available channels.
+
+```typescript
+wsManager.getAllChannels();
+```
+
+#### `createChannel(channel: string): void`
+
+Creates a new channel.
+
+```typescript
+wsManager.createChannel('new-chat-room');
+```
+
+#### `deleteChannel(channel: string): void`
+
+Deletes a channel.
+
+```typescript
+wsManager.deleteChannel('old-chat-room');
+```
+
+#### `getUsersInChannel(channel: string): void`
+
+Gets users in a channel.
+
+```typescript
+wsManager.getUsersInChannel('chat-1');
+```
+
+### Notification Methods
+
+#### `createNotificationChannel(channel: string): void`
+
+Creates notification channel.
+
+```typescript
+wsManager.createNotificationChannel('user-notifications');
+```
+
+#### `getNotificationChannels(): void`
+
+Gets notification channels.
+
+```typescript
+wsManager.getNotificationChannels();
+```
+
+#### `getTodaysNotificationChannels(): void`
+
+Gets today's notification channels.
+
+```typescript
+wsManager.getTodaysNotificationChannels();
+```
+
+#### `subscribeToNotificationChannel(channel: string, options?: any, user?: any): void`
+
+Subscribes to notification channel.
+
+```typescript
+wsManager.subscribeToNotificationChannel('alerts', {
+  priority: 'high'
+}, 'user123');
+```
+
+#### `unsubscribeFromNotificationChannel(channel: string): void`
+
+Unsubscribes from notification channel.
+
+```typescript
+wsManager.unsubscribeFromNotificationChannel('alerts');
+```
+
+#### `sendNotification(channel: string, content: any): void`
+
+Sends notification to channel.
+
+```typescript
+wsManager.sendNotification('alerts', {
+  title: 'New Alert',
+  message: 'Something happened!'
+});
+```
+
+### Signals
+
+#### `connectionStatus: ReadonlySignal<boolean>`
+
+Connection status signal.
+
+```typescript
+connected = this.wsManager.connectionStatus;
+// Usage: connected()
+```
+
+#### `messages: ReadonlySignal<any>`
+
+Latest message signal.
+
+```typescript
+message = this.wsManager.messages;
+// Usage: message()
+```
+
+#### `subscribedChannels: ReadonlySignal<Set<string>>`
+
+Subscribed channels signal.
+
+```typescript
+channels = this.wsManager.subscribedChannels;
+// Usage: channels()
+```
+
+### Observables (Interop)
+
+#### `connectionStatus$: Observable<boolean>`
+
+Connection status as observable.
+
+```typescript
+this.wsManager.connectionStatus$.subscribe(connected => {
+  console.log('Connected:', connected);
+});
+```
+
+#### `messages$: Observable<any>`
+
+Messages as observable stream.
+
+```typescript
+this.wsManager.messages$.subscribe(message => {
+  console.log('New message:', message);
+});
+```
+
+#### `subscribedChannels$: Observable<Set<string>>`
+
+Channels as observable.
+
+```typescript
+this.wsManager.subscribedChannels$.subscribe(channels => {
+  console.log('Channels:', channels);
+});
+```
+
+## Advanced Examples
+
+### Real-Time Chat Application
+
+```typescript
+import { Component, inject, signal, computed, effect } from '@angular/core';
+import { WebSocketSignalsManagerService } from 'http-request-manager';
+
+interface ChatMessage {
+  id: string;
+  user: string;
+  content: string;
+  timestamp: string;
+}
+
+@Component({
+  selector: 'app-realtime-chat',
+  template: `
+    <div class="chat-container">
+      <header>
+        <h2>Chat Room</h2>
+        <span [class.connected]="connected()">
+          {{ connected() ? '🟢 Online' : '🔴 Offline' }}
+        </span>
+      </header>
+      
+      <div class="messages-list">
+        @for (msg of messages(); track msg.id) {
+          <div class="message">
+            <strong>{{ msg.user }}</strong>
+            <span>{{ msg.content }}</span>
+            <small>{{ msg.timestamp | date:'short' }}</small>
+          </div>
+        }
+      </div>
+      
+      <div class="message-input">
+        <input 
+          [value]="messageText()" 
+          (input)="messageText.set($any($event.target).value)"
+          placeholder="Type a message..."
+          (keydown.enter)="sendMessage()">
+        <button (click)="sendMessage()">Send</button>
+      </div>
+    </div>
+  `
+})
+export class RealtimeChatComponent {
+  private wsManager = inject(WebSocketSignalsManagerService);
+  
+  // Local state
+  messageText = signal('');
+  messages = signal<ChatMessage[]>([]);
+  
+  // From WebSocket manager
+  connected = this.wsManager.connectionStatus;
+  channels = this.wsManager.subscribedChannels;
+  
+  constructor() {
+    // Connect to WebSocket
+    this.wsManager.connect({
+      server: 'ws://localhost:8080',
+      path: ['chat', 'general']
+    }, this.getJwtToken());
+    
+    // Subscribe to channel
+    this.wsManager.subscribeToChannel('general');
+    
+    // React to incoming messages
+    effect(() => {
+      const message = this.wsManager.messages();
+      if (message && message.type === 'chat') {
+        this.messages.update(msgs => [...msgs, message as ChatMessage]);
+      }
+    });
+  }
+  
+  sendMessage() {
+    const text = this.messageText();
+    if (!text.trim()) return;
+    
+    const message: ChatMessage = {
+      id: crypto.randomUUID(),
+      user: 'Current User',
+      content: text,
+      timestamp: new Date().toISOString()
+    };
+    
+    this.wsManager.sendChannelMessage('general', message);
+    this.messageText.set('');
+  }
+  
+  private getJwtToken(): string {
+    // Get JWT token from auth service
+    return 'your-jwt-token';
+  }
+}
+```
+
+### Live Notifications
+
+```typescript
+import { Injectable, inject, computed, signal } from '@angular/core';
+import { WebSocketSignalsManagerService } from 'http-request-manager';
+
+interface Notification {
+  id: string;
+  title: string;
+  message: string;
+  type: 'info' | 'warning' | 'error' | 'success';
+  timestamp: string;
+  read: boolean;
+}
+
+@Injectable({ providedIn: 'root' })
+export class NotificationService {
+  private wsManager = inject(WebSocketSignalsManagerService);
+  
+  private notificationsSignal = signal<Notification[]>([]);
+  
+  // Public signals
+  notifications = this.notificationsSignal.asReadonly();
+  unreadCount = computed(() => 
+    this.notificationsSignal().filter(n => !n.read).length
+  );
+  hasUnread = computed(() => this.unreadCount() > 0);
+  
+  constructor() {
+    // Connect to notifications channel
+    this.init();
+  }
+  
+  private init() {
+    this.wsManager.connect({
+      server: 'ws://localhost:8080',
+      path: ['notifications']
+    }, this.getJwtToken());
+    
+    this.wsManager.subscribeToNotificationChannel('user-notifications');
+    
+    // React to notifications
+    const messages = this.wsManager.messages;
+    
+    // In a real app, use effect or subscribe to messages$
+    this.wsManager.messages$.subscribe(message => {
+      if (message.type === 'notification') {
+        this.addNotification(message as Notification);
+      }
+    });
+  }
+  
+  addNotification(notification: Notification) {
+    this.notificationsSignal.update(notifications => [
+      notification,
+      ...notifications
+    ]);
+  }
+  
+  markAsRead(id: string) {
+    this.notificationsSignal.update(notifications =>
+      notifications.map(n => 
+        n.id === id ? { ...n, read: true } : n
+      )
+    );
+  }
+  
+  markAllAsRead() {
+    this.notificationsSignal.update(notifications =>
+      notifications.map(n => ({ ...n, read: true }))
+    );
+  }
+  
+  clearAll() {
+    this.notificationsSignal.set([]);
+  }
+  
+  private getJwtToken(): string {
+    return 'your-jwt-token';
+  }
+}
+```
+
+## Comparison with Non-Signal Version
+
+| Feature | Non-Signal Version | Signal Version |
+|---------|-------------------|----------------|
+| **State Management** | BehaviorSubject | Angular Signals |
+| **Connection Status** | `connectionStatus$` (Observable) | `connectionStatus` (Signal) + `connectionStatus$` |
+| **Messages** | `messages$` (Observable) | `messages` (Signal) + `messages$` |
+| **Channels** | `subscribedChannels$` | `subscribedChannels` (Signal) + `subscribedChannels$` |
+| **Methods** | All WebSocket methods | Same methods |
+| **Subscription Mgmt** | Manual | Automatic for signals |
+| **Angular Version** | 14-18 | 19+ |
+
+## Best Practices
+
+1. **Use Signals in Templates**
+   ```typescript
+   // ✅ Good - Direct signal usage
+   template: `{{ connectionStatus() ? 'Connected' : 'Disconnected' }}`
+   
+   // ❌ Avoid - Unnecessary observable conversion
+   connectionStatus$ = toObservable(this.wsManager.connectionStatus);
+   ```
+
+2. **Leverage Effect for Reactions**
+   ```typescript
+   // ✅ Good - React to message changes
+   effect(() => {
+     const message = this.wsManager.messages();
+     if (message) {
+       this.handleMessage(message);
+     }
+   });
+   ```
+
+3. **Use Both Signals and Observables**
+   ```typescript
+   // ✅ Good - Use what fits
+   signalValue = this.wsManager.connectionStatus();  // Signal
+   this.wsManager.messages$.subscribe(msg => {});    // Observable
+   ```
+
+4. **Manage Connection Lifecycle**
+   ```typescript
+   // ✅ Good - Connect on init, disconnect on destroy
+   constructor() {
+     this.wsManager.connect(options, token);
+   }
+   
+   ngOnDestroy() {
+     this.wsManager.disconnect();
+   }
+   ```
+
+## Troubleshooting
+
+### Not Receiving Messages
+
+**Problem**: Messages signal not updating
+
+**Solution**: Ensure you're subscribed to the correct channel
+```typescript
+wsManager.subscribeToChannel('your-channel');
+```
+
+### Connection Issues
+
+**Problem**: Connection status stays false
+
+**Solution**: Check WebSocket server URL and JWT token
+```typescript
+wsManager.connect({
+  server: 'ws://localhost:8080',  // Ensure correct URL
+  path: ['chat']
+}, 'valid-jwt-token');  // Ensure valid token
+```
+
+### Multiple Connections
+
+**Problem**: Multiple WebSocket connections created
+
+**Solution**: The service uses singleton pattern - only one connection exists
+```typescript
+// ✅ Good - Multiple instances share same connection
+inject(WebSocketSignalsManagerService);  // All share one connection
+```
+
+## Related Documentation
+
+- [Signal Services Index](./SIGNAL_SERVICES_README.md)
+- [Non-Signal WebSocket](./WS_MANAGER_README.md)
+- [Message Tracker Signals](./MESSAGE_TRACKER_SIGNALS_README.md)
+- [Advanced WebSocket Guide](./ADVANCED_WEBSOCKET.md)