http-request-manager 19.0.0 → 22.0.0

package/README.md

@@ -1,362 +1,775 @@
-# Request Manager Service Documentation
+<!-- markdownlint-disable MD013 MD060 -->
 
-## Summary of the Lib
-The HTTPManagerService is a collection of 4 services for HTTP and Local Storage management.
+# HTTP Request Manager - Angular Library
 
-## Installation
-
-`npm install http-request-manager`
-
-## Services
-
-### HTTP Manager Service: 
-
-Http service simplifies http requests in the following ways
-  - Define a fixed endpoint service
-  - Provide a fixed set of headers or add to the headers on request
-  - Proxy Config Support
-  - Adapter for strict type checking for incoming data
-  - Mapper for data transformation for outgoing data
-  - Polling requests automatically
-  - Retry requests if failure
-  - Stream http requests from endpoint service
-  - Display Error provides a Toast (Snackbar) notification on error
-
-### HTTP State Manager Service
-
-Http service simplifies http request state management in the following ways
-  - Inherits from HTTP Manager Service for config options
-  - Creates a Component Store state (NGRX)
-  - Selectors for data and selecting data records
-  - Create, Update and Delete automatically updates data by endpoint and state on success
-  - Get keeps state of records
-
-### Database Storage Manager (Coming soon)
-  - Inherits from HTTP State Manager Service for config options
-  - Manages HTTP Requests caching data in local DB (IndexedDB) using DixieJS
-  - Requests check first local DB and if data is not stale, request is made and updates DB
-  - Expiry time/date can be set for DB records for caching
+[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![Angular](https://img.shields.io/badge/Angular-DD0031?style=flat&logo=angular&logoColor=white)](https://angular.io/)
+[![RxJS](https://img.shields.io/badge/RxJS-B7178C?style=flat&logo=reactivex&logoColor=white)](https://rxjs.dev/)
+
+> **Supported Angular:** 22.x (Angular 22 is the supported baseline. The library also retains the observable/NgRx track for older Angular 14-18 consumers and the signal track for Angular 19+ consumers, but the peer range and the toolchain target Angular 22.)
+
+A comprehensive Angular library providing enterprise-grade HTTP request management, state management, real-time communication, and local data persistence.
+
+This README is the main documentation hub for the library. Detailed service guides live in `src/docs/`, and this page links to the observable/ngrx services for older Angular applications and the signal-based services for newer Angular applications in parallel.
+
+## 🚀 Features
+
+### Core Capabilities
+
+| Feature | Description | Angular 14-18 / Observable + NgRx | Angular 19+ / Signals |
+|---------|-------------|----------------------------------|------------------------|
+| **🌐 HTTP Request Management** | Retry, polling, streaming, file downloads | [`HTTPManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md) | [`HTTPManagerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_SIGNALS_MANAGER_README.md) |
+| **🔄 State Management** | CRUD state, persistence, derived state | [`HTTPManagerStateService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_STATE_MANAGER_README.md) and [`StoreStateManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_MANAGER_README.md) | [`StoreStateManagerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_SIGNALS_README.md) |
+| **💬 Real-Time Communication** | WebSocket channels, tracking, messaging | [`WebSocketManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_MANAGER_README.md), [`WebSocketMessageService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md), and [`MessageTrackerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) | [`WebSocketSignalsManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_SIGNALS_README.md) and [`MessageTrackerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_SIGNALS_README.md) |
+| **💾 Data Persistence** | Local/session storage and offline caching | [`LocalStorageManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_README.md) and [`DatabaseManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/DATABASE_README.md) | [`LocalStorageSignalsManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_SIGNALS_README.md) |
+| **🗄️ Database Queries** | MySQL-syntax SQL queries on IndexedDB — the recommended way to query data | [`DexieSqlService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SQL_DIXIE_README.md) | Uses the same service |
+| **⚡ Utility Functions** | JSON handling, encryption, headers, validation, logging | [`UtilsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_README.md), [`Encryption`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ENCRYPTION_README.md), [`Logger`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) | Uses the same utility layer |
+| **🔧 Utility Services** | Headers, path/query, merging, base request classes | [`Utility Services`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_SERVICES_README.md) | Internal and helper services |
+
+### Key Benefits
+
+- ✅ **Type-Safe** - Full TypeScript support with generics
+- ✅ **Offline-First** - Built-in IndexedDB caching
+- ✅ **Real-Time Ready** - Seamless WebSocket integration
+- ✅ **Secure** - AES & RSA encryption support for sensitive data
+- ✅ **Scalable** - ComponentStore-based architecture
+- ✅ **Flexible** - Works with Observables or Signals
+
+Note on clearing persisted data:
+
+- **Clear full DB (fire-and-forget)**: To wipe the entire IndexedDB for this library and its associated localStorage metadata, call `DatabaseManagerService.clearDatabase()`. This method subscribes internally and is intentionally fire-and-forget — callers should simply call `databaseManager.clearDatabase()` (no `.subscribe()` required). The method also clears related localStorage metadata via `LocalStorageManagerService`.
+- **Clear a specific table (Observable)**: To remove records from a specific table, use `DatabaseManagerService.clearTableRecords(tableName)` which returns an `Observable<void>`; callers should `.subscribe()` or use RxJS operators to react to completion.
+
+### �️ Database Access
+
+The library provides two complementary services for working with IndexedDB data:
+
+| Task | Service | Example |
+|------|---------|---------|
+| **Query data** (recommended) | `DexieSqlService` | `sql.query('SELECT * FROM orders WHERE status = "open"')` |
+| **Create tables** | `DatabaseManagerService` | `db.createDatabaseTable(tableDef)` |
+| **Insert / update records** | `DatabaseManagerService` | `db.createTableRecord('orders', record)` |
+| **Delete records** | `DatabaseManagerService` | `db.deleteTableRecord('orders', id)` |
+| **Clear / reset database** | `DatabaseManagerService` | `db.clearDatabase()` |
+
+Use `DexieSqlService` for all read queries — it supports SELECT with WHERE, JOIN, ORDER BY, LIMIT, COUNT, DISTINCT, and more. Use `DatabaseManagerService` for table creation and write operations.
+
+See the full SQL syntax reference: [`DexieSqlService Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SQL_DIXIE_README.md)
+
+### �🚀 Advanced Features
+
+| Feature | Description | Learn More |
+|---------|-------------|------------|
+| **🔐 Enterprise Encryption** | AES symmetric + RSA asymmetric encryption | [`Encryption Utils`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ENCRYPTION_README.md) |
+| **🗄️ Database Queries** | MySQL-syntax SQL queries on IndexedDB — the recommended way to query data (SELECT, WHERE, JOIN, ORDER BY, LIMIT, COUNT, DISTINCT) | [`DexieSqlService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SQL_DIXIE_README.md) |
+| **📡 Streaming Support** | NDJSON & Server-Sent Events (SSE) | [`HTTP Manager`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md#streaming) |
+| **📄 File Downloads** | Progress tracking for large files | [`HTTP Manager`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md#file-downloads) |
+| **📤 File Uploads** | Multi-file upload with progress, validation, and form-data config | [`Upload Request`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UPLOAD_REQUEST_README.md) |
+| **📊 Pagination** | Built-in pagination with page tracking | [`HTTP State Manager`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_STATE_MANAGER_README.md#pagination) |
+| **🔔 Smart Notifications** | Persistent notifications with DB storage | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#notifications) |
+| **👥 Presence Tracking** | Real-time user presence by channel | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#presence) |
+| **🔄 Message Replay** | Automatic message history on reconnect | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#message-replay) and [`Message Tracker`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) |
+| **🏷️ Channel Architecture** | SYS-, PUB-, MES- channel prefixes | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#channels) |
+| **🔌 Singleton WebSocket** | Single connection across ALL instances | [`WebSocket Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ADVANCED_WEBSOCKET.md#singleton) |
+| **✨ Unified Message Service** | Type-safe WebSocket messaging with auto prefixes | [`WebSocket Message Service`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md) |
+| **🚀 Batch Requests** | Execute multiple HTTP requests with sequential/parallel modes | [`Batch Request Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/BATCH_REQUEST_README.md) |
+| **📝 Message Tracking** | Guaranteed delivery with gap detection | [`Message Tracker`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) |
+| **🔍 Debug Logging** | Context-aware logging with dev/prod modes | [`Logger Service`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) |
+
+## 📋 Table of Contents
+
+- [Quick Start](#-quick-start)
+- [Configuration](#️-configuration)
+- [Services Overview](#-services-overview)
+- [Documentation Paths](#-documentation-paths)
+- [Architecture](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ARCHITECTURE.md)
+- [Interceptors](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/INTERCEPTOR_README.md)
+- [Advanced Features](#-advanced-features)
+- [Batch Requests](#batch-requests)
+- [Detailed Documentation](#-detailed-documentation)
+- [Demo Examples](#-demo-examples)
+- [Migration Guide](#-migration-guide)
+
+## 🚀 Quick Start
+
+### 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 { }
+```
 
-### Local/Session Storage
-  - Allows for Local and Storage management for data Persistence
-  - Component Store (NGRX) State for changes on storage
-  - Encryption for data
-  - Expiry time/date can be set for stores
+#### 2. Provide APP_ID (if using encryption)
 
-## Using the Services
+```typescript
+// app.module.ts
+import { APP_ID } from '@angular/core';
 
-There are three ways to use the service, depending on your needs:
+@NgModule({
+  providers: [
+    { provide: APP_ID, useValue: "your-unique-guid-here" }
+  ]
+})
+export class AppModule { }
+```
 
-### Injecting the Service (Single Usage)
+### Simple Examples
+
+#### Basic HTTP 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 *ngIf="error$ | async as error" class="error">
+      Error: {{ error.message }}
+    </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$;
+  error$ = this.httpManager.error$;
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'], displaySuccess: true, successMessage: 'Loaded users!' })
+    ).subscribe();
+  }
+}
+```
 
-  ```ts
-  httpManagerService = inject(HTTPManagerService)
-  ```
+#### State Management with CRUD
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UsersStore extends HTTPManagerStateService<User> {
+  
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        server: 'http://localhost:8080',
+        path: ['users']
+      }),
+      DataType.ARRAY
+    );
+  }
 
-- This approach provides a singleton state for the service, as services are provided in root (@Injectable({ providedIn: 'root' })).
-- Any components or services that inject this service will share the same state, meaning they all have access to:
-  - data$ (observable for data)
-  - isPending$ (loading state)
-  - countDown$ (loading state)
-  - error$ (error state)
-  - Methods associated with the service
-  - Since there is only one shared state, it can be reused across components without creating new instances.
+  // 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);
+}
+```
 
-  Here is a very simple example
+### Request Tracking Options (Database Mode)
 
-  ```ts
-    //Define your API request details using the `ApiRequest` adapter
-    const apiOptions = ApiRequest.adapt({
-      server: 'myApiUrl/rest/clients' // or ['myApiUrl', 'rest', 'clients']
-    })
+`HTTPManagerStateService` supports request tracking options for `fetchRecords` and `fetchStream` when database caching is configured (`DatabaseStorage` provided in the service constructor).
 
-  onFetchData() {
+```typescript
+service.fetchRecords(RequestOptions.adapt({
+  path: ['ai/pagination?page=0&size=25'],
+  ignoreQueryParams: ['page', 'size'],
+  queryParamsExpiresIn: '10s'
+}));
+```
 
-      this.httpManagerService.getRequest<any>(apiOptions)
-      .pipe(
-        catchError(error => {
-          return throwError(() => this.errorHandling(error, 'GET'))
-        })
-      ).subscribe(data => console.log(data)))
+Supported request options:
 
-    }
-  ```
+- `ignoreQueryParams`: Query keys to track for request-change behavior.
+- `queryParamsExpiresIn`: Expiry window for tracked values (examples: `10s`, `5mn`, `1h`).
 
-### Example
-In this example, we define the endpoint URL as myApiUrl. This will return the data from the observable for your use case.
+Behavior notes:
 
-The endpoint can be:
+- Database enabled (`DatabaseStorage` configured): tracker is active, repeated identical query values are blocked until expiry, then can call API again.
+- Database disabled: tracker is bypassed; requests call the API directly each time.
+- `forceRefresh: true` always forces an API call.
 
-A direct URL (e.g., https://apple.com/clients).
-A proxy-config file (recommended to avoid CORS issues).
-A string, an array of strings, or numbers—similar to Angular’s Router.navigate() API.
-The HTTP Service Manager automatically sanitizes the endpoint by removing redundant `/` characters and validating the URL.
+## ⚙️ Configuration
 
-You can also add query parameters by passing an object:
+### Module Initialization (`forRoot`)
 
-  ```ts
-    { sortBy: 'asc', filter: ['samples', 'testing'] }
-  ```
+Configure the library globally using the `forRoot` method:
 
-This translates to: `https://apple.com/clients?sortBy=asc&filter=samples,testing`
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
 
-There are a number of other options available in the `ApiRequest` adapter
+@NgModule({
+  imports: [
+    HttpRequestManagerModule.forRoot({
+      httpRequestOptions: {
+        server: 'https://api.example.com',
+        headers: { 'Authorization': 'Bearer token' },
+        retry: { times: 3, delay: 2 },
+        displayError: true
+      },
+      LocalStorageOptions: {
+        storageName: 'my-app-data',
+        storageSettingsName: 'my-app-settings',
+        options: {
+          encrypted: true,
+          expiresIn: '7d'
+        }
+      }
+    })
+  ]
+})
+export class AppModule { }
+```
 
+### Configuration Options
+
+#### HTTP Options (`ConfigHTTPOptions`)
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `server` | `string` | Base URL for API requests | `''` |
+| `path` | `any[]` | Default path segments | `[]` |
+| `headers` | `any` | Default headers | `{}` |
+| `polling` | `number` | Default polling interval (seconds) | `0` |
+| `retry` | `RetryOptions` | Default retry configuration | `{ times: 0, delay: 3 }` |
+| `stream` | `boolean` | Enable streaming by default | `false` |
+| `displayError` | `boolean` | Show toast errors by default | `false` |
+| `displaySuccess` | `boolean` | Show toast on success by default | `false` |
+| `successMessage` | `string` | Custom success toast message (optional) | `undefined` |
+| `errorMessage` | `string` | Custom error toast message (optional, overrides default) | `undefined` |
+
+#### Local Storage Options (`LocalStorageOptions`)
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `storageName` | `string` | Key for storing data | `'storage'` |
+| `storageSettingsName` | `string` | Key for settings metadata | `'global-storage'` |
+| `options` | `SettingOptions` | Default storage settings | `{ storage: StorageType.GLOBAL, expires: 0, expiresIn: '', encrypted: false }` |
+
+#### Retry Options (`RetryOptions`)
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `times` | `number` | Number of retry attempts | `0` |
+| `delay` | `number` | Delay between retries (seconds) | `3` |
+
+#### WebSocket Options (`WSOptions`)
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `id` | `string` | Channel identifier (used to construct channel names) | `''` |
+| `wsServer` | `string` | WebSocket server URL | `''` |
+| `jwtToken` | `string` | JWT token for authentication | `''` |
+| `permissions` | `string[]` | Permission levels for the connection | `[]` |
+| `channels` | `string[]` | Additional channels to subscribe to | `[]` |
+| `user` | `any` | User information for presence tracking | `undefined` |
+| `retry` | `RetryOptions` | Retry configuration for reconnection | `{ times: 0, delay: 3 }` |
+
+### Injection Tokens
+
+| Token | Type | Purpose | Required |
+|-------|------|---------|----------|
+| `CONFIG_SETTINGS_TOKEN` | `ConfigOptions` | Global library configuration (provided by `forRoot()`) | Yes (via `forRoot()`) |
+| `APP_ID` | `string` | Unique application ID for encryption key generation | Yes (if using encryption) |
+
+### Providing APP_ID
+
+If using encryption features (localStorage encryption, AES/RSA encryption), you must provide a unique `APP_ID`:
+
+```typescript
+import { APP_ID } from '@angular/core';
+
+@NgModule({
+  providers: [
+    { provide: APP_ID, useValue: 'your-unique-app-guid-here' }
+  ]
+})
+export class AppModule { }
+```
 
-### Extending a Component or Service with the Service (Multiple Instances - preferred method)
+> **Important:** The `APP_ID` is used as the encryption key for `SymmetricalEncryptionService`. Use a strong, unique value per application.
+
+## 📚 Services Overview
+
+### Angular 14-18: Observable + NgRx Services
+
+| Service | Description | Use Case |
+|---------|-------------|----------|
+| [`HTTPManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md) | Observable-based HTTP client with retry, polling, streaming | Simple API calls with loading states |
+| [`HTTPManagerStateService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_STATE_MANAGER_README.md) | ComponentStore + HTTP + WebSocket + IndexedDB | CRUD with auto state sync and real-time updates |
+| [`StoreStateManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_MANAGER_README.md) | Persistent ComponentStore with localStorage sync | Application state persistence |
+| [`WebSocketManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_MANAGER_README.md) | Singleton WebSocket connection manager | Real-time messaging and notifications |
+| [`WebSocketMessageService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md) | Unified type-safe message sending service | Simplified WebSocket messaging with auto prefixes |
+| [`MessageTrackerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) | Guaranteed message delivery with gap detection | Message tracking and reconnection sync |
+| [`LocalStorageManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_README.md) | Secure local/session storage with encryption | User preferences and session data |
+| [`DatabaseManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/DATABASE_README.md) | IndexedDB wrapper via Dexie.js | Offline-first data access |
+
+### Angular 19+: Signal-Based Services
+
+| Service | Description | Use Case |
+|---------|-------------|----------|
+| [`HTTPManagerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_SIGNALS_MANAGER_README.md) | Signal-based HTTP client for modern reactive UI | Modern Angular with Signals |
+| [`LocalStorageSignalsManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_SIGNALS_README.md) | Signal-based local/session storage | Reactive persisted UI state |
+| [`StoreStateManagerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_SIGNALS_README.md) | Signal-based persistent state service | App state persistence with computed derivations |
+| [`WebSocketSignalsManagerService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_SIGNALS_README.md) | Signal-based WebSocket manager | Signal-driven real-time dashboards and messaging |
+| [`MessageTrackerSignalsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_SIGNALS_README.md) | Signal-based channel/message tracking | Presence, counters, last-message views |
+
+### Shared Utilities
+
+| Service | Description | Use Case |
+|---------|-------------|----------|
+| [`UtilsService`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_README.md) | Utilities: encryption, headers, merging, path/query | Helper functions |
+| [`Utility Services`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_SERVICES_README.md) | Headers, path/query, merging, base request classes | Internal and helper services |
+
+### 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, pagination |
+| Real-time chat | `HTTPManagerStateService` + WebSocket | PUB- messaging channels |
+| Persistent notifications | `HTTPManagerStateService` + WebSocket | MES- channels with DB storage |
+| State synchronization | `HTTPManagerStateService` + WebSocket | SYS- private channels |
+| **Unified WebSocket messaging** | **`WebSocketMessageService`** | **Type-safe, auto prefixes, validation** |
+| User preferences | `LocalStorageManagerService` | Encryption, expiration |
+| Offline-first | `DatabaseManagerService` | IndexedDB caching, querying |
+| Large local datasets | `DatabaseManagerService` | Bulk operations, indexing |
+| Secure data storage | `LocalStorageManagerService` | AES encryption |
+| File transfers | `HTTPManagerService` | Download progress tracking |
+| Live data streams | `HTTPManagerService` | NDJSON, SSE streaming |
+
+## 📖 Documentation Paths
+
+All detailed service guides live in `src/docs/`. Use this README as the entry point, then choose the track that matches the Angular version in your app.
+
+### Angular 14-18: Observable + NgRx Track
+
+| Category | Documentation |
+|----------|---------------|
+| HTTP | [HTTP Manager](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md) |
+| State | [HTTP State Manager](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_STATE_MANAGER_README.md) and [Store State Manager](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_MANAGER_README.md) |
+| Real-Time | [WebSocket Manager](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_MANAGER_README.md), [WebSocket Message Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md), and [Message Tracker](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) |
+| Persistence | [Local Storage](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_README.md) and [Database](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/DATABASE_README.md) |
+| Utilities | [Utils](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_README.md), [Encryption](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ENCRYPTION_README.md), [Logger](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) |
+| Reference | [Models](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md), [Complete API Reference](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/COMPLETE_API_REFERENCE.md) |
+
+### Angular 19+: Signal Track
+
+| Category | Documentation |
+|----------|---------------|
+| Overview | [Signal Services Overview](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SIGNAL_SERVICES_README.md) |
+| HTTP | [HTTP Manager Signals](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_SIGNALS_MANAGER_README.md) |
+| State | [Store State Signals](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_SIGNALS_README.md) |
+| Real-Time | [WebSocket Signals](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_SIGNALS_README.md) and [Message Tracker Signals](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_SIGNALS_README.md) |
+| Persistence | [Local Storage Signals](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_SIGNALS_README.md) |
+
+## 🏗️ Architecture
+
+For detailed system architecture, data flows, and design patterns, see:
+
+📋 **[Architecture Documentation](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ARCHITECTURE.md)**
+
+### System Overview
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                         Angular Application                     │
+├─────────────────────────────────────────────────────────────────┤
+│  ┌────────────────┐  ┌────────────────┐  ┌──────────────────┐   │
+│  │   Components   │  │   Components   │  │    Components    │   │
+│  │   (Signals)    │  │  (Observables) │  │  (State Store)   │   │
+│  └───────┬────────┘  └───────┬────────┘  └────────┬─────────┘   │
+│          │                   │                     │            │
+│          ▼                   ▼                     ▼            │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐   │
+│  │HTTPManager   │    │HTTPManager   │    │HTTPManager       │   │
+│  │SignalsService│    │Service       │    │StateService      │   │
+│  └──────┬───────┘    └──────┬───────┘    └────────┬─────────┘   │
+│         │                   │                      │            │
+│         └───────────────────┴──────────────────────┘            │
+│                             │                                   │
+│                             ▼                                   │
+│                    ┌─────────────────┐                          │
+│                    │  HttpClient     │                          │
+│                    │  (Angular)      │                          │
+│                    └────────┬────────┘                          │
+│                             │                                   │
+├─────────────────────────────┼───────────────────────────────────┤
+│                             │                                   │
+│  ┌──────────────────────────┼──────────────────────┐            │
+│  │        Storage Layer                            │            │
+│  ├──────────────────────────┼──────────────────────┤            │
+│  │  ┌────────────────┐      │      ┌─────────────┐ │            │
+│  │  │LocalStorage    │      │      │IndexedDB    │ │            │
+│  │  │Manager Service │      │      │(Dexie.js)   │ │            │
+│  │  └────────────────┘      │      └─────────────┘ │            │
+│  └──────────────────────────┼──────────────────────┘            │
+│                             │                                   │
+│  ┌──────────────────────────┼──────────────────────┐            │
+│  │        WebSocket Layer                          │            │
+│  ├──────────────────────────┼──────────────────────┤            │
+│  │  ┌─────────────────────────────────────┐        │            │
+│  │  │   WebsocketService                  │        │            │
+│  │  └─────────────────────────────────────┘        │            │
+│  └─────────────────────────────────────────────────┘            │
+└─────────────────────────────────────────────────────────────────┘
+```
 
-This approach creates a new instance of the service for each component or service that extends it, ensuring each instance maintains its own independent state.
+## 🔧 Interceptors
 
-### Observables
-- Similar to the first approach, instead of one instance of the state you are creating a new state instance
-- CRUD operations return Observables, similar to HttpClient.
-- This allows for custom error handling and executing additional actions after the request completes.
-- Since HTTP requests are asynchronous, you must subscribe to the Observable to receive data:
+The library provides several HTTP interceptors that are automatically configured:
 
-  ```ts
-    myService.getData().subscribe(response => {
-      console.log(response);
-    });
-  ```
+📋 **[Interceptors Documentation](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/INTERCEPTOR_README.md)**
 
-- Alternatively, you can use the async pipe for automatic subscription and cleanup:
+### Available Interceptors
 
-  ```ts
-    {{ myData$ | async }}
-  ```
+| Interceptor | Purpose | Automatically Applied |
+|-------------|---------|----------------------|
+| **RequestErrorInterceptor** | Handles 400/500 errors with toast notifications | ✅ Yes |
+| **RequestHeadersInterceptor** | Adds Content-Type, Accept-Language, Current-Date | ✅ Yes |
+| **CredentialsInterceptor** | Adds `withCredentials: true` for CORS | ✅ Yes |
+| **ProxyDebuggerInterceptor** | Debug logging for development | ⚙️ Configurable |
 
-### Example
-First we need to extend the Component or Service (recommended approach) with the `HTTPManagerService`
+### Manual Configuration
 
-Component Example:
-  ```ts
-  export class RequestManagerDemoComponent extends HTTPManagerService<any> implements OnInit {
+```typescript
+// app.module.ts
+providers: [
+  { provide: HTTP_INTERCEPTORS, useClass: WithCredentialsInterceptor, multi: true },
+  { provide: HTTP_INTERCEPTORS, useClass: RequestHeadersInterceptor, multi: true },
+  { provide: HTTP_INTERCEPTORS, useClass: RequestErrorInterceptor, multi: true }
+]
+```
 
-    constructor() { 
-      super()
-    }
-  }
-  ```
+### Customization
 
-Service Example:
-  ```ts
-  @Injectable({
-    providedIn: 'root'
-  })
-  export class myAPIService extends HTTPManagerService<any> {
+Error handling can be customized with `ErrorSettings`:
 
-    constructor() { 
-      super()
-    }
+```typescript
+import { ErrorSettings } from 'http-request-manager';
 
+const customSettings: ErrorSettings = {
+  displayError: true,
+  displayWarning: true,
+  customHandler: (error) => {
+    // Custom error handling logic
   }
-  ```
+};
+```
 
-In this example, we define the endpoint URL as myApiUrl. This will return the data from the observable for your use case.
+## 📚 Detailed Documentation
 
-The endpoint can be:
+For in-depth documentation on each service and component, refer to the following detailed guides:
 
-A direct URL (e.g., https://apple.com/clients).
-A proxy-config file (recommended to avoid CORS issues).
-A string, an array of strings, or numbers—similar to Angular’s Router.navigate() API.
-The HTTP Service Manager automatically sanitizes the endpoint by removing redundant `/` characters and validating the URL.
+### Detailed Docs for Angular 14-18
 
-You can also add query parameters by passing an object:
-```ts
-  { sortBy: 'asc', filter: ['samples', 'testing'] }
+| Documentation | Description |
+|---------------|-------------|
+| 📖 [HTTP Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_MANAGER_README.md) | Observable-based HTTP client with retry, polling, streaming, and error handling |
+| 📖 [HTTP Manager State Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_STATE_MANAGER_README.md) | ComponentStore integration with automatic CRUD state updates and WebSocket sync |
+| 📖 [Store State Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_MANAGER_README.md) | Persistent ComponentStore synchronized with local/session storage |
+| 📖 [WebSocket Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WS_MANAGER_README.md) | WebSocket connection management with channel-based messaging and notifications |
+| 📖 [WebSocket Message Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_MESSAGE_SERVICE.md) | Type-safe WebSocket message sending with channel prefix helpers |
+| 📖 [Message Tracker Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_README.md) | Guaranteed message delivery with gap detection and reconnection sync |
+| 📖 [Local Storage Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_README.md) | Secure local/session storage with encryption and expiration |
+| 📖 [Database Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/DATABASE_README.md) | IndexedDB wrapper via Dexie.js with Observable API for offline-first apps |
+| 🚀 [Batch Request Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/BATCH_REQUEST_README.md) | Execute multiple HTTP requests with sequential/parallel modes and configurable error handling |
+| 📤 [Upload Request Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UPLOAD_REQUEST_README.md) | Multi-file upload with progress tracking, validation, and form-data configuration |
+| 🔐 [Encryption Utils](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ENCRYPTION_README.md) | AES symmetric and RSA asymmetric encryption utilities |
+| 📝 [Logger Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOGGER_README.md) | Context-aware logging with automatic dev/prod mode detection |
+| 📚 [Models Reference](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md) | Complete reference for all data models and configuration interfaces |
+
+### Detailed Docs for Angular 19+
+
+| Documentation | Description |
+|---------------|-------------|
+| 📖 [Signal Services Overview](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/SIGNAL_SERVICES_README.md) | Overview of the signal-based service set and migration guidance |
+| 📖 [HTTP Manager Signals Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/HTTP_SIGNALS_MANAGER_README.md) | Signal-based HTTP client for modern reactive UI with Angular Signals |
+| 📖 [Local Storage Signals Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/LOCAL_STORAGE_SIGNALS_README.md) | Signal-based persisted storage patterns |
+| 📖 [Store State Signals Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/STORE_STATE_SIGNALS_README.md) | Signal-based state persistence and computed state |
+| 📖 [WebSocket Signals Manager Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/WEBSOCKET_SIGNALS_README.md) | Signal-driven WebSocket connection and subscription management |
+| 📖 [Message Tracker Signals Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MESSAGE_TRACKER_SIGNALS_README.md) | Signal-based message counting, presence, and channel metadata |
+| 🚀 [Batch Request Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/BATCH_REQUEST_README.md) | Execute multiple HTTP requests with sequential/parallel modes and configurable error handling |
+
+### Shared Services
+
+| Documentation | Description |
+|---------------|-------------|
+| 📖 [Utils Service](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/UTILS_README.md) | Utility functions for JSON handling, encryption, headers, and validation |
+
+### Core Components
+
+| Documentation | Description |
+|---------------|-------------|
+| 🏗️ [Architecture](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/ARCHITECTURE.md) | System architecture, data flows, and design patterns |
+| 🔧 [Interceptors](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/INTERCEPTOR_README.md) | HTTP interceptors for error handling, headers, authentication, and debugging |
+
+### Additional Resources
+
+- **Request Manager Services** - Detailed API documentation for the request manager services ([`src/lib/services/request-manager-services/README.md`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/lib/services/request-manager-services/README.md))
+- **Encryption Utils** - Encryption utility documentation ([`src/lib/services/utils/encryption/README.md`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/lib/services/utils/encryption/README.md))
+
+## 🎮 Demo Examples
+
+Comprehensive demo components showcase all library features in action:
+
+### Available Demos
+
+Located in [`src/lib/http-request-services-demo/`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/lib/http-request-services-demo/):
+
+| Demo Component | Features Demonstrated |
+|----------------|----------------------|
+| **HttpRequestServicesDemoComponent** | Main demo hub with service selection |
+| **RequestManagerDemoComponent** | HTTP CRUD, file downloads, streaming, polling, retry |
+| **RequestManagerStateDemoComponent** | State management, pagination, WebSocket sync, IndexedDB caching |
+| **RequestManagerWsDemoComponent** | Real-time chat, AI messaging, notifications, presence tracking |
+| **LocalStorageDemoComponent** | Encrypted storage, expiration, reactive signals |
+| **LocalStorageSignalsDemoComponent** | Signal-based localStorage API |
+| **DatabaseDataDemoComponent** | IndexedDB CRUD, querying, bulk operations |
+| **RequestSignalsManagerDemoComponent** | Signal-based HTTP with file downloads |
+| **StoreStateManagerDemoComponent** | Persistent state with localStorage sync |
+
+### Demo Features
+
+**HTTP Service Demos:**
+
+- ✅ Basic CRUD operations
+- ✅ File download with progress tracking
+- ✅ Streaming responses (NDJSON, SSE)
+- ✅ Polling with countdown timers
+- ✅ Retry logic with custom delays
+- ✅ Error handling with toast notifications
+
+**State Management Demos:**
+
+- ✅ ComponentStore integration
+- ✅ Automatic state updates
+- ✅ Pagination controls
+- ✅ WebSocket real-time sync
+- ✅ IndexedDB caching
+- ✅ Database clear/refresh
+
+**WebSocket Demos:**
+
+- ✅ Channel-based messaging (PUB- channels)
+- ✅ Private state sync (SYS- channels)
+- ✅ Persistent notifications (MES- channels)
+- ✅ User presence tracking
+- ✅ Message history & replay
+- ✅ AI chat integration
+- ✅ Multi-room support
+
+**Storage Demos:**
+
+- ✅ Encrypted localStorage
+- ✅ SessionStorage usage
+- ✅ Expiration management
+- ✅ Signal-based API
+- ✅ Reactive updates
+
+### Usage
+
+```html
+<app-http-request-services-demo
+  [server]="'http://localhost:8080'"
+  [wsServer]="'ws://localhost:8080'"
+  [jwtToken]="'your-jwt-token'"
+  [adapter]="myAdapterFunction"
+  [mapper]="myMapperFunction">
+</app-http-request-services-demo>
 ```
-This translates to: `https://apple.com/clients?sortBy=asc&filter=samples,testing`
-
-Lets define these query params as a variable called `PARAMS` and use them in the following request.
 
-There are a number of other options available in the `ApiRequest` adapter
+### Sample Models
 
-No we can define a method:
-In this example take note that the clientID has been passed to the method and the param after the apiOptions allows for further customization for the api request being made. In this case we extended the the base path defined in the `ApiRequest` options. We also added the `PARAMS` for query parameters.
+Demo includes production-ready sample models:
 
-Define your API request options using the 'ApiRequest' adapter
+- `User` - User data structures
+- `ClientInfo` - Client details
+- `SessionData` - Session management
+- `AIMessage` - AI chat messages
+- `Notification` - Notification structures
 
-  ```ts
-    const apiOptions = ApiRequest.adapt({
-      server: ['myApiUrl', 'rest', 'clients']
-    })
-
-    // Dynamically change these params
-    const PARAMS = {
-      sortBy: 'asc',
-      filter: ['samples', 'testing']
-    }
+## 📖 Migration Guide
 
-    onFetchData(clientId) {
+### From HttpClient to HTTPManagerService
 
-      this.httpManagerService.getRequest<any>(apiOptions, [clientId, this.PARAMS])
-      .pipe(
-        catchError(error => {
-          return throwError(() => this.errorHandling(error, 'GET'))
-        })
-      ).subscribe(data => console.log(data)))
+**Before:**
 
-    }
-  ```
+```typescript
+http.get('api/users').subscribe(users => {
+  this.users = users;
+  this.loading = false;
+});
+```
 
+**After:**
 
-### State Observable
-- When executing CRUD operations, their results are automatically pushed into the data$ observable within the service.
-- This means you can bind the data$ observable to a component to automatically update UI elements.
-- Using this approach enables state management across components and allows data refresh actions without needing additional logic.
+```typescript
+httpManager.getRequest(
+  ApiRequest.adapt({ path: ['users'] })
+).subscribe();
 
-### Example
-First we need to extend the Component or Service (recommended approach) with the `HTTPManagerService`
+data$ = this.httpManager.data$;
+isLoading$ = this.httpManager.isPending$;
+```
 
-Component Example:
-The structure would be: Component extends `HTTPManagerService`
+### From Manual State to HTTPManagerStateService
 
-  ```ts
-  export class RequestManagerDemoComponent extends HTTPManagerService<any> implements OnInit {
+**Before:**
 
-    constructor() { 
-      super()
-    }
-  }
-  ```
+```typescript
+users: User[] = [];
+loading = false;
 
-Service Example:
-The structure would be: Component injects a service call `clientsService` and `clientsService` extends `HTTPManagerService`
+loadUsers() {
+  this.loading = true;
+  this.http.get('api/users').subscribe(users => {
+    this.users = users;
+    this.loading = false;
+  });
+}
 
-  ```ts
-  @Injectable({
-    providedIn: 'root'
-  })
-  export class myAPIService extends HTTPManagerService<any> {
+addUser(user: User) {
+  this.http.post('api/users', user).subscribe(newUser => {
+    this.users = [...this.users, newUser];
+  });
+}
+```
 
-    constructor() { 
-      super()
-    }
+**After:**
 
+```typescript
+@Injectable()
+export class UsersStore extends HTTPManagerStateService<User> {
+  constructor() {
+    super(ApiRequest.adapt({ path: ['users'] }), DataType.ARRAY);
   }
-  ```
-
-In this example, we define the endpoint URL as myApiUrl.
-
-Lets define these query params as a variable called `PARAMS` and use them in the following request.
-
-No we can define a method:
-In this example the clientID has been passed to the method. 
-We also added the `PARAMS` for query parameters.
-
-Define your API request options using the 'ApiRequest' adapter
-
-  ```ts
-    const apiOptions = ApiRequest.adapt({
-      server: ['myApiUrl', 'rest', 'clients']
-    })
-
-    // Dynamically change these params
-    const PARAMS = {
-      sortBy: 'asc',
-      filter: ['samples', 'testing']
-    }
-
-    onFetchData(clientId: number) {
-      this.httpManagerService.getRequest<any>(apiOptions, [clientId, this.PARAMS]).subscribe()
-    }
-  ```
-
-  In the above case we are not using the data returning from the Observable but rather executing the api call, like a refresh if called again
-
-  To access the data from the observable, you need to bind the observable if your using a component that injects the service that extends the `HTTPManagerService`
-
-  In the component where the service was injected, we define
+  
+  loadUsers() { this.fetchRecords(); }
+  addUser(user: User) { this.createRecord(user); }
+}
+
+// Component
+data$ = this.usersStore.data$;
+isLoading$ = this.usersStore.isPending$;
+```
 
-  ```ts
-    data$ = this.clientsService.data$
-    isPending$ = this.clientsService.isPending$
-    error$ = this.clientsService.error$
-  ```
-  By doing this gives your component the state of the data and other feedback states for the request that now you can use in your template.
+## 📋 API Reference
 
-```ts
-  {{ data$ | async }}
-  {{ isPending$ | async }}
-  {{ error$ | async }}
-```
+### Core Models
 
+All models follow the `<Name>Interface` + `<Name>Model` pattern with static `adapt()` methods.
 
-### ApiRequest Options
-The following are the available options when configuring an ApiRequest object:
-
-```ts
-apiRequest = ApiRequest.adapt({
-  server: string,
-  path: any[],
-  headers: any,
-  adapter?: any,
-  mapper?: any,
-  polling?: number, // in seconds (undefined | 0 = none)
-  retry: RetryOptions,
-  stream?: boolean
-  displayError: boolean
-});
-```
+| Model | Description | Documentation |
+|-------|-------------|---------------|
+| **ApiRequest** | HTTP request configuration | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#apirequest) |
+| **RetryOptions** | Retry behavior settings | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#retryoptions) |
+| **DataType** | Data structure type (ARRAY, OBJECT) | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#datatype) |
+| **DatabaseStorage** | IndexedDB configuration | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#databasestorage) |
+| **SettingOptions** | Storage settings | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#settingoptions) |
+| **WSOptions** | WebSocket configuration | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#wsoptions) |
+| **ConfigOptions** | Global library configuration | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#configoptions) |
+| **StateStorageOptions** | Persistent state configuration | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#statestorageoptions) |
+| **TableSchemaDef** | Database table schema | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#tableschemadef) |
+| **ChannelMessage** | WebSocket message structure | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#channelmessage) |
+| **WSUser** | WebSocket user info | [`Models Guide`](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/MODELS_README.md#wsuser) |
 
-| **Property**   | **Description**                                                                   | **Type**                   | **Required** |
-|--------------|--------------------------------------------------------------------------------|---------------------------|------------|
-| `server`     | The base URL or service endpoint for the API request.                         | `string`                   | ✅         |
-| `path`       | Additional paths to append to the base URL for constructing the full API endpoint. | `any[]`                    | ✅         |
-| `headers`    | Custom headers to include in the request, provided as an object.             | `any`                      | ✅         |
-| `adapter`    | A model adapter used to transform incoming data (e.g., `DistrictData.adapt`). | `any`                      | ❌         |
-| `mapper`     | A model adapter used to map outgoing data before sending it to the server (e.g., `DistrictData.mapper`). | `any` | ❌         |
-| `polling`    | Enables periodic polling, where the request will be made every specified number of seconds. | `number` (seconds)         | ❌         |
-| `retry`      | Retry logic using `RetryOptions`, which includes: <br> - `times`: Number of retry attempts. <br> - `delay`: Delay in milliseconds between retries. | `RetryOptions`             | ✅         |
-| `stream`     | A flag to indicate whether the request expects a stream of data from the server. | `boolean`                  | ❌         |
-| `displayError` | A flag to indicate whether to present the error from the request in a snackbar notification. | `boolean`                  | ✅         |
+### Enums
 
+| Enum | Values | Description |
+|------|--------|-------------|
+| **DataType** | `ARRAY`, `OBJECT` | Response data structure |
+| **StreamType** | `NDJSON`, `SSE` | Streaming response types |
+| **StorageType** | `GLOBAL`, `SESSION` | Storage scope |
+| **CommunicationType** | `subscribe`, `unsubscribe`, `message`, `notification`, etc. | WebSocket message types |
+| **ChannelType** | `SYS`, `PUB`, `MES` | Channel prefixes |
+| **ToastColors** | `SUCCESS`, `WARN`, `ERROR`, `INFO` | Toast notification colors |
 
-### Additional Observables for Request Status
-- countdown$: If polling is active, this property gives feedback on when the next request will take place. It starts from the specified time in seconds and counts down to 0, triggering the next request and restarting the countdown.
-- error$: This returns any HTTP error that occurs during the request.
-- isPending$: This boolean value indicates whether the request is pending (true) or has been completed (false).
-- data$: You can access the data fetched in the request using the data$ observable. This provides the response from the server, which can be used for further processing or displaying in the UI.
+### Configuration Tokens
 
-## Importing Module forRoot() Configuration
+| Token | Type | Purpose |
+|-------|------|---------|
+| **CONFIG_SETTINGS_TOKEN** | `ConfigOptions` | Global library configuration |
+| **APP_ID** | `string` | Application ID for encryption |
 
+### Complete API Documentation
 
-# Available Interceptors
+For comprehensive API reference with all methods, parameters, and examples:
+📋 **[Complete API Reference](https://github.com/micheleboni/npm-angular/tree/main/projects/http-request-manager/src/docs/COMPLETE_API_REFERENCE.md)**
 
-There are 3 interceptors that you can import into your project for api requests. 
+## 🧩 Angular 22 Support Matrix
 
-You may add these interceptors in your `AppModule` file as providers and import them into as providers.
+This library is published with Angular 22 as the supported baseline. Older Angular tracks remain documented for reference, but the peer dependency range and toolchain target Angular 22.
 
-```ts
-providers: [
-  { provide: HTTP_INTERCEPTORS, useClass: WithCredentialsInterceptor, multi: true },
-  { provide: HTTP_INTERCEPTORS, useClass: RequestHeadersInterceptor, multi: true },
-  { provide: HTTP_INTERCEPTORS, useClass: RequestErrorInterceptor, multi: true }
-],
-```
+| Angular Version | Track | Recommended Service |
+|-----------------|-------|---------------------|
+| 14-18 | Observable + NgRx | `HTTPManagerService`, `HTTPManagerStateService`, `WebSocketManagerService` |
+| 19-21 | Signals | `HTTPManagerSignalsService`, `StoreStateManagerSignalsService`, `WebSocketSignalsManagerService` |
+| **22 (supported)** | **Signals (default) + Observable** | **All of the above — module-based bootstrap** |
 
-Or you can use all intercepts above by importing the `HttpRequestManagerModule` in your `AppModule`
+### Required Toolchain
 
-- **RequestErrorInterceptor**
+| Tool | Version |
+|------|---------|
+| Angular | `^22.0.1` |
+| Angular CLI / `@angular-devkit/build-angular` | `^22.0.1` |
+| Angular CDK | `^22.0.1` |
+| Angular Material | `^22.0.1` |
+| `@ngrx/component-store` | `^21.1.1` |
+| `@ngx-translate/core` | `^17.0.0` |
+| TypeScript | `~6.0.0` |
+| Node.js | `>=20.19.0` (Angular 22 CLI requires `>=22.22.3` / `>=24.15.0` / `>=26.0.0`) |
+| `ng-packagr` | `^22.0.0` |
+| RxJS | `~7.8.0` |
+| zone.js | `~0.16.2` |
 
-This interceptor handles errors of type 400 and 500. This interceptor is applicable when you need to display UI for the user to indicate a server or request error has occurred. The Status and Error Text is displayed in a `toast-message` modal.
+> The library's `package.json` declares an `engines.node` of `>=20.19.0` to match the Angular 22 toolchain requirements.
 
-- **WithCredentialsInterceptor**
+## 🤝 Contributing
 
-  Adds to your request header 
+This library is designed to be enterprise-ready and production-safe. All features include comprehensive error handling, TypeScript support, and extensive configuration options.
 
-  ```json 
-  { credentials: true }
-  ```
+## 📄 License
 
-- **RequestHeadersInterceptor**
+This project is part of the Angular application library suite.
 
-  Adds to your request - current local `language` (i18n) selection and `current date` to every request
+---
 
-  ```json
-  {
-    'Content-Type': 'application/json',
-    'Accept-Language': this.language || 'en-CA',
-    'Current-Date': this.currentDate
-  }
-  ```
+**Need help?** Check out the detailed documentation for each service, explore the demo examples, or review the architecture documentation for implementation guidance.