http-request-manager 18.15.32 → 18.15.34

package/src/docs/UPLOAD_REQUEST_README.md

@@ -0,0 +1,324 @@
+# File Upload Request
+
+The `uploadRequest` method provides a complete file upload solution with progress tracking, client-side validation, and configurable options. It is available on both `HTTPManagerService` (Observable) and `HTTPManagerSignalsService` (Signals).
+
+## Overview
+
+```typescript
+uploadRequest<T>(files: File | File[], options: ApiRequest, params?: any[]): Observable<T>
+```
+
+The method sends files as `multipart/form-data` via HTTP POST (or PUT) with upload progress reporting.
+
+## ApiRequest Upload Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `server` | `string` | `''` | Server key mapped via proxy config (e.g. `'gtlcApi'`) |
+| `path` | `string[]` | `[]` | URL path segments (e.g. `['uploader']`) |
+| `uploadFieldName` | `string` | `'file'` (single) / `'files'` (multiple) | Form-data field name for the file(s) |
+| `uploadHttpMethod` | `'POST' \| 'PUT'` | `'POST'` | HTTP method for the upload request |
+| `allowedTypes` | `string[]` | `[]` | Allowed MIME types (e.g. `['image/jpeg', 'image/png']`). Empty array = all types allowed |
+| `maxFileSize` | `number` | `Infinity` | Maximum file size in bytes (e.g. `40 * 1024 * 1024` = 40MB) |
+| `maxTotalSize` | `number` | `Infinity` | Maximum total size across all files in bytes |
+| `headers` | `object` | `{}` | Custom HTTP headers |
+| `displayError` | `boolean` | `false` | Show error toast on failure |
+| `displaySuccess` | `boolean` | `false` | Show success toast on completion |
+| `errorMessage` | `string` | — | Custom error message for toast |
+| `successMessage` | `string` | — | Custom success message for toast |
+| `retry` | `RetryOptions` | — | Retry configuration |
+| `polling` | `number` | `0` | Polling interval in seconds |
+
+## Method Signature
+
+```typescript
+uploadRequest<T>(
+  files: File | File[],     // Single file or array of files
+  options: ApiRequest,      // Upload configuration
+  params?: any[]            // Optional path params appended to `path`
+): Observable<T>
+```
+
+### Parameters
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `files` | `File \| File[]` | One or more files to upload |
+| `options` | `ApiRequest` | Upload configuration (see table above) |
+| `params` | `any[]` | (Optional) Additional path segments appended to `options.path` |
+
+### Returns
+
+An `Observable<T>` that emits the server response on success. The observable also provides upload progress updates via the service's `progress$` observable.
+
+## Progress Tracking
+
+The service exposes a `progress$` observable that emits upload progress as a percentage (0–100):
+
+```typescript
+this.httpManager.progress$.subscribe(percent => {
+  console.log(`Upload progress: ${percent}%`);
+});
+```
+
+Progress is tracked using Angular's `HttpEventType.UploadProgress` events.
+
+## Client-Side Validation
+
+Before sending, the service validates files against the configured constraints:
+
+- **File type** — Checks against `allowedTypes` array (supports wildcards like `image/*`)
+- **File size** — Checks each file against `maxFileSize`
+- **Total size** — Checks combined size against `maxTotalSize`
+
+Invalid files are collected and returned as an `UploadValidationErrorModel` error.
+
+## Complete Demo Example
+
+### Upload State Model
+
+```typescript
+// models/upload-state.model.ts
+export interface UploadStateInterface {
+  selectedFiles: File[]
+  isUploading: boolean
+  progress: number
+  currentFile: string | null
+  errorMessage: string | null
+  successMessage: string | null
+}
+
+export class UploadStateModel implements UploadStateInterface {
+  constructor(
+    public selectedFiles: File[] = [],
+    public isUploading: boolean = false,
+    public progress: number = 0,
+    public currentFile: string | null = null,
+    public errorMessage: string | null = null,
+    public successMessage: string | null = null
+  ) {}
+
+  static adapt(item?: any): UploadStateModel {
+    return new UploadStateModel(
+      Array.isArray(item?.selectedFiles) ? item.selectedFiles : [],
+      item?.isUploading ?? false,
+      item?.progress ?? 0,
+      item?.currentFile ?? null,
+      item?.errorMessage ?? null,
+      item?.successMessage ?? null
+    )
+  }
+}
+```
+
+### Component
+
+```typescript
+import { Component, inject } from '@angular/core'
+import { ApiRequest, HTTPManagerService } from 'http-request-manager'
+import { UploadStateModel } from './models/upload-state.model'
+
+@Component({
+  selector: 'app-file-upload',
+  templateUrl: './file-upload.component.html'
+})
+export class FileUploadComponent {
+
+  private httpManager = inject(HTTPManagerService)
+
+  uploadState = UploadStateModel.adapt()
+
+  allowedTypes = ['image/jpeg', 'image/png', 'application/pdf']
+  maxFileSize = 40 * 1024 * 1024 // 40MB
+
+  onFileSelected(event: Event): void {
+    const input = event.target as HTMLInputElement
+    const files = input.files
+
+    if (!files || files.length === 0) return
+
+    this.uploadState.selectedFiles = []
+    this.uploadState.errorMessage = null
+
+    for (let i = 0; i < files.length; i++) {
+      const file = files[i]
+      const validationError = this.validateFile(file)
+
+      if (validationError) {
+        this.uploadState.errorMessage = validationError
+        continue
+      }
+
+      this.uploadState.selectedFiles.push(file)
+    }
+  }
+
+  validateFile(file: File): string | null {
+    if (!this.allowedTypes.includes(file.type)) {
+      return `File "${file.name}" is not a valid type.`
+    }
+    if (file.size > this.maxFileSize) {
+      return `File "${file.name}" exceeds maximum size of 40MB.`
+    }
+    return null
+  }
+
+  startUpload(): void {
+    if (this.uploadState.selectedFiles.length === 0) return
+
+    this.uploadState.isUploading = true
+    this.uploadState.progress = 0
+    this.uploadState.errorMessage = null
+    this.uploadState.successMessage = null
+
+    const options = ApiRequest.adapt({
+      server: 'gtlcApi',
+      path: ['uploader'],
+      uploadFieldName: 'files',
+      allowedTypes: this.allowedTypes,
+      maxFileSize: this.maxFileSize
+    })
+
+    // Track upload progress
+    this.httpManager.progress$.subscribe(percent => {
+      this.uploadState.progress = percent
+    })
+
+    this.httpManager.uploadRequest<any>(
+      this.uploadState.selectedFiles,
+      options,
+      ['upload']  // optional path params
+    ).subscribe({
+      next: (response) => {
+        this.uploadState.progress = 100
+        this.uploadState.successMessage = `Uploaded ${this.uploadState.selectedFiles.length} file(s)`
+        this.uploadState.isUploading = false
+      },
+      error: (error) => {
+        this.uploadState.errorMessage = error.message || 'Upload failed'
+        this.uploadState.isUploading = false
+        this.uploadState.progress = 0
+      }
+    })
+  }
+
+  clearSelection(): void {
+    this.uploadState = UploadStateModel.adapt()
+  }
+
+  getFileSizeString(size: number): string {
+    if (size < 1024) return `${size} bytes`
+    if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`
+    return `${(size / (1024 * 1024)).toFixed(1)} MB`
+  }
+}
+```
+
+### Template
+
+```html
+<div class="upload-container">
+  <h2>File Upload</h2>
+
+  <div class="upload-controls">
+    <button (click)="fileInput.click()" [disabled]="uploadState.isUploading">
+      Select Files
+    </button>
+    <input #fileInput type="file" multiple
+           accept="image/jpeg,image/png,application/pdf"
+           (change)="onFileSelected($event)" hidden>
+    <button (click)="clearSelection()"
+            [disabled]="uploadState.selectedFiles.length === 0">
+      Clear
+    </button>
+  </div>
+
+  <!-- Selected Files -->
+  <div *ngIf="uploadState.selectedFiles.length > 0">
+    <h3>Selected Files ({{uploadState.selectedFiles.length}})</h3>
+    <ul>
+      <li *ngFor="let file of uploadState.selectedFiles">
+        {{file.name}} — {{getFileSizeString(file.size)}}
+      </li>
+    </ul>
+  </div>
+
+  <!-- Progress Bar -->
+  <div *ngIf="uploadState.isUploading" class="progress-bar">
+    <div class="progress-fill" [style.width.%]="uploadState.progress">
+      {{uploadState.progress}}%
+    </div>
+  </div>
+
+  <!-- Messages -->
+  <div *ngIf="uploadState.errorMessage" class="error">
+    {{uploadState.errorMessage}}
+  </div>
+  <div *ngIf="uploadState.successMessage" class="success">
+    {{uploadState.successMessage}}
+  </div>
+
+  <!-- Upload Button -->
+  <button (click)="startUpload()"
+          [disabled]="uploadState.selectedFiles.length === 0 || uploadState.isUploading">
+    {{uploadState.isUploading ? 'Uploading...' : 'Start Upload'}}
+  </button>
+</div>
+```
+
+## Signals Service
+
+The same API is available on `HTTPManagerSignalsService`:
+
+```typescript
+import { HTTPManagerSignalsService } from 'http-request-manager'
+
+private httpManagerSignals = inject(HTTPManagerSignalsService)
+
+// Progress as a signal
+const progress = this.httpManagerSignals.progress
+
+this.httpManagerSignals.uploadRequest<any>(files, options, ['upload'])
+  .subscribe({ ... })
+```
+
+## Error Handling
+
+The service throws an `UploadValidationErrorModel` when client-side validation fails:
+
+```typescript
+interface UploadValidationErrorModel {
+  invalidFiles: InvalidFileInfoModel[]
+  validCount: number
+  totalCount: number
+}
+
+interface InvalidFileInfoModel {
+  fileName: string
+  fileSize: number
+  fileType: string
+  errors: string[]  // e.g. ['type not allowed', 'exceeds maxFileSize']
+}
+```
+
+## Proxy Configuration
+
+When using Angular's proxy, ensure the proxy pattern matches the `server` key:
+
+```json
+{
+  "/gtlcApi/**": {
+    "target": "http://your-api-server:8550/rest/oidc",
+    "secure": false,
+    "changeOrigin": true,
+    "pathRewrite": { "^/gtlcApi": "" },
+    "logLevel": "debug"
+  }
+}
+```
+
+## Important Notes
+
+- **Content-Type** — The browser automatically sets `multipart/form-data` with the correct boundary when sending `FormData`. Do NOT manually set `Content-Type` in interceptors for upload requests.
+- **Form field naming** — Files are appended with the key specified by `uploadFieldName`. Each file uses the same key (e.g. `files`), not indexed keys like `files[0]`.
+- **Large files** — For files over 40MB, consider chunked upload strategies or adjust server limits accordingly.