http-request-manager 18.15.33 → 18.15.34

package/src/docs/SIGNAL_SERVICES_README.md

@@ -0,0 +1,238 @@
+<!-- markdownlint-disable MD022 MD031 MD032 MD060 -->
+
+# Signal-Based Services Documentation Index
+
+This folder contains documentation for **signal-based services** designed for Angular 19+ applications.
+
+## 📚 Signal Services Documentation
+
+### Core Signal Services
+
+- **[HTTP_MANAGER_SIGNALS_README.md](./HTTP_SINGNALS_MANAGER_README.md)** - Signal-based HTTP client with polling, retry, streaming
+- **[LOCAL_STORAGE_SIGNALS_README.md](./LOCAL_STORAGE_SIGNALS_README.md)** - Signal-based local/session storage with encryption
+- **[STORE_STATE_SIGNALS_README.md](./STORE_STATE_SIGNALS_README.md)** - Signal-based generic state management with persistence
+- **[WEBSOCKET_SIGNALS_README.md](./WEBSOCKET_SIGNALS_README.md)** - Signal-based WebSocket connection manager
+- **[MESSAGE_TRACKER_SIGNALS_README.md](./MESSAGE_TRACKER_SIGNALS_README.md)** - Signal-based message tracking and presence
+
+### Service Comparison
+
+| Service | Non-Signal Version | Signal Version | Angular Version |
+|---------|-------------------|----------------|-----------------|
+| **HTTP Manager** | `HTTPManagerService` | `HTTPManagerSignalsService` | 19+ |
+| **Local Storage** | `LocalStorageManagerService` | `LocalStorageSignalsManagerService` | 19+ |
+| **Store State** | `StoreStateManagerService` | `StoreStateManagerSignalsService` | 19+ |
+| **WebSocket** | `WebSocketManagerService` | `WebSocketSignalsManagerService` | 19+ |
+| **Message Tracker** | `MessageTrackerService` | `MessageTrackerSignalsService` | 19+ |
+
+## 🎯 When to Use Signal Services
+
+**Use Signal Services if:**
+- ✅ Your app uses Angular 19 or later
+- ✅ You want fine-grained reactivity
+- ✅ You prefer signals over RxJS for state management
+- ✅ You want better performance with OnPush change detection
+- ✅ You're building new features with modern Angular patterns
+
+**Use Non-Signal Services if:**
+- ✅ Your app uses Angular 14-18
+- ✅ You have existing RxJS-based code
+- ✅ You need NgRx ComponentStore integration
+- ✅ You're maintaining legacy features
+
+## 📖 Quick Start with Signals
+
+### HTTP Manager Signals
+
+```typescript
+import { Component, inject, computed } from '@angular/core';
+import { HTTPManagerSignalsService } from 'http-request-manager';
+
+@Component({
+  template: `
+    <div *ngIf="isLoading()">Loading...</div>
+    <div *ngFor="let user of users()">
+      {{ user.name }}
+    </div>
+  `
+})
+export class UsersComponent {
+  private http = inject(HTTPManagerSignalsService);
+  
+  data = this.http.data;
+  isLoading = this.http.isPending;
+  
+  users = computed(() => this.data() || []);
+  
+  ngOnInit() {
+    this.http.getRequest({ path: ['users'] }).subscribe();
+  }
+}
+```
+
+### Local Storage Signals
+
+```typescript
+import { Component, computed, inject } from '@angular/core';
+import { LocalStorageSignalsManagerService } from 'http-request-manager';
+
+interface PreferencesState {
+  theme: 'light' | 'dark';
+}
+
+@Component({
+  template: `
+    <div>
+      <p>Theme: {{ theme() }}</p>
+      <button (click)="toggleTheme()">Toggle</button>
+    </div>
+  `
+})
+export class ThemeComponent {
+  private storage = inject(LocalStorageSignalsManagerService);
+
+  private readonly storeName = 'preferences';
+  private readonly defaultState: PreferencesState = { theme: 'light' };
+
+  preferences = this.storage.store(this.storeName);
+  theme = computed(() => this.preferences()?.theme ?? this.defaultState.theme);
+  
+  constructor() {
+    if (!this.storage.storeExists(this.storeName)()) {
+      this.storage.createStore({
+        name: this.storeName,
+        data: this.defaultState,
+        options: { encrypted: false }
+      });
+    }
+  }
+  
+  toggleTheme() {
+    const newTheme = this.theme() === 'light' ? 'dark' : 'light';
+    this.storage.updateStore({
+      name: this.storeName,
+      data: { theme: newTheme }
+    });
+  }
+}
+```
+
+### Store State Signals
+
+```typescript
+import { Component, inject, computed } from '@angular/core';
+import { StoreStateManagerSignalsService } from 'http-request-manager';
+
+interface CounterState {
+  count: number;
+  history: number[];
+}
+
+@Component({
+  template: `
+    <div>
+      <h2>Count: {{ count() }}</h2>
+      <p>History: {{ history().length }} items</p>
+      <button (click)="increment()">+</button>
+    </div>
+  `
+})
+export class CounterComponent {
+  private stateManager = new StoreStateManagerSignalsService<CounterState>();
+  
+  constructor() {
+    this.stateManager.init({
+      store: 'counter',
+      model: () => ({ count: 0, history: [] })
+    });
+  }
+  
+  count = computed(() => this.stateManager.data()?.count || 0);
+  history = computed(() => this.stateManager.data()?.history || []);
+  
+  increment() {
+    const current = this.stateManager.data();
+    this.stateManager.updateState({
+      count: current!.count + 1,
+      history: [...current!.history, current!.count]
+    });
+  }
+}
+```
+
+## 🔗 Related Documentation
+
+### Non-Signal Services (Angular 14-18)
+For older Angular applications, see:
+- [HTTP Manager (Observable)](./HTTP_MANAGER_README.md)
+- [Local Storage (Observable)](./LOCAL_STORAGE_README.md)
+- [Store State (ComponentStore)](./COMPLETE_API_REFERENCE.md#storestatemanagerservice)
+- [WebSocket Manager](./WS_MANAGER_README.md)
+- [Message Tracker](./COMPLETE_API_REFERENCE.md#messagetrackerservice)
+
+### General Documentation
+- [Main Library README](../README.md)
+- [Architecture Guide](./ARCHITECTURE.md)
+- [Complete API Reference](./COMPLETE_API_REFERENCE.md)
+
+## 📝 Documentation Status
+
+| Document | Status | Last Updated |
+|----------|--------|--------------|
+| HTTP Manager Signals | ✅ Complete | 2026-04 |
+| Local Storage Signals | ✅ Complete | 2026-04 |
+| Store State Signals | ✅ Complete | 2026-04 |
+| WebSocket Signals | ✅ Complete | 2026-04 |
+| Message Tracker Signals | ✅ Complete | 2026-04 |
+
+## 🚀 Migration Guide
+
+### From Observable to Signal
+
+**Before (Observable):**
+```typescript
+private service = inject(HTTPManagerService);
+data$ = this.service.data$;
+
+constructor() {
+  this.data$.subscribe(data => {
+    this.users = data;
+  });
+}
+```
+
+**After (Signal):**
+```typescript
+private service = inject(HTTPManagerSignalsService);
+data = this.service.data;
+
+// No subscription needed!
+// Access in template: data()
+```
+
+### From ComponentStore to Signal
+
+**Before (ComponentStore):**
+```typescript
+class MyStore extends ComponentStore<State> {
+  readonly data$ = this.select(state => state.data);
+  readonly updateData = this.updater((state, data) => ({ ...state, data }));
+}
+```
+
+**After (Signal):**
+```typescript
+class MyService {
+  private state = signal<State>({ data: null });
+  readonly data = this.state.asReadonly();
+  
+  updateData(data: any) {
+    this.state.update(state => ({ ...state, data }));
+  }
+}
+```
+
+## 🎓 Learning Resources
+
+- [Angular Signals Guide](https://angular.dev/guide/signals)
+- [Signal-Based Components](https://angular.dev/guide/components/signals)
+- [RxJS Interop](https://angular.dev/api/core/rxjs-interop)