http-request-manager 18.15.32 → 18.15.34

package/src/docs/HTTP_MANAGER_README.md

@@ -0,0 +1,628 @@
+# HTTP Manager Service
+
+The `HTTPManagerService` is the core HTTP client service that provides Observable-based request management with comprehensive features for enterprise applications.
+
+## Overview
+
+The HTTPManagerService acts as a wrapper around Angular's HttpClient, providing a centralized way to manage HTTP requests with:
+
+- **State Management** - Exposes `data$`, `isPending$`, `error$`, and `countdown$` observables
+- **Polling Support** - Automatic endpoint polling with countdown timers
+- **Retry Logic** - Configurable retry attempts with delays
+- **Adapters & Mappers** - Data transformation for requests and responses
+- **Streaming** - Support for streaming responses (NDJSON, Server-Sent Events)
+- **Error Handling** - Centralized error handling with optional toast notifications
+- **File Downloads** - Progress tracking for file downloads
+- **File Uploads** - Multi-file upload with progress tracking, validation, and form-data configuration ([see Upload Request docs](./UPLOAD_REQUEST_README.md))
+
+## Installation
+
+This service is automatically available when you import `HttpRequestManagerModule`.
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({})]
+})
+export class AppModule { }
+```
+
+## Usage
+
+### 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 *ngFor="let user of data$ | async">
+      {{ user.name }}
+    </div>
+  `
+})
+export class UsersComponent {
+  httpManager = inject(HTTPManagerService);
+  
+  data$ = this.httpManager.data$;
+  isLoading$ = this.httpManager.isPending$;
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    ).subscribe();
+  }
+}
+```
+
+### Service Extension Pattern
+
+```typescript
+import { Injectable } from '@angular/core';
+import { HTTPManagerService, ApiRequest } from 'http-request-manager';
+import { BehaviorSubject, EMPTY } from 'rxjs';
+import { catchError } from 'rxjs/operators';
+
+@Injectable()
+export class UserService extends HTTPManagerService<any> {
+  
+  private errorRetry$ = new BehaviorSubject<{ func: Function, message: string } | null>(null);
+  errorRetryMessage$ = this.errorRetry$.asObservable();
+
+  private apiRequest = ApiRequest.adapt({
+    server: 'api/users',
+    adapter: User.adapt
+  });
+
+  private params = { type: 'ACTIVE' };
+
+  fetchUsers(params = this.params) {
+    return this.httpManagerService.getRequest(this.apiRequest, [params])
+      .pipe(
+        catchError((error: HttpErrorResponse) => {
+          const func = this.fetchUsers.bind(this);
+          const message = error.message;
+          this.errorRetry$.next({ func, message });
+          return EMPTY;
+        })
+      );
+  }
+}
+```
+
+## API Reference
+
+### ApiRequest Configuration
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `server` | `string` | Base URL for the request | `''` |
+| `path` | `any[]` | Path segments to append to URL | `[]` |
+| `headers` | `any` | Custom headers for request | `{}` |
+| `adapter` | `function` | Transform incoming response data | `undefined` |
+| `mapper` | `function` | Transform outgoing request payload | `undefined` |
+| `polling` | `number` | Polling interval in seconds (0 = disabled) | `0` |
+| `retry` | `RetryOptions` | Retry configuration | `{ times: 0, delay: 3 }` |
+| `stream` | `boolean` | Enable streaming response handling | `false` |
+| `streamType` | `StreamType` | Streaming format: `NDJSON`, `SSE`, or `AI_STREAMING` | `AI_STREAMING` |
+| `displayError` | `boolean` | Show toast notification on error | `false` |
+| `displaySuccess` | `boolean` | Show toast notification on success | `false` |
+| `successMessage` | `string` | Custom success toast message | `undefined` |
+| `errorMessage` | `string` | Custom error toast message | `undefined` |
+| `saveAs` | `string` | Filename for file downloads | `undefined` |
+| `fileContentHeader` | `string` | Content-Disposition header for downloads | `undefined` |
+| `ws` | `WSOptions` | WebSocket configuration for real-time sync | `undefined` |
+| `env` | `string` | Environment for WebSocket channel naming | `'dev'` |
+| `uploadFieldName` | `string` | Form-data field name for uploads | `undefined` |
+| `uploadHttpMethod` | `'POST' \| 'PUT'` | HTTP method for upload requests | `undefined` |
+| `allowedTypes` | `string[]` | Allowed MIME types for upload validation | `[]` |
+| `maxFileSize` | `number` | Maximum per-file size in bytes | `undefined` |
+| `maxTotalSize` | `number` | Maximum total upload size in bytes | `undefined` |
+
+### State-Only Request Tracking Options
+
+The following request options are not part of HTTPManagerService base ApiRequest options.
+They are handled by HTTPManagerStateService request methods (fetchRecords/fetchStream):
+
+- `ignoreQueryParams` — Query parameter keys to exclude from request-change tracking
+- `queryParamsExpiresIn` — Expiry duration for tracked query values (e.g., `'10s'`, `'5mn'`, `'1h'`)
+- `watchParams` — Specific query keys to watch for change detection (variation mode)
+- `watchExpiresAt` — Epoch timestamp when tracked values expire
+- `forceRefresh` — Bypass tracking and always make the API request
+
+Important scope:
+
+- Database enabled (DatabaseStorage configured in HTTPManagerStateService): tracking and expiry behavior are active.
+- Database disabled: tracking is bypassed and API calls proceed normally.
+
+If you need this behavior, use HTTPManagerStateService docs:
+
+- ./HTTP_STATE_MANAGER_README.md
+
+### Observable Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data$` | `Observable<any>` | Response data from requests |
+| `isPending$` | `Observable<boolean>` | Loading state indicator |
+| `error$` | `Observable<any>` | Error state |
+| `countdown$` | `Observable<number>` | Countdown for polling (if active) |
+
+### HTTP Methods
+
+#### getRequest(options: ApiRequest, params?: any[])
+
+Make a GET request with the specified options.
+
+```typescript
+this.httpManager.getRequest(
+  ApiRequest.adapt({
+    path: ['users', '123'],
+    retry: { times: 3, delay: 1 }
+  })
+).subscribe();
+```
+
+#### postRequest(data: T, options: ApiRequest, params?: any[])
+
+Make a POST request with data payload.
+
+```typescript
+this.httpManager.postRequest(
+  { name: 'John Doe', email: 'john@example.com' },
+  ApiRequest.adapt({ path: ['users'] })
+).subscribe();
+```
+
+#### putRequest(data: T, options: ApiRequest, params?: any[])
+
+Make a PUT request with data payload.
+
+```typescript
+this.httpManager.putRequest(
+  { name: 'Jane Doe', email: 'jane@example.com' },
+  ApiRequest.adapt({ path: ['users', '123'] })
+).subscribe();
+```
+
+#### deleteRequest(options: ApiRequest, params?: any[])
+
+Make a DELETE request.
+
+```typescript
+this.httpManager.deleteRequest(
+  ApiRequest.adapt({ path: ['users', '123'] })
+).subscribe();
+```
+
+#### downloadRequest(options: ApiRequest, params?: any[], saveAs?: string)
+
+Download a file with progress tracking.
+
+```typescript
+this.httpManager.downloadRequest(
+  ApiRequest.adapt({
+    server: 'assets',
+    path: ['report.pdf']
+  }),
+  [],
+  'monthly-report.pdf'
+).subscribe();
+```
+
+#### uploadRequest(files: File | File[], options: ApiRequest, params?: any[])
+
+Upload one or more files with progress tracking and validation. See [Upload Request docs](./UPLOAD_REQUEST_README.md) for full details.
+
+```typescript
+this.httpManager.uploadRequest(
+  selectedFiles,
+  ApiRequest.adapt({
+    path: ['uploader'],
+    allowedTypes: ['image/jpeg', 'image/png'],
+    maxFileSize: 40 * 1024 * 1024
+  })
+).subscribe();
+```
+
+## Advanced Features
+
+### Polling
+
+Enable automatic polling of endpoints with countdown display:
+
+```typescript
+this.httpManager.getRequest(
+  ApiRequest.adapt({
+    path: ['server-status'],
+    polling: 10  // Poll every 10 seconds
+  })
+).subscribe();
+
+// Countdown display
+countdown$ = this.httpManager.countdown$; // 10, 9, 8, 7...
+```
+
+### Streaming Responses
+
+Handle streaming responses for real-time data:
+
+```typescript
+// NDJSON Streaming
+this.httpManager.getRequest(
+  ApiRequest.adapt({
+    path: ['stream', 'data'],
+    stream: true,
+    adapter: StreamingData.adapt
+  })
+).subscribe();
+
+// AI Streaming
+this.httpManager.postRequest(
+  ApiRequest.adapt({
+    path: ['ai', 'chat'],
+    stream: true,
+    streamType: 'ai_streaming'
+  }),
+  { message: 'Hello AI' }
+).subscribe();
+```
+
+### Retry Logic
+
+Configure automatic retry for failed requests:
+
+```typescript
+this.httpManager.getRequest(
+  ApiRequest.adapt({
+    path: ['unreliable-endpoint'],
+    retry: { times: 5, delay: 2 },  // Retry 5 times with 2s delay
+    displayError: true              // Show toast on final failure
+  })
+).subscribe();
+```
+
+### Data Adapters
+
+Transform incoming data using adapter functions:
+
+```typescript
+// Define adapter
+export class User {
+  constructor(
+    public id: number = 0,
+    public name: string = '',
+    public email: string = ''
+  ) {}
+
+  static adapt(item: any): User {
+    return new User(
+      item.id,
+      item.fullName,     // Map fullName to name
+      item.emailAddress  // Map emailAddress to email
+    );
+  }
+}
+
+// Use adapter
+this.httpManager.getRequest(
+  ApiRequest.adapt({
+    path: ['users'],
+    adapter: User.adapt
+  })
+).subscribe();
+
+// Data is automatically transformed using User.adapt
+data$ = this.httpManager.data$; // Observable<User[]>
+```
+
+### Data Mappers
+
+Transform outgoing data before sending to API:
+
+```typescript
+// Define mapper
+export class UserMapper {
+  static adapt(user: User): any {
+    return {
+      id: user.id,
+      fullName: user.name,      // Map name to fullName
+      emailAddress: user.email, // Map email to emailAddress
+      active: true
+    };
+  }
+}
+
+// Use mapper
+this.httpManager.postRequest(
+  ApiRequest.adapt({
+    path: ['users'],
+    mapper: UserMapper.adapt
+  }),
+  new User(1, 'John Doe', 'john@example.com')
+).subscribe();
+```
+
+## Demo Examples
+
+### Complete HTTP Service Example
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { FormBuilder, Validators } from '@angular/forms';
+import { HTTPManagerService, ApiRequest } from 'http-request-manager';
+
+@Component({
+  selector: 'app-api-client',
+  template: `
+    <form [formGroup]="requestForm" (ngSubmit)="makeRequest()">
+      <input formControlName="endpoint" placeholder="API endpoint">
+      <button type="submit">Make Request</button>
+    </form>
+
+    <div *ngIf="isLoading$ | async">Loading...</div>
+    
+    <div *ngIf="error$ | async as error" class="error">
+      Error: {{ error }}
+    </div>
+
+    <pre *ngIf="data$ | async as data">
+      {{ data | json }}
+    </pre>
+
+    <div *ngIf="countdown$ | async as countdown">
+      Next request in: {{ countdown }}s
+    </div>
+  `
+})
+export class ApiClientComponent {
+  private fb = inject(FormBuilder);
+  private httpManager = inject(HTTPManagerService);
+
+  data$ = this.httpManager.data$;
+  isLoading$ = this.httpManager.isPending$;
+  error$ = this.httpManager.error$;
+  countdown$ = this.httpManager.countdown$;
+
+  requestForm = this.fb.group({
+    endpoint: ['users', Validators.required],
+    method: ['GET', Validators.required],
+    polling: [0],
+    retry: this.fb.group({
+      times: [3],
+      delay: [2],
+    })
+  });
+
+  makeRequest() {
+    const formValue = this.requestForm.value;
+    
+    this.httpManager.getRequest(
+      ApiRequest.adapt({
+        path: [formValue.endpoint],
+        polling: formValue.polling,
+        retry: formValue.retry,
+        displayError: true
+      })
+    ).subscribe();
+  }
+}
+```
+
+### Error Handling with Retry
+
+```typescript
+export class RobustApiService {
+  private errorRetry$ = new BehaviorSubject<{ func: Function, message: string } | null>(null);
+  errorRetryMessage$ = this.errorRetry$.asObservable();
+
+  makeRequestWithRetry(endpoint: string) {
+    return this.httpManager.getRequest(
+      ApiRequest.adapt({
+        path: [endpoint],
+        retry: { times: 3, delay: 2 },
+        displayError: true
+      })
+    ).pipe(
+      catchError((error: HttpErrorResponse) => {
+        this.errorRetry$.next({
+          func: () => this.makeRequestWithRetry(endpoint),
+          message: error.message
+        });
+        return EMPTY;
+      })
+    );
+  }
+
+  retry() {
+    const retryAction = this.errorRetry$.value;
+    if (retryAction) {
+      retryAction.func();
+    }
+  }
+}
+```
+
+## Integration with Other Services
+
+The HTTPManagerService can be extended and used with other services:
+
+### With State Management
+
+```typescript
+@Injectable()
+export class UserStateService extends HTTPManagerStateService<User> {
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        path: ['users'],
+        adapter: User.adapt
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  loadUsers() {
+    this.fetchRecords(); // Uses HTTPManagerService internally
+  }
+}
+```
+
+### With WebSocket
+
+```typescript
+@Injectable()
+export class ChatService extends HTTPManagerStateService<Message> {
+  constructor() {
+    super(
+      ApiRequest.adapt({
+        path: ['messages'],
+        adapter: Message.adapt,
+        ws: {
+          id: 'CHAT_WS',
+          wsServer: 'ws://localhost:8080'
+        }
+      }),
+      DataType.ARRAY
+    );
+  }
+
+  // HTTP + WebSocket combined
+  sendMessage(content: string) {
+    // HTTP POST to save message
+    this.createRecord({ content, timestamp: Date.now() });
+    
+    // WebSocket broadcast
+    this.wsMessaging(
+      { content: { message: content } },
+      ['chat-room']
+    );
+  }
+}
+```
+
+## Best Practices
+
+### 1. Service Layer Pattern
+
+Always create dedicated services that extend or use HTTPManagerService:
+
+```typescript
+// ✅ Good
+@Injectable()
+export class UserService {
+  constructor(private http: HTTPManagerService) {}
+  
+  getUsers() {
+    return this.http.getRequest(
+      ApiRequest.adapt({ path: ['users'] })
+    );
+  }
+}
+
+// ❌ Avoid
+@Component({
+  template: `<div *ngFor="let user of http.data$ | async">`
+})
+export class BadComponent {
+  constructor(private http: HTTPManagerService) {}
+}
+```
+
+### 2. Error Handling
+
+Implement comprehensive error handling:
+
+```typescript
+fetchData() {
+  this.data$ = this.httpManager.getRequest(
+    ApiRequest.adapt({
+      path: ['data'],
+      retry: { times: 3, delay: 2 },
+      displayError: true
+    })
+  );
+}
+```
+
+### 3. Adapter Usage
+
+Use adapters for type safety:
+
+```typescript
+// ✅ Good
+ApiRequest.adapt({
+  path: ['users'],
+  adapter: User.adapt  // Ensures type safety
+});
+
+// ❌ Avoid
+ApiRequest.adapt({
+  path: ['users']
+  // No adapter = loose typing
+});
+```
+
+### 4. Cleanup
+
+Always clean up subscriptions:
+
+```typescript
+@Component({ template: '...' })
+export class MyComponent implements OnDestroy {
+  private destroy$ = new Subject<void>();
+
+  ngOnInit() {
+    this.httpManager.getRequest(
+      ApiRequest.adapt({ path: ['data'] })
+    ).pipe(takeUntil(this.destroy$)).subscribe();
+  }
+
+  ngOnDestroy() {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. CORS Errors
+```typescript
+// Enable CORS in ApiRequest
+ApiRequest.adapt({
+  server: 'https://api.example.com',
+  headers: { 'Access-Control-Allow-Origin': '*' }
+});
+```
+
+#### 2. Authentication Headers
+```typescript
+// Add auth headers
+ApiRequest.adapt({
+  headers: {
+    'Authorization': `Bearer ${this.authToken}`,
+    'Content-Type': 'application/json'
+  }
+});
+```
+
+#### 3. Polling Not Stopping
+```typescript
+ngOnDestroy() {
+  this.httpManager.stopPolling(); // Important!
+}
+```
+
+## Related Documentation
+
+- [Architecture Overview](../architecture/README.md)
+- [HTTP State Service](http-state/README.md)
+- [HTTP Signals Service](http-signals/README.md)
+- [Demo Examples](../demos/README.md)