http-request-manager 18.7.21 → 18.7.24

package/HTTP_STATE_MANAGER_README.md

@@ -1,948 +0,0 @@
-# HTTP Manager State Service
-
-The `HTTPManagerStateService` extends `ComponentStore` to provide robust state management with built-in HTTP request handling and WebSocket integration for CRUD operations.
-
-## Overview
-
-This service combines HTTP requests with local state management, automatically updating the local store when CRUD operations succeed. It integrates with WebSockets to keep the state synchronized with server-side changes.
-
-### Key Features
-
-- **ComponentStore Integration** - Extends NGRX ComponentStore for robust state management
-- **Automatic CRUD Updates** - `createRecord`, `updateRecord`, and `deleteRecord` automatically update local state
-- **WebSocket Sync** - Real-time synchronization with server via WebSocket channels
-- **Database Support** - IndexedDB caching integration for offline-first applications
-- **Selectors** - Built-in selectors like `data$` and `selectRecord$(id)` for data access
-- **Pagination** - State tracking for paginated data
-- **Streaming Support** - Real-time data streaming integration
-
-## Installation
-
-```typescript
-import { HttpRequestManagerModule } from 'http-request-manager';
-
-@NgModule({
-  imports: [HttpRequestManagerModule.forRoot({})]
-})
-export class AppModule { }
-```
-
-## Basic Usage
-
-### Creating a State Service
-
-```typescript
-import { Injectable } from '@angular/core';
-import { HTTPManagerStateService, ApiRequest, DataType } from 'http-request-manager';
-
-interface User {
-  id: number;
-  name: string;
-  email: string;
-  active: boolean;
-}
-
-@Injectable({
-  providedIn: 'root'
-})
-export class UserStateService extends HTTPManagerStateService<User> {
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['users'],
-        adapter: User.adapt, // Required for Database Storage
-        ws: {
-          id: 'USERS123',  // Base name - automatically becomes SYS-USERS123
-          wsServer: 'ws://localhost:8080',
-          retry: { times: 3, delay: 5 }
-        }
-      }),
-      DataType.ARRAY,
-      DatabaseStorage.adapt({
-        table: 'users-cache',
-        expiresIn: '1d'  // Cache for 1 day
-      })
-    );
-  }
-
-  // Public API methods
-  loadUsers() { 
-    this.fetchRecords(); 
-  }
-
-  addUser(user: Omit<User, 'id'>) { 
-    this.createRecord(user); 
-  }
-
-  updateUser(user: User) { 
-    this.updateRecord(user); 
-  }
-
-  deleteUser(id: number) { 
-    this.deleteRecord(id); 
-  }
-
-  getUser(id: number) {
-    return this.selectRecord$(id);
-  }
-}
-```
-
-### Using in Components
-
-```typescript
-import { Component, inject } from '@angular/core';
-import { UserStateService } from './user-state.service';
-
-@Component({
-  selector: 'app-users',
-  template: `
-    <div class="user-management">
-      <h2>User Management</h2>
-      
-      <!-- Loading State -->
-      <div *ngIf="store.isPending$ | async">
-        <div class="loading-spinner">Loading users...</div>
-      </div>
-
-      <!-- Error State -->
-      <div *ngIf="store.error$ | async as error" class="error">
-        Error: {{ error.message }}
-      </div>
-
-      <!-- User List -->
-      <div class="user-grid">
-        <div *ngFor="let user of store.data$ | async" class="user-card">
-          <div class="user-info">
-            <h3>{{ user.name }}</h3>
-            <p>{{ user.email }}</p>
-            <span class="user-status" 
-                  [class.active]="user.active"
-                  [class.inactive]="!user.active">
-              {{ user.active ? 'Active' : 'Inactive' }}
-            </span>
-          </div>
-          
-          <div class="user-actions">
-            <button (click)="store.updateUser({...user, active: !user.active})">
-              {{ user.active ? 'Deactivate' : 'Activate' }}
-            </button>
-            <button (click)="store.deleteUser(user.id)" class="delete">
-              Delete
-            </button>
-          </div>
-        </div>
-      </div>
-
-      <!-- Add User Form -->
-      <div class="add-user-form">
-        <h3>Add New User</h3>
-        <form (ngSubmit)="addUser()">
-          <input [(ngModel)]="newUser.name" name="name" placeholder="Name" required>
-          <input [(ngModel)]="newUser.email" name="email" placeholder="Email" required>
-          <label>
-            <input type="checkbox" [(ngModel)]="newUser.active" name="active">
-            Active
-          </label>
-          <button type="submit">Add User</button>
-        </form>
-      </div>
-    </div>
-  `
-})
-export class UsersComponent {
-  store = inject(UserStateService);
-  
-  newUser = {
-    name: '',
-    email: '',
-    active: true
-  };
-
-  ngOnInit() {
-    this.store.loadUsers();
-  }
-
-  addUser() {
-    if (this.newUser.name && this.newUser.email) {
-      this.store.addUser(this.newUser);
-      this.newUser = { name: '', email: '', active: true };
-    }
-  }
-}
-```
-
-## API Reference
-
-### State Interface
-
-The service manages state with the following interface:
-
-```typescript
-interface State<T> {
-  records: T[];           // Array of entities
-  record: T | null;       // Single selected entity
-  page: number;           // Current page
-  totalPages: number;     // Total pages
-  isPending: boolean;     // Loading state
-  error: any;             // Error state
-}
-```
-
-### Selectors
-
-#### data$: Observable<T[]>
-
-Get all records from the state:
-
-```typescript
-users$ = this.store.data$;
-```
-
-#### record$: Observable<T | null>
-
-Get the currently selected record:
-
-```typescript
-selectedUser$ = this.store.record$;
-```
-
-#### selectRecord$(id: any): Observable<T | undefined>
-
-Get a specific record by ID:
-
-```typescript
-user$ = this.store.selectRecord$(123);
-```
-
-#### isPending$: Observable<boolean>
-
-Check if any operation is in progress:
-
-```typescript
-loading$ = this.store.isPending$;
-```
-
-#### error$: Observable<any>
-
-Get the current error state:
-
-```typescript
-error$ = this.store.error$;
-```
-
-#### page$: Observable<number>
-
-Get the current page number:
-
-```typescript
-currentPage$ = this.store.page$;
-```
-
-#### totalPages$: Observable<number>
-
-Get the total number of pages:
-
-```typescript
-totalPages$ = this.store.totalPages$;
-```
-
-### CRUD Methods
-
-#### fetchRecords(params?: any)
-
-Fetch records from the API:
-
-```typescript
-// Basic fetch
-this.store.fetchRecords();
-
-// Fetch with parameters
-this.store.fetchRecords({ page: 1, limit: 10, search: 'john' });
-```
-
-#### createRecord(record: T)
-
-Create a new record and update state:
-
-```typescript
-this.store.createRecord({
-  name: 'John Doe',
-  email: 'john@example.com',
-  active: true
-});
-```
-
-#### updateRecord(record: T)
-
-Update an existing record and update state:
-
-```typescript
-this.store.updateRecord({
-  id: 123,
-  name: 'John Smith',
-  email: 'john.smith@example.com',
-  active: true
-});
-```
-
-#### deleteRecord(id: any)
-
-Delete a record and update state:
-
-```typescript
-this.store.deleteRecord(123);
-```
-
-#### setPage(page: number)
-
-Set the current page:
-
-```typescript
-this.store.setPage(2);
-```
-
-#### setTotalPages(total: number)
-
-Set the total number of pages:
-
-```typescript
-this.store.setTotalPages(10);
-```
-
-## WebSocket Integration
-
-The HTTPManagerStateService automatically handles WebSocket connections for real-time state synchronization.
-
-### Channel Types
-
-The service uses three types of WebSocket channels:
-
-| Channel Type | Prefix | Description | Purpose |
-|--------------|--------|-------------|---------|
-| **STATE** | `SYS-` | State synchronization | CRUD operations sync |
-| **MESSAGE** | `MES-` | Messaging channels | Real-time messaging |
-| **NOTIFICATION** | `PUB-` | Notification channels | System notifications |
-
-### Configuration
-
-```typescript
-constructor() {
-  super(
-    ApiRequest.adapt({
-      server: 'http://localhost:8080',
-      path: ['users'],
-      ws: {
-        id: 'USERS123',        // Base name becomes SYS-USERS123
-        wsServer: 'ws://localhost:8080',
-        jwtToken: 'your-jwt-token',
-        retry: { times: 3, delay: 5 }
-      }
-    }),
-    DataType.ARRAY
-  );
-}
-```
-
-### WebSocket Observables
-
-#### connectionStatus$: Observable<boolean>
-
-Monitor WebSocket connection status:
-
-```typescript
-connectionStatus$ = this.store.connectionStatus$;
-
-// Usage
-<div *ngIf="store.connectionStatus$ | async; disconnected" class="connection-status">
-  Connected
-</div>
-
-<ng-template #disconnected>
-  <div class="connection-status offline">
-    Reconnecting...
-  </div>
-</ng-template>
-```
-
-#### communicationMessages$: Observable<any[]>
-
-Monitor incoming messages:
-
-```typescript
-messages$ = this.store.communicationMessages$;
-```
-
-#### notificationMessages$: Observable<any[]>
-
-Monitor notifications:
-
-```typescript
-notifications$ = this.store.notificationMessages$;
-```
-
-### WebSocket Methods
-
-#### initializeConnection(wsServer: string, jwtToken: string, user: any)
-
-Initialize WebSocket connection:
-
-```typescript
-this.store.initializeConnection(
-  'ws://localhost:8080',
-  'jwt-token-here',
-  { id: 1, name: 'John Doe', email: 'john@example.com' }
-);
-```
-
-#### setApiRequestOptions(options: ApiRequest)
-
-Update API and WebSocket configuration at runtime:
-
-```typescript
-this.store.setApiRequestOptions(
-  ApiRequest.adapt({
-    ...this.store.apiRequestOptions,
-    ws: {
-      ...this.store.apiRequestOptions.ws,
-      wsServer: 'wss://new-server.com/ws'
-    }
-  })
-);
-```
-
-#### createChannel(channelName: string)
-
-Create a new messaging channel:
-
-```typescript
-// Creates PUB-{channelName}
-this.store.createChannel('general-chat');
-```
-
-#### subscribeToChannel(channelName: string)
-
-Subscribe to a messaging channel:
-
-```typescript
-// Subscribes to PUB-{channelName}
-this.store.subscribeToChannel('general-chat');
-```
-
-#### unsubscribeFromChannel(channelName: string)
-
-Unsubscribe from a channel:
-
-```typescript
-this.store.unsubscribeFromChannel('general-chat');
-```
-
-#### sendMessage(content: any, channels: string[])
-
-Send a message to specific channels:
-
-```typescript
-this.store.sendMessage(
-  { message: 'Hello everyone!' },
-  ['general-chat', 'team-updates']
-);
-```
-
-### Real-time CRUD Operations
-
-The service automatically syncs state changes via WebSocket:
-
-```typescript
-// When createRecord() is called:
-// 1. Makes HTTP POST request
-// 2. On success, updates local state
-// 3. Sends WebSocket message to SYS-{id} channel
-// 4. Other clients receive the message and update their state
-
-// When other clients call createRecord:
-// 1. They send WebSocket message to SYS-{id} channel
-// 2. This client receives the message
-// 3. Automatically calls fetchRecords() to get updated data
-```
-
-## Database Storage Integration
-
-For offline-first applications, configure IndexedDB caching:
-
-```typescript
-@Injectable()
-export class UserStateService extends HTTPManagerStateService<User> {
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['users'],
-        adapter: User.adapt  // Required for Database Storage
-      }),
-      DataType.ARRAY,
-      DatabaseStorage.adapt({
-        table: 'users-cache',
-        expiresIn: '1d'  // Cache expires in 1 day
-      })
-    );
-  }
-}
-```
-
-### Caching Behavior
-
-1. **First Request**: Fetches from server and saves to IndexedDB
-2. **Subsequent Requests**: Checks IndexedDB first, uses cached data if valid
-3. **Cache Expiry**: Automatically fetches from server when cache expires
-4. **Offline Mode**: Uses cached data when network is unavailable
-
-## Advanced Examples
-
-### Pagination State Service
-
-```typescript
-@Injectable()
-export class PaginatedUserStateService extends HTTPManagerStateService<User> {
-
-  private currentPage = signal(1);
-  private pageSize = signal(10);
-  private searchQuery = signal('');
-  private sortBy = signal('name');
-  private sortOrder = signal<'asc' | 'desc'>('asc');
-
-  // Computed selectors
-  totalPages = computed(() => Math.ceil(this.store.data$().length / this.pageSize()));
-  
-  paginatedData = computed(() => {
-    const data = this.store.data$();
-    const start = (this.currentPage() - 1) * this.pageSize();
-    const end = start + this.pageSize();
-    return data.slice(start, end);
-  });
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['users'],
-        adapter: User.adapt
-      }),
-      DataType.ARRAY
-    );
-  }
-
-  loadUsers() {
-    const params = {
-      page: this.currentPage(),
-      limit: this.pageSize(),
-      search: this.searchQuery(),
-      sortBy: this.sortBy(),
-      sortOrder: this.sortOrder()
-    };
-    
-    this.fetchRecords(params);
-  }
-
-  setPage(page: number) {
-    this.currentPage.set(page);
-    this.loadUsers();
-  }
-
-  setPageSize(size: number) {
-    this.pageSize.set(size);
-    this.currentPage.set(1); // Reset to first page
-    this.loadUsers();
-  }
-
-  setSearchQuery(query: string) {
-    this.searchQuery.set(query);
-    this.currentPage.set(1); // Reset to first page
-    this.loadUsers();
-  }
-
-  setSorting(sortBy: string, order: 'asc' | 'desc') {
-    this.sortBy.set(sortBy);
-    this.sortOrder.set(order);
-    this.currentPage.set(1); // Reset to first page
-    this.loadUsers();
-  }
-}
-```
-
-### Real-time Chat with State Management
-
-```typescript
-@Injectable()
-export class ChatStateService extends HTTPManagerStateService<ChatMessage> {
-
-  private currentUser = signal<any>(null);
-  private activeChannel = signal<string>('general');
-
-  // Observables
-  messages$ = this.store.data$;
-  channelUsers$ = this.store.communicationMessages$;
-  connectionStatus$ = this.store.connectionStatus$;
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['messages'],
-        adapter: ChatMessage.adapt,
-        ws: {
-          id: 'CHAT_WS',
-          wsServer: 'ws://localhost:8080'
-        }
-      }),
-      DataType.ARRAY
-    );
-  }
-
-  initializeChat(user: any) {
-    this.currentUser.set(user);
-    this.store.initializeConnection(
-      'ws://localhost:8080',
-      user.jwtToken,
-      user
-    );
-  }
-
-  joinChannel(channelName: string) {
-    this.activeChannel.set(channelName);
-    this.store.createChannel(channelName);
-    this.store.subscribeToChannel(channelName);
-  }
-
-  leaveChannel(channelName: string) {
-    this.store.unsubscribeFromChannel(channelName);
-    if (this.activeChannel() === channelName) {
-      this.activeChannel.set('general');
-    }
-  }
-
-  sendMessage(message: string) {
-    const channel = this.activeChannel();
-    const user = this.currentUser();
-    
-    if (!channel || !user) return;
-
-    // Create message record (HTTP)
-    this.createRecord({
-      id: Date.now(), // Temporary ID
-      content: message,
-      channel: channel,
-      userId: user.id,
-      userName: user.name,
-      timestamp: new Date()
-    });
-
-    // Send via WebSocket
-    this.store.sendMessage(
-      {
-        message: message,
-        userId: user.id,
-        userName: user.name,
-        channel: channel
-      },
-      [channel]
-    );
-  }
-
-  getMessagesForChannel(channelName: string) {
-    return this.store.data$.pipe(
-      map(messages => messages.filter(msg => msg.channel === channelName))
-    );
-  }
-}
-```
-
-### Complex Filter and Search State
-
-```typescript
-@Injectable()
-export class AdvancedUserStateService extends HTTPManagerStateService<User> {
-
-  // Filter state
-  activeFilter = signal<'all' | 'active' | 'inactive'>('all');
-  roleFilter = signal<string>('');
-  searchQuery = signal<string>('');
-  dateRange = signal<{start: Date, end: Date} | null>(null);
-
-  // Computed filters
-  filteredUsers = computed(() => {
-    let users = this.store.data$();
-    
-    // Apply active filter
-    if (this.activeFilter() !== 'all') {
-      const isActive = this.activeFilter() === 'active';
-      users = users.filter(user => user.active === isActive);
-    }
-
-    // Apply role filter
-    if (this.roleFilter()) {
-      users = users.filter(user => user.role === this.roleFilter());
-    }
-
-    // Apply search query
-    if (this.searchQuery()) {
-      const query = this.searchQuery().toLowerCase();
-      users = users.filter(user => 
-        user.name.toLowerCase().includes(query) ||
-        user.email.toLowerCase().includes(query)
-      );
-    }
-
-    // Apply date range
-    if (this.dateRange()) {
-      const { start, end } = this.dateRange()!;
-      users = users.filter(user => {
-        const userDate = new Date(user.createdAt);
-        return userDate >= start && userDate <= end;
-      });
-    }
-
-    return users;
-  });
-
-  filterStats = computed(() => {
-    const allUsers = this.store.data$();
-    return {
-      total: allUsers.length,
-      active: allUsers.filter(u => u.active).length,
-      inactive: allUsers.filter(u => !u.active).length,
-      filtered: this.filteredUsers().length
-    };
-  });
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['users'],
-        adapter: User.adapt
-      }),
-      DataType.ARRAY,
-      DatabaseStorage.adapt({
-        table: 'users-advanced-cache',
-        expiresIn: '1h'
-      })
-    );
-  }
-
-  // Filter methods
-  setActiveFilter(filter: 'all' | 'active' | 'inactive') {
-    this.activeFilter.set(filter);
-    this.fetchRecords();
-  }
-
-  setRoleFilter(role: string) {
-    this.roleFilter.set(role);
-    this.fetchRecords();
-  }
-
-  setSearchQuery(query: string) {
-    this.searchQuery.set(query);
-    // Debounced search
-    setTimeout(() => this.fetchRecords(), 300);
-  }
-
-  setDateRange(start: Date, end: Date) {
-    this.dateRange.set({ start, end });
-    this.fetchRecords();
-  }
-
-  clearFilters() {
-    this.activeFilter.set('all');
-    this.roleFilter.set('');
-    this.searchQuery.set('');
-    this.dateRange.set(null);
-    this.fetchRecords();
-  }
-}
-```
-
-## Error Handling and Retry Logic
-
-### Custom Error Handling
-
-```typescript
-@Injectable()
-export class RobustUserStateService extends HTTPManagerStateService<User> {
-
-  private retryAttempts = signal(0);
-  private maxRetries = signal(3);
-
-  constructor() {
-    super(
-      ApiRequest.adapt({
-        server: 'http://localhost:8080',
-        path: ['users'],
-        retry: { times: 3, delay: 2 },
-        displayError: true
-      }),
-      DataType.ARRAY
-    );
-  }
-
-  // Override to add custom error handling
-  fetchRecords(params?: any) {
-    this.retryAttempts.set(0);
-    super.fetchRecords(params);
-  }
-
-  // Custom retry logic for critical operations
-  criticalUpdate(user: User) {
-    try {
-      this.updateRecord(user);
-    } catch (error) {
-      this.handleCriticalError(error, () => this.criticalUpdate(user));
-    }
-  }
-
-  private handleCriticalError(error: any, retryFn: () => void) {
-    const currentAttempts = this.retryAttempts();
-    const maxAttempts = this.maxRetries();
-
-    if (currentAttempts < maxAttempts) {
-      this.retryAttempts.set(currentAttempts + 1);
-      
-      // Exponential backoff
-      const delay = Math.pow(2, currentAttempts) * 1000;
-      setTimeout(retryFn, delay);
-    } else {
-      // Max retries reached, show critical error
-      this.showCriticalErrorDialog(error);
-    }
-  }
-
-  private showCriticalErrorDialog(error: any) {
-    // Implement your critical error handling
-    console.error('Critical operation failed after retries:', error);
-  }
-}
-```
-
-## Best Practices
-
-### 1. Service Layer Pattern
-
-```typescript
-// ✅ Good
-@Injectable()
-export class UserStateService extends HTTPManagerStateService<User> {
-  // Business logic methods
-  activateUser(id: number) {
-    this.updateRecord({ id, active: true });
-  }
-
-  deactivateUser(id: number) {
-    this.updateRecord({ id, active: false });
-  }
-}
-
-// ❌ Avoid
-@Component({
-  template: `<div (click)="store.updateRecord(...)">`
-})
-export class BadComponent {}
-```
-
-### 2. Proper State Management
-
-```typescript
-// ✅ Good
-loadUsers() {
-  this.fetchRecords(); // Uses internal state management
-}
-
-// ❌ Avoid
-loadUsers() {
-  this.http.get('users').subscribe(users => {
-    this.users = users; // Manual state management
-  });
-}
-```
-
-### 3. WebSocket Error Handling
-
-```typescript
-// ✅ Good
-initializeConnection(wsServer: string, jwtToken: string, user: any) {
-  try {
-    this.setApiRequestOptions(
-      ApiRequest.adapt({
-        ...this.apiRequestOptions,
-        ws: { ...this.apiRequestOptions.ws, wsServer, jwtToken, user }
-      })
-    );
-  } catch (error) {
-    console.error('WebSocket initialization failed:', error);
-  }
-}
-```
-
-### 4. Memory Management
-
-```typescript
-@Component({ template: '...' })
-export class UserComponent implements OnDestroy {
-  private destroy$ = new Subject<void>();
-
-  ngOnInit() {
-    this.store.data$
-      .pipe(takeUntil(this.destroy$))
-      .subscribe();
-  }
-
-  ngOnDestroy() {
-    this.destroy$.next();
-    this.destroy$.complete();
-  }
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-#### 1. WebSocket Not Connecting
-```typescript
-// Check configuration
-console.log('WS Config:', this.store.apiRequestOptions?.ws);
-
-// Verify connection
-this.store.connectionStatus$.subscribe(status => {
-  console.log('WebSocket status:', status);
-});
-```
-
-#### 2. State Not Updating
-```typescript
-// Ensure adapter is provided for database storage
-ApiRequest.adapt({
-  path: ['users'],
-  adapter: User.adapt // Required!
-});
-```
-
-#### 3. Infinite Loops
-```typescript
-// Avoid calling fetchRecords() in response to WebSocket messages
-// The service handles this automatically
-
-// ❌ Don't do this
-communicationMessages$.subscribe(msg => {
-  this.fetchRecords(); // This can cause loops
-});
-```
-
-## Related Documentation
-
-- [HTTP Manager Service](http-manager/README.md)
-- [HTTP Signals Service](http-signals/README.md)
-- [WebSocket Service](websocket/README.md)
-- [Database Manager Service](database/README.md)
-- [Architecture Overview](../architecture/README.md)