http-request-manager 18.7.7 → 18.7.9

package/README.md

@@ -1,5 +1,91 @@
 # Request Manager Service Documentation
 
+## Overview
+
+The `http-request-manager` is a comprehensive Angular library that provides enterprise-grade HTTP request management, state management, real-time communication, and local data persistence. It simplifies complex data flows and provides a unified API for handling HTTP, WebSocket, and storage operations.
+
+### Core Capabilities
+
+#### 🌐 HTTP Request Management
+
+- **Observable-based** service (`HTTPManagerService`) for reactive programming
+- **Signal-based** service (`HTTPManagerSignalsService`) for modern Angular applications
+- Automatic retry logic with configurable attempts and delays
+- Polling support with countdown timers
+- Streaming response handling (NDJSON, Server-Sent Events)
+- Request/response adapters and mappers for data transformation
+- Built-in error handling with optional toast notifications
+- File download support with progress tracking
+
+#### 🔄 State Management
+
+- **ComponentStore integration** (`HTTPManagerStateService`) for robust state management
+- Automatic CRUD state updates (Create, Read, Update, Delete)
+- Built-in selectors for data access and filtering
+- Pagination support with state tracking
+- Real-time state synchronization via WebSocket
+- IndexedDB caching for offline-first applications
+- Persistent state with LocalStorage/SessionStorage
+
+#### 💬 Real-Time Communication (WebSocket)
+
+- **Dual-mode messaging system:**
+  - **Messaging (PUB- channels)**: Real-time chat/collaboration
+  - **Notifications (MES- channels)**: Database-persisted notifications with date-range queries
+- Automatic reconnection with exponential backoff
+- JWT authentication support
+- Channel-based architecture (STATE, MESSAGE, NOTIFICATION)
+- Subscribe/unsubscribe to channels dynamically
+- Broadcast, channel, and user-specific messaging
+- Connection status monitoring
+- Session persistence across reconnections
+
+#### 💾 Data Persistence
+
+- **LocalStorage/SessionStorage** with encryption and expiration
+- **IndexedDB** integration via Dexie.js for complex queries
+- Automatic cache invalidation based on time
+- Secure encryption using symmetrical encryption service
+- Reactive storage observables for UI synchronization
+
+#### 🎯 Advanced Features
+
+- Request interception (credentials, headers, error handling)
+- Automatic loading state management
+- Database-backed notification history with epoch filtering
+- Define and load previous day's notification channels
+- Bulk operations for IndexedDB
+- Model adapters for type safety
+- Configurable global defaults via `forRoot()`
+
+### Key Benefits
+
+✅ **Reduced Boilerplate** - Eliminates repetitive HTTP and state management code  
+✅ **Type-Safe** - Full TypeScript support with generics  
+✅ **Offline-First** - Built-in IndexedDB caching for resilient applications  
+✅ **Real-Time Ready** - Seamless WebSocket integration with state management  
+✅ **Secure** - Encryption support for sensitive local data  
+✅ **Scalable** - ComponentStore-based architecture for complex state  
+✅ **Flexible** - Works with Observables or Signals based on preference  
+✅ **Battle-Tested** - Production-ready with comprehensive error handling  
+
+### Use Cases
+
+| Scenario | Solution |
+|----------|----------|
+| Simple API calls with loading states | `HTTPManagerService` |
+| Modern reactive UI with Signals | `HTTPManagerSignalsService` |
+| CRUD operations with auto state sync | `HTTPManagerStateService` |
+| Real-time chat/collaboration | `HTTPManagerStateService` + WebSocket (PUB- channels) |
+| Persistent notifications/alerts | `HTTPManagerStateService` + WebSocket (MES- channels) |
+| User preferences/settings | `LocalStorageManagerService` |
+| Offline-first data access | `DatabaseManagerService` + `HTTPManagerStateService` |
+| Large local datasets | `DatabaseManagerService` with Dexie.js |
+| Polling for live updates | `HTTPManagerService` with polling |
+| File downloads | `HTTPManagerService.downloadRequest()` |
+
+---
+
 ## Demo Component (`HttpRequestServicesDemoComponent`)
 
 The `HttpRequestServicesDemoComponent` is a comprehensive demonstration component that showcases the various services available in the `http-request-manager` library. It allows you to interactively test and visualize the functionality of HTTP services, state management, WebSockets, and local storage.
@@ -34,6 +120,357 @@ To use the demo component in your application, simply add the selector to your t
 
 The `http-request-manager` library provides a comprehensive set of services for handling HTTP requests, state management, local storage, and WebSocket communications in Angular applications.
 
+---
+
+## Quick Start Guide
+
+### Installation & Setup (2 minutes)
+
+#### 1. Import Module
+
+```typescript
+// app.module.ts
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [
+    HttpRequestManagerModule.forRoot({
+      httpRequestOptions: {
+        server: 'http://localhost:8080',  // Your API base URL
+        retry: { times: 3, delay: 2 },
+        displayError: true
+      }
+    })
+  ]
+})
+export class AppModule { }
+```
+
+#### 2. Provide APP_ID (if using encryption)
+
+```typescript
+// app.module.ts
+import { APP_ID } from '@angular/core';
+
+@NgModule({
+  providers: [
+    { provide: APP_ID, useValue: "your-unique-guid-here" }
+  ]
+})
+export class AppModule { }
+```
+
+### Quick Examples
+
+#### Example 1: Simple HTTP GET Request
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { HTTPManagerService, ApiRequest } from 'http-request-manager';
+
+@Component({
+  selector: 'app-users',
+  template: `
+    <div *ngIf="isLoading$ | async">Loading...</div>
+    <div *ngFor="let user of data$ | async">
+      {{ user.name }}
+    </div>
+  `
+})
+export class UsersComponent {
+  httpManager = inject(HTTPManagerService);
+  
+  data$ = this.httpManager.data$;
+  isLoading$ = this.httpManager.isPending$;
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    ).subscribe();
+  }
+}
+```
+
+#### Example 2: State Management with CRUD
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HTTPManagerStateService, ApiRequest, DataType } from 'http-request-manager';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+@Injectable({ providedIn: 'root' })
+export class UsersStore extends HTTPManagerStateService<User> {
+  
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        path: ['users']
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  // Public API
+  loadUsers() { this.fetchRecords(); }
+  addUser(user: User) { this.createRecord(user); }
+  updateUser(user: User) { this.updateRecord(user); }
+  deleteUser(id: number) { this.deleteRecord(id); }
+}
+
+// Component
+@Component({
+  selector: 'app-users',
+  template: `
+    <button (click)="store.loadUsers()">Load</button>
+    <div *ngFor="let user of store.data$ | async">
+      {{ user.name }}
+      <button (click)="store.deleteUser(user.id)">Delete</button>
+    </div>
+  `
+})
+export class UsersComponent {
+  store = inject(UsersStore);
+}
+```
+
+#### Example 3: WebSocket Real-Time Messaging
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ChatStore extends HTTPManagerStateService<Message> {
+  
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        path: ['messages'],
+        ws: {
+          id: 'CHAT_WS',
+          wsServer: 'ws://localhost:8080',
+          jwtToken: ''  // Add token if needed
+        }
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  joinChat(channel: string) {
+    this.createChannel(channel);
+    this.subscribeToChannel(channel);
+  }
+
+  sendMessage(channel: string, text: string, user: any) {
+    this.wsMessaging(
+      ChannelMessage.adapt({
+        sessionId: user,
+        content: { message: text }
+      }),
+      [channel]
+    );
+  }
+}
+
+// Component
+@Component({
+  template: `
+    <div *ngFor="let msg of chatStore.communicationMessages$ | async">
+      {{ msg.content.message }}
+    </div>
+    <input [(ngModel)]="messageText">
+    <button (click)="send()">Send</button>
+  `
+})
+export class ChatComponent {
+  chatStore = inject(ChatStore);
+  messageText = '';
+
+  ngOnInit() {
+    this.chatStore.joinChat('general');
+  }
+
+  send() {
+    this.chatStore.sendMessage('general', this.messageText, {
+      id: 1,
+      name: 'John'
+    });
+    this.messageText = '';
+  }
+}
+```
+
+#### Example 4: Persistent Notifications with Database
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class NotificationStore extends HTTPManagerStateService<any> {
+  
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        ws: {
+          id: 'NOTIFICATIONS',
+          wsServer: 'ws://localhost:8080'
+        }
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  initNotifications(user: any) {
+    // Get today's notification channels
+    this.getTodaysNotificationChannels();
+    
+    // Subscribe to alerts with 24h history
+    this.subscribeToNotificationChannel('alerts', {
+      startEpoch: Math.floor(Date.now() / 1000) - 86400
+    }, user);
+  }
+
+  sendAlert(message: string, priority: 'low' | 'high') {
+    this.sendNotification('alerts', {
+      message,
+      priority,
+      timestamp: Date.now()
+    });
+  }
+
+  loadPreviousDayChannels() {
+    this.definePreviousNotificationChannels();
+  }
+}
+
+// Component
+@Component({
+  template: `
+    <div *ngFor="let notif of store.notificationMessages$ | async">
+      <strong>{{ notif.user_name }}</strong>: {{ notif.content.message }}
+      <span>{{ notif.created * 1000 | date:'short' }}</span>
+    </div>
+    <button (click)="store.loadPreviousDayChannels()">
+      Load Previous Day Channels
+    </button>
+  `
+})
+export class NotificationsComponent {
+  store = inject(NotificationStore);
+
+  ngOnInit() {
+    this.store.initNotifications({
+      id: 1,
+      name: 'John',
+      email: 'john@example.com'
+    });
+  }
+}
+```
+
+#### Example 5: Local Storage with Encryption
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { LocalStorageManagerService, SettingOptions } from 'http-request-manager';
+
+@Component({
+  selector: 'app-settings'
+})
+export class SettingsComponent {
+  storage = inject(LocalStorageManagerService);
+
+  saveSettings(settings: any) {
+    this.storage.setItem(
+      'user-preferences',
+      settings,
+      SettingOptions.adapt({
+        encrypted: true,
+        expiresIn: '30d'
+      })
+    );
+  }
+
+  loadSettings() {
+    return this.storage.getItem('user-preferences');
+  }
+
+  clearSettings() {
+    this.storage.removeItem('user-preferences');
+  }
+}
+```
+
+#### Example 6: IndexedDB Caching for Offline-First
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ProductStore extends HTTPManagerStateService<Product> {
+  
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        path: ['products'],
+        adapter: (data: any) => data as Product  // Required for DB
+      }),
+      DataType.ARRAY,
+      DatabaseStorage.adapt({
+        table: 'products-cache',
+        expiresIn: '1d'  // Cache for 1 day
+      })
+    );
+  }
+
+  loadProducts() {
+    // First checks IndexedDB cache, then fetches from server if expired
+    this.fetchRecords();
+  }
+}
+```
+
+#### Example 7: Polling for Live Updates
+
+```typescript
+export class StatusComponent {
+  httpManager = inject(HTTPManagerService);
+  
+  status$ = this.httpManager.data$;
+  countdown$ = this.httpManager.countdown$;
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({
+        path: ['server-status'],
+        polling: 10  // Poll every 10 seconds
+      })
+    ).subscribe();
+  }
+
+  ngOnDestroy() {
+    this.httpManager.stopPolling();
+  }
+}
+```
+
+### Common Use Cases
+
+| Use Case | Service to Use | Key Features |
+|----------|---------------|--------------|
+| Simple API calls | `HTTPManagerService` | Observables, retry, polling |
+| Modern reactive UI | `HTTPManagerSignalsService` | Angular Signals |
+| CRUD operations | `HTTPManagerStateService` | Auto state updates |
+| Real-time chat | `HTTPManagerStateService` + WS | Messaging channels |
+| Persistent notifications | `HTTPManagerStateService` + WS | Database-backed |
+| User preferences | `LocalStorageManagerService` | Encryption, expiration |
+| Offline-first | `DatabaseManagerService` | IndexedDB |
+| Large local datasets | `DatabaseManagerService` | Querying, indexing |
+
+---
+
 ## Initialization
 
 ### 1. Module Initialization (`forRoot`)
@@ -680,6 +1117,11 @@ stateService.getNotificationChannels();
 // Get today's notification channels (from database)
 stateService.getTodaysNotificationChannels();
 
+// Define and load previous day's notification channels
+// This retrieves channels from the previous day's database records,
+// creates them in memory if needed, and broadcasts the updated list
+stateService.definePreviousNotificationChannels();
+
 // Subscribe to notifications with optional date filter
 stateService.subscribeToNotificationChannel('alerts', {
   startEpoch: Math.floor(Date.now() / 1000) - 86400,  // Last 24 hours
@@ -727,6 +1169,7 @@ The library includes a demo component showcasing notification functionality:
 
 - Create notification channels
 - View today's notification channels (from database)
+- Define previous day's channels (loads channels from previous day's data)
 - Subscribe with date range filters
 - Connect/disconnect from channels
 - Send notifications (persisted)