http-request-manager 18.15.32 → 18.15.34

package/src/docs/HTTP_SINGNALS_MANAGER_README.md

@@ -0,0 +1,654 @@
+# HTTP Manager Signals Service
+
+The `HTTPManagerSignalsService` provides the same functionality as `HTTPManagerService` but uses Angular Signals for state management, making it ideal for modern Angular applications that leverage fine-grained reactivity.
+
+## Overview
+
+This service provides:
+
+- **Signal-Based State** - Exposes `data`, `isPending`, `error`, and `countdown` as Angular Signals
+- **Feature Parity** - Supports all features of `HTTPManagerService` including polling, retries, adapters, and streaming
+- **Optimized for Signals** - Designed to work seamlessly with Angular's Signal-based components and templates
+- **Modern Reactivity** - Leverages Angular's latest reactive patterns
+
+## Usage
+
+### Basic Signal-Based HTTP Request
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { HTTPManagerSignalsService, ApiRequest } from 'http-request-manager';
+
+@Component({
+  selector: 'app-users',
+  template: `
+    <div *ngIf="isLoading()">Loading...</div>
+    <div *ngFor="let user of data()">
+      {{ user.name }}
+    </div>
+  `
+})
+export class UsersComponent {
+  httpManager = inject(HTTPManagerSignalsService);
+
+  data = this.httpManager.data;        // Signal<any[]>
+  isLoading = this.httpManager.isPending; // Signal<boolean>
+  error = this.httpManager.error;      // Signal<any>
+  countdown = this.httpManager.countdown; // Signal<number>
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    ).subscribe();
+  }
+}
+```
+
+### Modern Component with Signals
+
+```typescript
+import { Component, inject, signal, computed } from '@angular/core';
+import { HTTPManagerSignalsService, ApiRequest } from 'http-request-manager';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+@Component({
+  selector: 'app-user-list',
+  template: `
+    <div class="user-list">
+      <h2>Users ({{ userCount() }})</h2>
+      
+      <div *ngIf="loadingState() === 'loading'">
+        Loading users...
+      </div>
+      
+      <div *ngIf="loadingState() === 'error'" class="error">
+        {{ errorMessage() }}
+      </div>
+      
+      <div class="user-grid">
+        <div *ngFor="let user of activeUsers()" class="user-card">
+          <h3>{{ user.name }}</h3>
+          <p>{{ user.email }}</p>
+          <span class="user-id">#{{ user.id }}</span>
+        </div>
+      </div>
+      
+      <div *ngIf="isPolling()" class="polling-info">
+        Auto-refresh in {{ countdown() }}s
+        <button (click)="refreshNow()">Refresh Now</button>
+      </div>
+    </div>
+  `
+})
+export class UserListComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+
+  // Raw signals
+  data = this.httpManager.data;
+  isPending = this.httpManager.isPending;
+  error = this.httpManager.error;
+  countdown = this.httpManager.countdown;
+
+  // Computed signals
+  userCount = computed(() => this.data().length);
+  
+  activeUsers = computed(() => 
+    this.data().filter(user => user.active !== false)
+  );
+
+  loadingState = computed(() => {
+    if (this.isPending()) return 'loading';
+    if (this.error()) return 'error';
+    return 'idle';
+  });
+
+  errorMessage = computed(() => {
+    const err = this.error();
+    return err ? err.message || 'Unknown error' : '';
+  });
+
+  isPolling = computed(() => this.countdown() > 0);
+
+  constructor() {
+    // Initialize with polling
+    this.loadUsersWithPolling();
+  }
+
+  loadUsersWithPolling() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({
+        path: ['users'],
+        polling: 30, // Poll every 30 seconds
+        retry: { times: 3, delay: 2 },
+        displayError: true
+      })
+    ).subscribe();
+  }
+
+  refreshNow() {
+    this.loadUsersWithPolling();
+  }
+
+  stopPolling() {
+    this.httpManager.stopPolling();
+  }
+}
+```
+
+## API Reference
+
+### Signal Properties
+
+| Signal | Type | Description | Usage |
+|--------|------|-------------|-------|
+| `data` | `Signal<any>` | Response data from requests | `this.data()` |
+| `isPending` | `Signal<boolean>` | Loading state indicator | `this.isPending()` |
+| `error` | `Signal<any>` | Error state | `this.error()` |
+| `countdown` | `Signal<number>` | Countdown for polling | `this.countdown()` |
+
+### HTTP Methods
+
+All HTTP methods work the same as `HTTPManagerService`:
+
+```typescript
+// GET Request
+this.httpManager.getRequest(
+  ApiRequest.adapt({ path: ['users'] })
+).subscribe();
+
+// POST Request
+this.httpManager.postRequest(
+  ApiRequest.adapt({ path: ['users'] }),
+  { name: 'John Doe', email: 'john@example.com' }
+).subscribe();
+
+// PUT Request
+this.httpManager.putRequest(
+  ApiRequest.adapt({ path: ['users', '123'] }),
+  { name: 'Jane Doe' }
+).subscribe();
+
+// DELETE Request
+this.httpManager.deleteRequest(
+  ApiRequest.adapt({ path: ['users', '123'] })
+).subscribe();
+
+// Download Request
+this.httpManager.downloadRequest(
+  ApiRequest.adapt({
+    path: ['files', 'report.pdf'],
+    saveAs: 'my-report.pdf'
+  })
+).subscribe();
+```
+
+## Advanced Signal Patterns
+
+### Computed Signals for Data Transformation
+
+```typescript
+import { computed, signal, inject } from '@angular/core';
+import { HTTPManagerSignalsService, ApiRequest } from 'http-request-manager';
+
+@Component({
+  template: `
+    <div class="dashboard">
+      <div class="stats">
+        <div class="stat-card">
+          <h3>Total Users</h3>
+          <div class="stat-value">{{ totalUsers() }}</div>
+        </div>
+        <div class="stat-card">
+          <h3>Active Users</h3>
+          <div class="stat-value">{{ activeUsers() }}</div>
+        </div>
+        <div class="stat-card">
+          <h3>Admins</h3>
+          <div class="stat-value">{{ adminUsers() }}</div>
+        </div>
+      </div>
+      
+      <div class="filters">
+        <select (change)="setRoleFilter($any($event.target).value)">
+          <option value="">All Roles</option>
+          <option value="admin">Admin</option>
+          <option value="user">User</option>
+        </select>
+        
+        <select (change)="setStatusFilter($any($event.target).value)">
+          <option value="">All Status</option>
+          <option value="active">Active</option>
+          <option value="inactive">Inactive</option>
+        </select>
+      </div>
+      
+      <div class="user-list">
+        <div *ngFor="let user of filteredUsers()">
+          {{ user.name }} - {{ user.role }} ({{ user.status }})
+        </div>
+      </div>
+    </div>
+  `
+})
+export class UserDashboardComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+
+  // Raw data signal
+  rawData = this.httpManager.data;
+  
+  // Filter state signals
+  roleFilter = signal<string>('');
+  statusFilter = signal<string>('');
+
+  // Computed signals
+  totalUsers = computed(() => this.rawData().length);
+  
+  activeUsers = computed(() => 
+    this.rawData().filter(user => user.status === 'active').length
+  );
+
+  adminUsers = computed(() => 
+    this.rawData().filter(user => user.role === 'admin').length
+  );
+
+  filteredUsers = computed(() => {
+    const data = this.rawData();
+    const roleFilter = this.roleFilter();
+    const statusFilter = this.statusFilter();
+
+    return data.filter(user => {
+      const matchesRole = !roleFilter || user.role === roleFilter;
+      const matchesStatus = !statusFilter || user.status === statusFilter;
+      return matchesRole && matchesStatus;
+    });
+  });
+
+  constructor() {
+    this.loadUsers();
+  }
+
+  loadUsers() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ 
+        path: ['users'],
+        adapter: User.adapt
+      })
+    ).subscribe();
+  }
+
+  setRoleFilter(role: string) {
+    this.roleFilter.set(role);
+  }
+
+  setStatusFilter(status: string) {
+    this.statusFilter.set(status);
+  }
+}
+```
+
+### Effect-Based Side Effects
+
+```typescript
+import { effect, inject } from '@angular/core';
+import { HTTPManagerSignalsService, ApiRequest } from 'http-request-manager';
+
+@Component({
+  template: `
+    <div class="notifications">
+      <div *ngFor="let notification of notifications()">
+        {{ notification.message }}
+      </div>
+    </div>
+    
+    <div class="data-display">
+      <div *ngFor="let item of data()">
+        {{ item.name }}
+      </div>
+    </div>
+  `
+})
+export class NotificationComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+  
+  data = this.httpManager.data;
+  error = this.httpManager.error;
+  isPending = this.httpManager.isPending;
+
+  // External state
+  notifications = signal<Array<{message: string, type: string}>>([]);
+
+  constructor() {
+    // Auto-load data on component init
+    this.loadData();
+    
+    // Set up effects for side effects
+    this.setupEffects();
+  }
+
+  private setupEffects() {
+    // Show loading notifications
+    effect(() => {
+      if (this.isPending()) {
+        this.addNotification('Loading data...', 'info');
+      }
+    });
+
+    // Show error notifications
+    effect(() => {
+      const error = this.error();
+      if (error) {
+        this.addNotification(`Error: ${error.message}`, 'error');
+      }
+    });
+
+    // Auto-retry on certain errors
+    effect(() => {
+      const error = this.error();
+      if (error && error.status === 503) { // Service unavailable
+        setTimeout(() => this.loadData(), 5000); // Retry in 5s
+      }
+    });
+  }
+
+  loadData() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ 
+        path: ['data'],
+        retry: { times: 3, delay: 2 }
+      })
+    ).subscribe();
+  }
+
+  private addNotification(message: string, type: string) {
+    const current = this.notifications();
+    this.notifications.set([
+      ...current,
+      { message, type }
+    ]);
+    
+    // Auto-remove after 5 seconds
+    setTimeout(() => {
+      const updated = this.notifications().slice(1);
+      this.notifications.set(updated);
+    }, 5000);
+  }
+}
+```
+
+## Migration from Observables to Signals
+
+### Before (Observable-based)
+
+```typescript
+@Component({
+  template: `
+    <div *ngIf="isLoading$ | async">Loading...</div>
+    <div *ngFor="let user of users$ | async">
+      {{ user.name }}
+    </div>
+    <div *ngIf="error$ | async as error">
+      Error: {{ error }}
+    </div>
+  `
+})
+export class UserListComponent implements OnInit {
+  private httpManager = inject(HTTPManagerService);
+
+  users$ = this.httpManager.data$;
+  isLoading$ = this.httpManager.isPending$;
+  error$ = this.httpManager.error$;
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    ).subscribe();
+  }
+}
+```
+
+### After (Signal-based)
+
+```typescript
+@Component({
+  template: `
+    <div *ngIf="isLoading()">Loading...</div>
+    <div *ngIf="data() as users">
+      <div *ngFor="let user of users">
+        {{ user.name }}
+      </div>
+    </div>
+    <div *ngIf="error() as error">
+      Error: {{ error }}
+    </div>
+  `
+})
+export class UserListComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+
+  data = this.httpManager.data;
+  isLoading = this.httpManager.isPending;
+  error = this.httpManager.error;
+
+  constructor() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    ).subscribe();
+  }
+}
+```
+
+## Integration with Other Signal-Based Services
+
+### Local Storage Signals
+
+```typescript
+import { signal, computed, inject } from '@angular/core';
+import { LocalStorageSignalsManagerService } from 'http-request-manager';
+
+@Component({
+  template: `
+    <div class="user-preferences">
+      <h3>Welcome, {{ userName() }}!</h3>
+      
+      <div class="preferences">
+        <label>
+          Theme:
+          <select [value]="theme()" (change)="setTheme($any($event.target).value)">
+            <option value="light">Light</option>
+            <option value="dark">Dark</option>
+          </select>
+        </label>
+        
+        <label>
+          Notifications:
+          <input type="checkbox" [checked]="notifications()" 
+                 (change)="setNotifications($any($event.target).checked)">
+        </label>
+      </div>
+      
+      <div class="data-sync">
+        <p>Data last updated: {{ lastUpdated() }}</p>
+        <button (click)="refreshData()">Refresh from Server</button>
+      </div>
+    </div>
+  `
+})
+export class UserPreferencesComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+  private storage = inject(LocalStorageSignalsManagerService);
+
+  // HTTP data signals
+  serverData = this.httpManager.data;
+  
+  // Storage signals
+  theme = this.storage.signal('theme', 'light');
+  notifications = this.storage.signal('notifications', true);
+  lastUpdated = this.storage.signal('lastUpdated', new Date().toISOString());
+
+  // Computed signals
+  userName = computed(() => {
+    const data = this.serverData();
+    return data?.user?.name || 'Guest';
+  });
+
+  hasUnsavedChanges = computed(() => {
+    // Compare local storage with server data
+    return this.theme() !== 'light' || this.notifications() !== true;
+  });
+
+  constructor() {
+    this.loadUserData();
+    this.setupAutoSync();
+  }
+
+  private setupAutoSync() {
+    // Auto-save to server when preferences change
+    setInterval(() => {
+      if (this.hasUnsavedChanges()) {
+        this.saveToServer();
+      }
+    }, 30000); // Every 30 seconds
+  }
+
+  loadUserData() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['user', 'preferences'] })
+    ).subscribe();
+  }
+
+  setTheme(theme: string) {
+    this.theme.set(theme);
+    this.updateLastUpdated();
+  }
+
+  setNotifications(enabled: boolean) {
+    this.notifications.set(enabled);
+    this.updateLastUpdated();
+  }
+
+  private updateLastUpdated() {
+    this.lastUpdated.set(new Date().toISOString());
+  }
+
+  refreshData() {
+    this.loadUserData();
+  }
+
+  private saveToServer() {
+    const preferences = {
+      theme: this.theme(),
+      notifications: this.notifications(),
+      lastUpdated: this.lastUpdated()
+    };
+
+    this.httpManager.postRequest(
+      ApiRequest.adapt({ path: ['user', 'preferences'] }),
+      preferences
+    ).subscribe();
+  }
+}
+```
+
+## Performance Considerations
+
+### Optimized Rendering
+
+```typescript
+import { trackByFn } from '@angular/core';
+
+@Component({
+  template: `
+    <div *ngFor="let user; trackBy: trackByUserId">
+      {{ user.name }}
+    </div>
+  `
+})
+export class OptimizedComponent {
+  private httpManager = inject(HTTPManagerSignalsService);
+  data = this.httpManager.data;
+
+  trackByUserId = (index: number, user: any) => user.id;
+}
+```
+
+### Efficient Computed Signals
+
+```typescript
+// ✅ Good - Efficient computed
+filteredData = computed(() => {
+  return this.data().filter(item => item.active);
+});
+
+// ❌ Avoid - Inefficient computed
+allData = computed(() => this.data());
+activeData = computed(() => this.allData().filter(item => item.active));
+```
+
+## Best Practices
+
+### 1. Signal Initialization
+
+```typescript
+// ✅ Good
+data = this.httpManager.data;
+isLoading = this.httpManager.isPending;
+
+// ❌ Avoid
+data = signal<any[]>([]);
+isLoading = signal(false);
+```
+
+### 2. Computed Signal Usage
+
+```typescript
+// ✅ Good
+userCount = computed(() => this.data().length);
+
+// ❌ Avoid
+getUserCount() {
+  return this.data().length; // Called on every change detection
+}
+```
+
+### 3. Effect Cleanup
+
+```typescript
+import { effect, inject, OnDestroy } from '@angular/core';
+
+@Component({ template: '...' })
+export class MyComponent implements OnDestroy {
+  private httpManager = inject(HTTPManagerSignalsService);
+  private cleanup?: () => void;
+
+  constructor() {
+    // Store cleanup function
+    this.setupEffects();
+  }
+
+  private setupEffects() {
+    const stopEffect = effect(() => {
+      console.log('Data changed:', this.httpManager.data());
+    });
+    
+    this.cleanup = stopEffect;
+  }
+
+  ngOnDestroy() {
+    if (this.cleanup) {
+      this.cleanup();
+    }
+  }
+}
+```
+
+## Related Documentation
+
+- [HTTP Manager Service](http-manager/README.md)
+- [HTTP State Service](http-state/README.md)
+- [Local Storage Signals](local-storage/README.md)
+- [Angular Signals Documentation](https://angular.io/guide/signals)