http-request-manager 18.15.34 → 18.16.1

package/src/docs/HTTP_SINGNALS_MANAGER_README.md

@@ -1,654 +0,0 @@
-# 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)