@codex-ts/core-lib 1.0.0

package/src/lib/services/http-utility.service.md

@@ -0,0 +1,175 @@
+# HttpUtilityService
+
+A general-purpose HTTP utility service that extends Angular's HttpClient with additional functionality for common HTTP operations.
+
+## Features
+
+- **Enhanced HTTP Methods**: Typed GET, POST, PUT, DELETE methods with additional options
+- **Loading State Management**: Built-in loading state tracking
+- **Error Handling**: Standardized error handling with message display
+- **Request Configuration**:
+  - Timeout configuration
+  - Retry capabilities
+  - Custom headers and params support
+- **Specialized Operations**:
+  - File uploads with progress tracking
+  - File downloads
+  - Batch request handling
+
+## Installation
+
+The service is part of the core library. It's already registered with the Angular DI system, so you can inject it directly into your components and services.
+
+## Usage
+
+### Basic Import
+
+```typescript
+import { HttpUtilityService } from '@core/core-lib';
+
+@Component({
+  // ...
+})
+export class MyComponent {
+  constructor(private httpUtil: HttpUtilityService) {}
+}
+```
+
+### GET Requests
+
+```typescript
+// Simple GET request
+this.httpUtil.get<UserData>('/api/users/123').subscribe({
+  next: (data) => console.log('User data:', data),
+  error: (err) => console.error('Error fetching user:', err)
+});
+
+// GET with parameters and options
+const params = this.httpUtil.createParams({
+  filter: 'active',
+  sort: 'name',
+  page: 1
+});
+
+this.httpUtil.get<PagedResponse<UserData>>('/api/users', {
+  params,
+  retries: 2,
+  timeoutMs: 5000
+}).subscribe({
+  next: (data) => this.handleData(data),
+  error: (err) => this.handleError(err)
+});
+```
+
+### POST Requests
+
+```typescript
+const newUser = {
+  name: 'John Doe',
+  email: 'john@example.com'
+};
+
+this.httpUtil.post<UserData>('/api/users', newUser).subscribe({
+  next: (data) => console.log('User created:', data),
+  error: (err) => console.error('Error creating user:', err)
+});
+```
+
+### PUT Requests
+
+```typescript
+const updatedUser = {
+  id: '123',
+  name: 'John Smith',
+  email: 'john@example.com'
+};
+
+this.httpUtil.put<UserData>(`/api/users/${updatedUser.id}`, updatedUser).subscribe({
+  next: (data) => console.log('User updated:', data),
+  error: (err) => console.error('Error updating user:', err)
+});
+```
+
+### DELETE Requests
+
+```typescript
+this.httpUtil.delete<void>('/api/users/123').subscribe({
+  next: () => console.log('User deleted successfully'),
+  error: (err) => console.error('Error deleting user:', err)
+});
+```
+
+### File Upload with Progress
+
+```typescript
+// Get file from a file input
+const fileInput = event.target.files[0];
+
+// Additional form data
+const metadata = {
+  description: 'Profile photo',
+  userId: '123'
+};
+
+this.httpUtil.uploadFile<{url: string}>('/api/upload', fileInput, metadata, {
+  onProgress: (percent) => this.uploadProgress = percent
+}).subscribe({
+  next: (response) => this.imageUrl = response.url,
+  error: (err) => console.error('Upload failed:', err)
+});
+```
+
+### File Download
+
+```typescript
+this.httpUtil.downloadFile('/api/reports/123', 'report.pdf').subscribe({
+  next: (blob) => {
+    // Create download link
+    const url = window.URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = 'report.pdf';
+    document.body.appendChild(a);
+    a.click();
+    window.URL.revokeObjectURL(url);
+    a.remove();
+  },
+  error: (err) => console.error('Download failed:', err)
+});
+```
+
+### Batch Requests
+
+```typescript
+// Create multiple requests
+const userRequest = this.httpUtil.get<UserData>('/api/users/123');
+const ordersRequest = this.httpUtil.get<Order[]>(`/api/users/123/orders`);
+
+// Execute all requests in parallel
+this.httpUtil.batchRequests([userRequest, ordersRequest]).subscribe({
+  next: ([user, orders]) => {
+    this.user = user;
+    this.orders = orders;
+  },
+  error: (err) => console.error('Error fetching data:', err)
+});
+```
+
+### Loading State
+
+The service exposes a loading state observable that you can subscribe to:
+
+```typescript
+this.httpUtil.loading$.subscribe(isLoading => {
+  this.isLoading = isLoading;
+  // Update UI based on loading state
+});
+```
+
+## Error Handling
+
+The service automatically handles common HTTP errors and displays appropriate messages using the MessageService if it's provided in the constructor.
+
+## Advanced Usage
+
+For more complex usage examples, see the `http-utility.service.example.ts` file.

package/src/lib/services/http-utility.service.ts

@@ -0,0 +1,389 @@
+import { Injectable } from '@angular/core';
+import { HttpClient, HttpParams, HttpHeaders, HttpErrorResponse, HttpEvent } from '@angular/common/http';
+import { Observable, throwError, BehaviorSubject, finalize, forkJoin } from 'rxjs';
+import { catchError, retry, timeout } from 'rxjs/operators';
+import { MessageService } from 'primeng/api';
+
+/**
+ * A general-purpose HTTP utility service that provides enhanced HTTP operations
+ * beyond the standard Angular HttpClient. This service includes features such as:
+ * - Loading state management
+ * - Standardized error handling
+ * - Request timeouts and retries
+ * - File upload capabilities
+ * - Batch request handling
+ */
+@Injectable({
+  providedIn: 'root'
+})
+export class HttpUtilityService {
+  private loading = new BehaviorSubject<boolean>(false);
+  loading$ = this.loading.asObservable();
+
+  constructor(
+    private http: HttpClient,
+    private messageService?: MessageService
+  ) {}
+
+  /**
+   * Perform a GET request with enhanced options
+   * @param url The endpoint URL
+   * @param options Additional request options
+   * @returns An observable of the response
+   */
+  get<T>(url: string, options?: {
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>,
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    responseType?: 'json',
+    withCredentials?: boolean,
+    retries?: number,
+    timeoutMs?: number
+  }): Observable<T> {
+    this.loading.next(true);
+    
+    let request$ = this.http.get<T>(url, {
+      params: options?.params,
+      headers: options?.headers,
+      responseType: options?.responseType as 'json',
+      withCredentials: options?.withCredentials
+    });
+    
+    if (options?.retries) {
+      request$ = request$.pipe(retry(options.retries));
+    }
+    
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+
+  /**
+   * Perform a POST request with enhanced options
+   * @param url The endpoint URL
+   * @param body The request payload
+   * @param options Additional request options
+   * @returns An observable of the response
+   */
+  post<T>(url: string, body: any, options?: {
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>,
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    responseType?: 'json',
+    withCredentials?: boolean,
+    retries?: number,
+    timeoutMs?: number
+  }): Observable<T> {
+    this.loading.next(true);
+    
+    let request$ = this.http.post<T>(url, body, {
+      params: options?.params,
+      headers: options?.headers,
+      responseType: options?.responseType as 'json',
+      withCredentials: options?.withCredentials
+    });
+    
+    if (options?.retries) {
+      request$ = request$.pipe(retry(options.retries));
+    }
+    
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+
+  /**
+   * Perform a PUT request with enhanced options
+   * @param url The endpoint URL
+   * @param body The request payload
+   * @param options Additional request options
+   * @returns An observable of the response
+   */
+  put<T>(url: string, body: any, options?: {
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>,
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    responseType?: 'json',
+    withCredentials?: boolean,
+    retries?: number,
+    timeoutMs?: number
+  }): Observable<T> {
+    this.loading.next(true);
+    
+    let request$ = this.http.put<T>(url, body, {
+      params: options?.params,
+      headers: options?.headers,
+      responseType: options?.responseType as 'json',
+      withCredentials: options?.withCredentials
+    });
+    
+    if (options?.retries) {
+      request$ = request$.pipe(retry(options.retries));
+    }
+    
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+
+  /**
+   * Perform a DELETE request with enhanced options
+   * @param url The endpoint URL
+   * @param options Additional request options
+   * @returns An observable of the response
+   */
+  delete<T>(url: string, options?: {
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>,
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    responseType?: 'json',
+    withCredentials?: boolean,
+    retries?: number,
+    timeoutMs?: number
+  }): Observable<T> {
+    this.loading.next(true);
+    
+    let request$ = this.http.delete<T>(url, {
+      params: options?.params,
+      headers: options?.headers,
+      responseType: options?.responseType as 'json',
+      withCredentials: options?.withCredentials
+    });
+    
+    if (options?.retries) {
+      request$ = request$.pipe(retry(options.retries));
+    }
+    
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+  
+  /**
+   * Upload a file with optional additional data
+   * @param url The upload endpoint URL
+   * @param file The file to upload
+   * @param additionalData Additional form data to include
+   * @param options Additional request options
+   * @returns An observable of the response
+   */
+  uploadFile<T>(url: string, file: File, additionalData?: Record<string, any>, options?: {
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    withCredentials?: boolean,
+    retries?: number,
+    timeoutMs?: number,
+    onProgress?: (percentage: number) => void
+  }): Observable<T> {
+    this.loading.next(true);
+    
+    const formData = new FormData();
+    formData.append('file', file, file.name);
+    
+    if (additionalData) {
+      Object.keys(additionalData).forEach(key => {
+        formData.append(key, additionalData[key]);
+      });
+    }
+    
+    let httpOptions: any = {
+      headers: options?.headers,
+      withCredentials: options?.withCredentials
+    };
+    
+    // If progress tracking is requested
+    if (options?.onProgress) {
+      httpOptions.reportProgress = true;
+      httpOptions.observe = 'events';
+    }
+    
+    // Create the request
+    let request$ = this.http.post<any>(url, formData, httpOptions);
+    
+    // Add retries if specified
+    if (options?.retries) {
+      request$ = request$.pipe(retry(options.retries));
+    }
+    
+    // Add timeout if specified
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    // Track progress if a callback is provided
+    if (options?.onProgress) {
+      return new Observable<T>(observer => {
+        request$.subscribe({
+          next: (event: HttpEvent<any>) => {
+            if (event.type === 1 && event.total) { // HttpEventType.UploadProgress
+              const percentDone = Math.round(100 * event.loaded / event.total);
+              options.onProgress!(percentDone);
+            } else if (event.type === 4) { // HttpEventType.Response
+              observer.next(event.body);
+              observer.complete();
+            }
+          },
+          error: (error) => {
+            observer.error(this.handleError(error));
+            this.loading.next(false);
+          },
+          complete: () => {
+            this.loading.next(false);
+          }
+        });
+      });
+    }
+    
+    // Standard request without progress tracking
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    ) as Observable<T>;
+  }
+
+  /**
+   * Execute multiple HTTP requests in parallel
+   * @param requests Array of HTTP request observables
+   * @returns An observable that emits when all requests complete
+   */
+  batchRequests<T>(requests: Observable<T>[]): Observable<T[]> {
+    this.loading.next(true);
+    return forkJoin(requests).pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+  
+  /**
+   * Download a file from the server
+   * @param url The file URL
+   * @param filename Optional filename to save as
+   * @param options Additional request options
+   */
+  downloadFile(url: string, filename?: string, options?: {
+    params?: HttpParams | Record<string, string | number | boolean | readonly (string | number | boolean)[]>,
+    headers?: HttpHeaders | Record<string, string | string[]>,
+    withCredentials?: boolean,
+    timeoutMs?: number
+  }): Observable<Blob> {
+    this.loading.next(true);
+    
+    let request$ = this.http.get(url, {
+      params: options?.params,
+      headers: options?.headers,
+      responseType: 'blob',
+      withCredentials: options?.withCredentials
+    });
+    
+    if (options?.timeoutMs) {
+      request$ = request$.pipe(timeout(options.timeoutMs));
+    }
+    
+    return request$.pipe(
+      catchError(this.handleError.bind(this)),
+      finalize(() => this.loading.next(false))
+    );
+  }
+
+  /**
+   * Create parameter string from an object
+   * @param params Object containing parameters
+   * @returns HttpParams object
+   */
+  createParams(params: Record<string, any>): HttpParams {
+    let httpParams = new HttpParams();
+    
+    Object.keys(params).forEach(key => {
+      const value = params[key];
+      if (value !== undefined && value !== null) {
+        httpParams = httpParams.append(key, value.toString());
+      }
+    });
+    
+    return httpParams;
+  }
+
+  /**
+   * Standardized error handler for HTTP requests
+   * @param error The HTTP error
+   * @returns An observable that errors with the processed error object
+   */
+  private handleError(error: HttpErrorResponse) {
+    console.error('An HTTP error occurred:', error);
+    
+    let errorMessage = 'An error occurred';
+    let errorCode: string | undefined;
+    
+    if (error.error instanceof ErrorEvent) {
+      // Client-side error
+      errorMessage = error.error.message;
+    } else {
+      // Server-side error
+      errorCode = error.status.toString();
+      
+      switch (error.status) {
+        case 400:
+          errorMessage = error.error?.message || 'Bad request';
+          break;
+        case 401:
+          errorMessage = 'Unauthorized';
+          break;
+        case 403:
+          errorMessage = 'Access denied';
+          break;
+        case 404:
+          errorMessage = 'Resource not found';
+          break;
+        case 408:
+          errorMessage = 'Request timeout';
+          break;
+        case 500:
+          errorMessage = 'Server error';
+          break;
+        case 503:
+          errorMessage = 'Service unavailable';
+          break;
+        default:
+          errorMessage = error.error?.message || `Error ${error.status}`;
+          break;
+      }
+    }
+
+    this.showError(errorMessage);
+    return throwError(() => ({
+      error,
+      message: errorMessage,
+      code: errorCode
+    }));
+  }
+
+  /**
+   * Display an error message using the message service
+   * @param message Error message to display
+   */
+  private showError(message: string) {
+    if (this.messageService) {
+      this.messageService.add({
+        severity: 'error',
+        summary: 'Error',
+        detail: message,
+        life: 3000
+      });
+    }
+  }
+}

package/src/lib/services/notification.service.ts

@@ -0,0 +1,35 @@
+import { Injectable } from '@angular/core';
+import { MessageService } from 'primeng/api';
+import { BehaviorSubject } from 'rxjs';
+
+@Injectable()
+export class NotificationService {
+  private messageSubject = new BehaviorSubject<any>(null);
+  message$ = this.messageSubject.asObservable();
+
+  constructor(private messageService: MessageService) {}
+
+  showSuccess(message: string) {
+    const msgObj = {
+      severity: 'success',
+      summary: 'Success',
+      detail: message,
+      life: 3000
+    };
+    this.messageSubject.next(msgObj);
+  }
+
+  showError(message: string) {
+    const msgObj = {
+      severity: 'error',
+      summary: 'Error',
+      detail: message,
+      life: 3000
+    };
+    this.messageSubject.next(msgObj);
+  }
+
+  clearMessage() {
+    this.messageSubject.next(null);
+  }
+}

package/src/lib/services/reference-data-provider.service.ts

@@ -0,0 +1,28 @@
+import { Injectable } from '@angular/core';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class ReferenceDataProviderService {
+
+  private endpoints: Record<string, string> = {};
+
+  // Method to set/update endpoints
+  setEndpoints(endpoints: Record<string, string>) {
+    this.endpoints = { ...this.endpoints, ...endpoints };
+  }
+
+  getReferenceEndpoint(entityName: string): string | null {
+    console.log('getReferenceEndpoint', entityName, this.endpoints);
+    let endpoint = this.endpoints[entityName];
+    if (endpoint != null && endpoint.length > 0) {
+      if (endpoint.startsWith('http://') || endpoint.startsWith('https://')) {
+        return endpoint; // Absolute URL
+      } else {
+        // Relative URL, assume it's within the application's base context
+        return endpoint;
+      }
+    }
+    return null;
+  }
+}