http-request-manager 18.15.34 → 18.16.1

package/src/docs/HTTP_MANAGER_README.md

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