http-request-manager 18.15.33 → 18.15.34

package/src/docs/MESSAGE_TRACKER_SIGNALS_README.md

@@ -0,0 +1,563 @@
+<!-- markdownlint-disable MD031 MD033 MD060 -->
+
+# Message Tracker Signals Service
+
+The `MessageTrackerSignalsService` provides signal-based message tracking, channel metadata, and user presence for real-time Angular applications.
+
+## Overview
+
+This service is a **signal-based wrapper** around the WebSocket message tracking system, designed for Angular 19+ applications that want reactive message tracking with automatic updates.
+
+### Key Features
+
+- ✅ **Signal-Based Tracking** - Messages, metadata, presence as signals
+- ✅ **Computed Statistics** - Message counts, active channels as computed signals
+- ✅ **Automatic Updates** - Reacts to WebSocket messages automatically
+- ✅ **Channel Metadata** - Track message counts, last messages per channel
+- ✅ **User Presence** - Track users in channels
+- ✅ **Observable Interop** - Provides both signals and observables
+
+## Installation
+
+```typescript
+import { MessageTrackerSignalsService } from 'http-request-manager';
+```
+
+## Basic Usage
+
+### Message Tracking Example
+
+```typescript
+import { Component, inject, computed, effect } from '@angular/core';
+import { MessageTrackerSignalsService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-message-tracker',
+  template: `
+    <div class="tracker">
+      <h2>Message Tracker</h2>
+      
+      <div class="stats">
+        <p>Total Messages: {{ totalMessages() }}</p>
+        <p>Active Channels: {{ activeChannels().length }}</p>
+      </div>
+      
+      <div class="channels">
+        <h3>Channels</h3>
+        @for (channel of activeChannels(); track channel) {
+          <div class="channel">
+            <h4>{{ channel }}</h4>
+            <p>Messages: {{ getMessageCount(channel) }}</p>
+            <p>Last: {{ getLastMessagePreview(channel) }}</p>
+          </div>
+        }
+      </div>
+      
+      <div class="latest-message">
+        <h3>Latest Message</h3>
+        @if (latestMessage()) {
+          <div class="message">
+            <strong>{{ latestMessage().user }}</strong>
+            <span>{{ latestMessage().content }}</span>
+          </div>
+        }
+      </div>
+    </div>
+  `
+})
+export class MessageTrackerComponent {
+  private tracker = inject(MessageTrackerSignalsService);
+  
+  // Signals
+  messages = this.tracker.messages;
+  channelMetadata = this.tracker.channelMetadata;
+  usersInChannels = this.tracker.usersInChannels;
+  
+  // Computed signals
+  totalMessages = this.tracker.messageCount;
+  activeChannels = this.tracker.activeChannels;
+  
+  latestMessage = computed(() => this.messages());
+  
+  constructor() {
+    // Subscribe to a channel
+    this.tracker.subscribeToChannel('general');
+    
+    // React to new messages
+    effect(() => {
+      const message = this.messages();
+      if (message) {
+        console.log('New message:', message);
+      }
+    });
+  }
+  
+  getMessageCount(channel: string): number {
+    return this.tracker.getMessageCount(channel);
+  }
+  
+  getLastMessagePreview(channel: string): string {
+    const last = this.tracker.getLastMessage(channel);
+    return last ? last.content : 'No messages';
+  }
+  
+  getUsersInChannel(channel: string): string[] {
+    return this.tracker.getUsersInChannel(channel);
+  }
+}
+```
+
+## API Reference
+
+### Message Tracking
+
+#### `trackMessage(message: any): void`
+
+Manually tracks a message.
+
+```typescript
+tracker.trackMessage({
+  id: 'msg-1',
+  channel: 'general',
+  user: 'user123',
+  content: 'Hello!',
+  timestamp: new Date().toISOString()
+});
+```
+
+### Channel Management
+
+#### `subscribeToChannel(channel: string): void`
+
+Subscribes to and tracks a channel.
+
+```typescript
+tracker.subscribeToChannel('general');
+```
+
+#### `unsubscribeFromChannel(channel: string): void`
+
+Unsubscribes from and stops tracking a channel.
+
+```typescript
+tracker.unsubscribeFromChannel('general');
+```
+
+### User Presence
+
+#### `removeUserFromChannel(channel: string, user: string): void`
+
+Removes a user from channel tracking.
+
+```typescript
+tracker.removeUserFromChannel('general', 'user123');
+```
+
+### Selectors
+
+#### `getMessageCount(channel: string): number`
+
+Gets message count for a channel.
+
+```typescript
+count = tracker.getMessageCount('general');
+```
+
+#### `getLastMessage(channel: string): any`
+
+Gets last message for a channel.
+
+```typescript
+lastMessage = tracker.getLastMessage('general');
+```
+
+#### `getActiveChannels(): string[]`
+
+Gets list of active channels.
+
+```typescript
+channels = tracker.getActiveChannels();
+```
+
+#### `getUsersInChannel(channel: string): string[]`
+
+Gets users in a channel.
+
+```typescript
+users = tracker.getUsersInChannel('general');
+// Returns: ['user1', 'user2', 'user3']
+```
+
+### Signals
+
+#### `messages: ReadonlySignal<any>`
+
+Latest message signal.
+
+```typescript
+message = this.tracker.messages;
+// Usage: message()
+```
+
+#### `channelMetadata: ReadonlySignal<Map<string, any>>`
+
+Channel metadata signal.
+
+```typescript
+metadata = this.tracker.channelMetadata;
+// Usage: metadata()
+// Map structure: { channel -> { count, lastMessage, lastUpdated } }
+```
+
+#### `usersInChannels: ReadonlySignal<Map<string, Set<string>>>`
+
+User presence signal.
+
+```typescript
+users = this.tracker.usersInChannels;
+// Usage: users()
+// Map structure: { channel -> Set<userIds> }
+```
+
+### Computed Signals
+
+#### `messageCount: ComputedSignal<number>`
+
+Total message count across all channels.
+
+```typescript
+total = this.tracker.messageCount;
+// Usage: total()
+```
+
+#### `activeChannels: ComputedSignal<string[]>`
+
+List of active channel names.
+
+```typescript
+channels = this.tracker.activeChannels;
+// Usage: channels()
+```
+
+### Observables (Interop)
+
+#### `messages$: Observable<any>`
+
+Messages as observable stream.
+
+```typescript
+this.tracker.messages$.subscribe(message => {
+  console.log('New message:', message);
+});
+```
+
+#### `channelMetadata$: Observable<Map<string, any>>`
+
+Channel metadata as observable.
+
+```typescript
+this.tracker.channelMetadata$.subscribe(metadata => {
+  console.log('Metadata:', metadata);
+});
+```
+
+#### `usersInChannels$: Observable<Map<string, Set<string>>>`
+
+User presence as observable.
+
+```typescript
+this.tracker.usersInChannels$.subscribe(users => {
+  console.log('Users:', users);
+});
+```
+
+## Advanced Examples
+
+### Real-Time Channel Statistics
+
+```typescript
+import { Component, inject, computed, signal } from '@angular/core';
+import { MessageTrackerSignalsService } from 'http-request-manager';
+
+interface ChannelStats {
+  name: string;
+  messageCount: number;
+  userCount: number;
+  lastMessage?: any;
+  lastActivity: string;
+}
+
+@Component({
+  selector: 'app-channel-stats',
+  template: `
+    <div class="stats-grid">
+      @for (stat of channelStats(); track stat.name) {
+        <div class="stat-card">
+          <h3>{{ stat.name }}</h3>
+          <div class="metrics">
+            <div class="metric">
+              <span class="label">Messages</span>
+              <span class="value">{{ stat.messageCount }}</span>
+            </div>
+            <div class="metric">
+              <span class="label">Users</span>
+              <span class="value">{{ stat.userCount }}</span>
+            </div>
+          </div>
+          <div class="last-activity">
+            Last activity: {{ stat.lastActivity | date:'short' }}
+          </div>
+        </div>
+      }
+    </div>
+  `
+})
+export class ChannelStatsComponent {
+  private tracker = inject(MessageTrackerSignalsService);
+  
+  channelStats = computed(() => {
+    const channels = this.tracker.activeChannels();
+    const metadata = this.tracker.channelMetadata();
+    const users = this.tracker.usersInChannels();
+    
+    return channels.map(channel => ({
+      name: channel,
+      messageCount: this.tracker.getMessageCount(channel),
+      userCount: this.tracker.getUsersInChannel(channel).length,
+      lastMessage: this.tracker.getLastMessage(channel),
+      lastActivity: metadata.get(channel)?.lastUpdated || Date.now()
+    }));
+  });
+}
+```
+
+### User Presence Tracker
+
+```typescript
+import { Component, inject, computed } from '@angular/core';
+import { MessageTrackerSignalsService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-user-presence',
+  template: `
+    <div class="presence">
+      <h3>Channel Users</h3>
+      
+      <select [value]="selectedChannel()" (change)="selectedChannel.set($any($event.target).value)">
+        @for (channel of channels(); track channel) {
+          <option [value]="channel">{{ channel }}</option>
+        }
+      </select>
+      
+      <div class="users-list">
+        <h4>Users in {{ selectedChannel() }} ({{ userCount() }})</h4>
+        <ul>
+          @for (user of users(); track user) {
+            <li>
+              <span class="user-status online"></span>
+              {{ user }}
+            </li>
+          }
+        </ul>
+      </div>
+    </div>
+  `
+})
+export class UserPresenceComponent {
+  private tracker = inject(MessageTrackerSignalsService);
+  
+  selectedChannel = signal('general');
+  channels = this.tracker.activeChannels;
+  
+  users = computed(() => 
+    this.tracker.getUsersInChannel(this.selectedChannel())
+  );
+  
+  userCount = computed(() => this.users().length);
+}
+```
+
+### Message Activity Dashboard
+
+```typescript
+import { Component, inject, computed } from '@angular/core';
+import { MessageTrackerSignalsService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-activity-dashboard',
+  template: `
+    <div class="dashboard">
+      <header>
+        <h1>Message Activity Dashboard</h1>
+        <div class="summary">
+          <span>Total: {{ totalMessages() }}</span>
+          <span>Channels: {{ channelsCount() }}</span>
+          <span>Users: {{ totalUsers() }}</span>
+        </div>
+      </header>
+      
+      <div class="activity-feed">
+        <h2>Recent Activity</h2>
+        @for (activity of recentActivity(); track activity.id) {
+          <div class="activity-item">
+            <span class="channel">{{ activity.channel }}</span>
+            <span class="user">{{ activity.user }}</span>
+            <span class="content">{{ activity.content }}</span>
+            <span class="time">{{ activity.timestamp | date:'short' }}</span>
+          </div>
+        }
+      </div>
+      
+      <div class="channel-activity">
+        <h2>Channel Activity</h2>
+        @for (stat of channelActivity(); track stat.channel) {
+          <div class="channel-stat">
+            <span class="name">{{ stat.channel }}</span>
+            <span class="count">{{ stat.messages }} messages</span>
+            <progress [value]="stat.percentage" max="100"></progress>
+          </div>
+        }
+      </div>
+    </div>
+  `
+})
+export class ActivityDashboardComponent {
+  private tracker = inject(MessageTrackerSignalsService);
+  
+  messages = this.tracker.messages;
+  metadata = this.tracker.channelMetadata;
+  totalMessages = this.tracker.messageCount;
+  channels = this.tracker.activeChannels;
+  
+  channelsCount = computed(() => this.channels().length);
+  
+  totalUsers = computed(() => {
+    const users = this.tracker.usersInChannels();
+    const allUsers = new Set<string>();
+    users.forEach(userSet => userSet.forEach(user => allUsers.add(user)));
+    return allUsers.size;
+  });
+  
+  recentActivity = computed(() => {
+    // In a real app, maintain a history array
+    const message = this.messages();
+    return message ? [message] : [];
+  });
+  
+  channelActivity = computed(() => {
+    const channels = this.channels();
+    const total = this.totalMessages() || 1;
+    
+    return channels.map(channel => ({
+      channel,
+      messages: this.tracker.getMessageCount(channel),
+      percentage: (this.tracker.getMessageCount(channel) / total) * 100
+    }));
+  });
+}
+```
+
+## Comparison with Non-Signal Version
+
+| Feature | Non-Signal Version | Signal Version |
+|---------|-------------------|----------------|
+| **Message Tracking** | BehaviorSubject | Angular Signals |
+| **Metadata** | BehaviorSubject<Map> | Signal<Map> |
+| **User Presence** | BehaviorSubject<Map> | Signal<Map> |
+| **Selectors** | Methods returning values | Computed signals |
+| **Statistics** | Manual calculation | Computed signals |
+| **Updates** | Manual `.next()` calls | Automatic |
+| **Angular Version** | 14-18 | 19+ |
+
+## Best Practices
+
+1. **Use Computed Signals for Derived State**
+   ```typescript
+   // ✅ Good
+   messageCount = computed(() => {
+     const metadata = this.tracker.channelMetadata();
+     let count = 0;
+     metadata.forEach(data => count += data.count);
+     return count;
+   });
+   
+   // ❌ Avoid
+   getMessageCount() {
+     // Manual calculation in method
+   }
+   ```
+
+2. **Leverage Automatic Tracking**
+   ```typescript
+   // ✅ Good - Automatic via effect
+   constructor() {
+     effect(() => {
+       const message = this.tracker.messages();
+       if (message) {
+         this.handleNewMessage(message);
+       }
+     });
+   }
+   
+   // ❌ Avoid - Manual subscription
+   this.tracker.messages$.subscribe(msg => {});
+   ```
+
+3. **Use Selectors for Access**
+   ```typescript
+   // ✅ Good - Use provided selectors
+   count = this.tracker.getMessageCount('general');
+   users = this.tracker.getUsersInChannel('general');
+   
+   // ❌ Avoid - Direct map access
+   metadata = this.tracker.channelMetadata();
+   count = metadata.get('general')?.count;
+   ```
+
+4. **Combine with WebSocket Signals**
+   ```typescript
+   // ✅ Good - Use both services together
+   private wsManager = inject(WebSocketSignalsManagerService);
+   private tracker = inject(MessageTrackerSignalsService);
+   
+   // Messages flow automatically from WS to tracker
+   ```
+
+## Troubleshooting
+
+### Messages Not Tracked
+
+**Problem**: Messages signal not updating
+
+**Solution**: Ensure WebSocket connection is active and you're subscribed to channels
+```typescript
+wsManager.connect(options, token);
+tracker.subscribeToChannel('your-channel');
+```
+
+### Metadata Not Updating
+
+**Problem**: Channel metadata stale
+
+**Solution**: Ensure messages are being tracked
+```typescript
+// Messages should auto-track via effect
+// Or manually track
+tracker.trackMessage(message);
+```
+
+### User Presence Empty
+
+**Problem**: No users showing in channels
+
+**Solution**: Ensure user presence is being updated
+```typescript
+// Users are tracked when messages arrive with user field
+tracker.trackMessage({ user: 'user123', channel: 'general' });
+```
+
+## Related Documentation
+
+- [Signal Services Index](./SIGNAL_SERVICES_README.md)
+- [WebSocket Signals](./WEBSOCKET_SIGNALS_README.md)
+- [Advanced WebSocket Guide](./ADVANCED_WEBSOCKET.md)