http-request-manager 18.15.33 → 18.15.34

package/src/docs/HTTP_STATE_MANAGER_README.md

@@ -0,0 +1,1391 @@
+# HTTP Manager State Service
+
+The `HTTPManagerStateService` is a comprehensive state management service that combines HTTP requests, WebSocket real-time updates, and IndexedDB persistence.
+
+## Features
+
+- **HTTP CRUD Operations**: Fetch, create, update, and delete records
+- **WebSocket Integration**: Real-time synchronization across clients
+- **IndexedDB Persistence**: Cache data locally with expiration
+- **State Management**: Built on NgRx ComponentStore
+- **Automatic Retry**: Configurable retry logic for failed requests
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { HTTPManagerStateService, ApiRequest, DataType, DatabaseStorage } from 'http-request-manager';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class MyStateService extends HTTPManagerStateService<MyDataType> {
+
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'https://api.example.com',
+        path: ['items'],
+        adapter: MyDataType.adapt  // Model adapter
+      }),
+      DataType.ARRAY,
+      DatabaseStorage.adapt({
+        table: 'my_items',
+        expiresIn: '1h'  // Cache expiration
+      })
+    );
+  }
+}
+```
+
+### Database Operations
+
+#### Clear Database Table
+
+Clears all records from the configured IndexedDB table and resets in-memory state.
+
+```typescript
+// Clear the database (subscription handled internally)
+myStateService.clearDatabase();
+
+// This will:
+// 1. Clear all records from the IndexedDB table
+// 2. Clear the in-memory state (set to empty array or object)
+// 3. Log success/error messages to console
+// 4. NOT re-fetch from API - data remains empty until manually refreshed
+// 5. NOT clear localStorage metadata (expiration info is preserved)
+```
+
+**Example in Component:**
+
+```typescript
+@Component({
+  selector: 'app-my-component',
+  template: `
+    <button (click)="onClearDatabase()">Clear Cache</button>
+  `
+})
+export class MyComponent {
+  myStateService = inject(MyStateService);
+
+  onClearDatabase() {
+    // Simple call - no subscription needed
+    this.myStateService.clearDatabase();
+  }
+}
+```
+
+**Console Output:**
+```
+🗑️ Clearing database table: my_items
+clearTable: Starting clear for table: my_items
+clearTable: Clearing table 'my_items'...
+clearTable: ✅ Table 'my_items' cleared successfully
+✅ Database table my_items cleared successfully
+```
+
+### CRUD Operations
+
+```typescript
+// Fetch all records
+service.fetchRecords();
+
+// Fetch single record
+service.fetchRecord({ path: ['items', 123] }, 'GET');
+
+// Create record
+service.createRecord(newData, { path: ['items'] });
+
+// Update record
+service.updateRecord(updatedData, { path: ['items', 123] });
+
+// Delete record
+service.deleteRecord({ path: ['items', 123] });
+```
+
+### Request Tracking Options (Database Only)
+
+The state manager supports query-tracking options on `fetchRecords` and `fetchStream`.
+
+```typescript
+service.fetchRecords(RequestOptions.adapt({
+  path: ['ai/pagination?page=0&size=25'],
+  ignoreQueryParams: ['page', 'size'],
+  queryParamsExpiresIn: '10s',
+  watchParams: ['category', 'status'],
+  watchExpiresAt: 1715904000
+}));
+```
+
+Options:
+
+- `ignoreQueryParams`: Query parameter keys to exclude from request-change tracking.
+- `queryParamsExpiresIn`: Expiry duration for tracked values (e.g., `'10s'`, `'5mn'`, `'1h'`).
+- `watchParams`: Specific query parameter keys to watch for change detection in variation mode. When set, only these params are tracked; others are ignored.
+- `watchExpiresAt`: Epoch timestamp (in seconds) when tracked values expire. Alternative to `queryParamsExpiresIn` for absolute expiry.
+
+Scope and behavior:
+
+- Database enabled (`DatabaseStorage` configured): tracker is active and can prevent repeated identical API calls until expiry resets tracked values.
+- Database disabled: tracker is not enabled; requests go straight to API.
+- `forceRefresh: true` bypasses tracking and always makes the API request.
+
+### WebSocket Integration
+
+```typescript
+// Automatic real-time sync when WebSocket is configured
+ApiRequest.adapt({
+  server: 'https://api.example.com',
+  ws: {
+    wsServer: 'wss://ws.example.com',
+    id: 'my-channel',
+    jwtToken: 'your-jwt-token',
+    retry: { times: 3, delay: 5 }
+  }
+});
+```
+
+## Configuration Options
+
+### ApiRequest
+- `server`: Backend API server URL
+- `path`: Array of path segments
+- `adapter`: Function to transform API response to your model
+- `ws`: WebSocket configuration
+- `retry`: Retry options for failed requests
+
+### DatabaseStorage
+- `table`: IndexedDB table name
+- `expiresIn`: Cache expiration (e.g., '1h', '30mn', '5mn')
+
+### DataType
+- `ARRAY`: For list data (default)
+- `OBJECT`: For single object data
+
+## Notes
+
+- The `clearDatabase()` method handles subscription internally for simplicity
+- Database operations are asynchronous and logged to console
+- Clearing the database does NOT trigger a refresh - call `fetchRecords()` after clearing if needed
+
+The `HTTPManagerStateService` is a comprehensive state management service that combines HTTP requests, WebSocket real-time updates, and IndexedDB persistence.
+
+## Features
+
+- **HTTP CRUD Operations**: Fetch, create, update, and delete records
+- **WebSocket Integration**: Real-time synchronization across clients
+- **IndexedDB Persistence**: Cache data locally with expiration
+- **State Management**: Built on NgRx ComponentStore
+- **Automatic Retry**: Configurable retry logic for failed requests
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { HTTPManagerStateService, ApiRequest, DataType, DatabaseStorage } from 'http-request-manager';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class MyStateService extends HTTPManagerStateService<MyDataType> {
+
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'https://api.example.com',
+        path: ['items'],
+        adapter: MyDataType.adapt  // Model adapter
+      }),
+      DataType.ARRAY,
+      DatabaseStorage.adapt({
+        table: 'my_items',
+        expiresIn: '1h'  // Cache expiration
+      })
+    );
+  }
+}
+```
+
+### Database Operations
+
+#### Clear Database Table
+
+Clears all records from the configured IndexedDB table and resets in-memory state.
+
+```typescript
+// Clear the database (subscription handled internally)
+myStateService.clearDatabase();
+
+// This will:
+// 1. Clear all records from the IndexedDB table
+// 2. Clear the in-memory state (set to empty array or object)
+// 3. Log success/error messages to console
+// 4. NOT re-fetch from API - data remains empty until manually refreshed
+// 5. NOT clear localStorage metadata (expiration info is preserved)
+```
+
+**Example in Component:**
+
+```typescript
+@Component({
+  selector: 'app-my-component',
+  template: `
+    <button (click)="onClearDatabase()">Clear Cache</button>
+  `
+})
+export class MyComponent {
+  myStateService = inject(MyStateService);
+
+  onClearDatabase() {
+    // Simple call - no subscription needed
+    this.myStateService.clearDatabase();
+  }
+}
+```
+
+**Console Output:**
+```
+🗑️ Clearing database table: my_items
+clearTable: Starting clear for table: my_items
+clearTable: Clearing table 'my_items'...
+clearTable: ✅ Table 'my_items' cleared successfully
+✅ Database table my_items cleared successfully
+```
+
+### CRUD Operations
+
+```typescript
+// Fetch all records
+service.fetchRecords();
+
+// Fetch single record
+service.fetchRecord({ path: ['items', 123] }, 'GET');
+
+// Create record
+service.createRecord(newData, { path: ['items'] });
+
+// Update record
+service.updateRecord(updatedData, { path: ['items', 123] });
+
+// Delete record
+service.deleteRecord({ path: ['items', 123] });
+```
+
+### WebSocket Integration
+
+```typescript
+// Automatic real-time sync when WebSocket is configured
+ApiRequest.adapt({
+  server: 'https://api.example.com',
+  ws: {
+    wsServer: 'wss://ws.example.com',
+    id: 'my-channel',
+    jwtToken: 'your-jwt-token',
+    retry: { times: 3, delay: 5 }
+  }
+});
+```
+
+## Configuration Options
+
+### ApiRequest
+- `server`: Backend API server URL
+- `path`: Array of path segments
+- `adapter`: Function to transform API response to your model
+- `ws`: WebSocket configuration
+- `retry`: Retry options for failed requests
+
+### DatabaseStorage
+- `table`: IndexedDB table name
+- `expiresIn`: Cache expiration (e.g., '1h', '30mn', '5mn')
+
+### DataType
+- `ARRAY`: For list data (default)
+- `OBJECT`: For single object data
+
+## Notes
+
+- The `clearDatabase()` method handles subscription internally for simplicity
+- Database operations are asynchronous and logged to console
+- Clearing the database does NOT trigger a refresh - call `fetchRecords()` after clearing if needed
+
+The `HTTPManagerStateService` is a comprehensive state management solution that extends NGRX `ComponentStore` to provide unified HTTP request handling, WebSocket real-time synchronization, and offline-first data persistence.
+
+## Overview
+
+This service serves as the central hub for managing application state, combining:
+- **HTTP CRUD operations** with automatic local state updates
+- **WebSocket integration** for real-time multi-user synchronization
+- **IndexedDB persistence** for offline-first applications
+- **Pagination and streaming** support out of the box
+- **Message tracking** with guaranteed delivery
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  HTTPManagerStateService                     │
+│                     (ComponentStore)                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
+│  │   HTTP       │  │  WebSocket   │  │  Database    │      │
+│  │   Manager    │◀─   Manager    │◀─┤   Manager    │      │
+│  │   Service    │  │  (Singleton) │  │   Service    │      │
+│  └──────────────┘  └──────────────┘  └──────────────┘      │
+│         │                   │                   │           │
+│         ▼                   ▼                   ▼           │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              Local State (ComponentStore)            │   │
+│  │  - data$ (records)                                   │   │
+│  │  - page$, totalPages$, percentage$                   │   │
+│  │  - isPending$, error$                                │   │
+│  │  - userList$, channels$, messages$                   │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Features
+
+- **ComponentStore Integration** - Extends NGRX ComponentStore for localized, performant state management
+- **Automatic CRUD Updates** - `createRecord`, `updateRecord`, and `deleteRecord` automatically update local state and sync via WebSocket
+- **WebSocket Real-Time Sync** - Multi-user synchronization with channel-based messaging and user presence tracking
+- **Guaranteed Message Delivery** - MessageTrackerService ensures no messages are missed during disconnections
+- **Database Support** - IndexedDB caching integration for offline-first applications with automatic sync
+- **Pagination State** - Built-in tracking for page, totalPages, and loading percentage
+- **Streaming Support** - Real-time data streaming with AI streaming patterns
+- **Notification System** - Dedicated notification channels with date filtering and latest notification tracking
+- **User Presence** - Track active users per channel and across all channels
+
+## 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
+}
+```
+
+### WSOptions Model (Updated)
+
+The `WSOptions` model has been updated with the following changes:
+
+```typescript
+interface WSOptionsInterface {
+  id: string,
+  wsServer: string,
+  jwtToken: string,
+  permissions?: string[],
+  channels?: string[],        // ✅ Available
+  user?: any,
+  retry?: RetryOptions,
+  // wsUpdateChannels?: string[]  ❌ Removed
+}
+```
+
+**Breaking Changes:**
+- `wsUpdateChannels` property has been **removed** from `WSOptionsInterface` and `WSOptions` class
+- Channel management is now handled through the `channels` array and automatic detection
+- Legacy message format support is maintained for backward compatibility
+
+### 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$;
+```
+
+#### operationSuccess$: Observable\<OperationResultModel | null\>
+
+Get feedback after `createRecord`, `updateRecord`, or `deleteRecord` operations. Emits `{ success: true, operation: 'CREATE' | 'UPDATE' | 'DELETE' }` when data is successfully pushed into state.
+
+```typescript
+this.store.operationSuccess$.subscribe(result => {
+  if (result?.success) {
+    // result.operation tells you which CRUD action completed
+    showSuccessToast(`${result.operation} succeeded!`);
+  }
+});
+```
+
+**Example in Component:**
+
+```typescript
+@Component({
+  selector: 'app-users',
+  template: `
+    <button (click)="store.deleteUser(user.id)">Delete</button>
+    <div *ngIf="lastOperation" class="toast">
+      {{ lastOperation.operation }} {{ lastOperation.success ? 'succeeded' : 'failed' }}
+    </div>
+  `
+})
+export class UsersComponent {
+  store = inject(UserStateService);
+  lastOperation: OperationResultModel | null = null;
+
+  constructor() {
+    this.store.operationSuccess$.subscribe(result => {
+      this.lastOperation = result;
+      // Auto-clear after 3 seconds
+      setTimeout(() => this.lastOperation = null, 3000);
+    });
+  }
+}
+```
+
+> **Note:** `operationSuccess$` only emits on successful HTTP responses that update local state. It does not emit on errors — use `error$` for error handling.
+
+#### 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 |
+
+### Channel Management (Updated)
+
+> **Breaking Change:** The `wsUpdateChannels` property has been removed from `WSOptionsInterface` and `WSOptions` class.
+
+Channel management has been improved and simplified:
+
+1. **Automatic Channel Detection**: The service now automatically constructs the expected channel name from the API path and environment configuration
+2. **Dynamic Channel Matching**: Messages are matched against expected channels based on the pattern: `${env}/${path.join('/')}`
+3. **Fallback Support**: Legacy message formats are still supported for backward compatibility
+
+```typescript
+// Before (deprecated)
+ws: {
+  id: 'USERS123',
+  wsUpdateChannels: ['MES-users', 'MES-updates'], // ❌ No longer supported
+  wsServer: 'ws://localhost:8080'
+}
+
+// After (current)
+ws: {
+  id: 'USERS123',
+  channels: ['custom-channel-1', 'custom-channel-2'], // ✅ Use channels array
+  wsServer: 'ws://localhost:8080'
+}
+```
+
+### 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
+  );
+}
+```
+
+> **Note:** The `wsUpdateChannels` property has been removed from `WSOptions`. WebSocket channel management is now handled dynamically through the `channels` property and automatic channel detection based on the API path and environment configuration.
+
+### 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']
+);
+```
+
+**Implementation Note:** The service now uses optimized batch messaging with `sendChannelMessageToChannels()` for better performance when sending to multiple channels simultaneously.
+
+### 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
+```
+
+**Updated Message Handling:**
+The service now implements enhanced message processing:
+- **Automatic Channel Detection**: Messages are matched against expected channels using `${env}/${path.join('/')}` pattern
+- **Optimized Batch Messaging**: Uses `sendChannelMessageToChannels()` for better performance
+- **Legacy Format Support**: Maintains backward compatibility with older message formats
+- **Enhanced Error Handling**: Improved error handling during service initialization
+
+## 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)