http-request-manager 18.15.34 → 18.16.1

package/src/docs/MESSAGE_TRACKER_SIGNALS_README.md

@@ -1,563 +0,0 @@
-<!-- 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)