@one-paragon/angular-utilities 2.8.2 → 2.8.4

package/src/http-request-state/documentation/REQUEST-STATE-STORE-CONFIG.md

@@ -0,0 +1,648 @@
+# RequestStateStoreConfig Documentation
+
+## Overview
+
+`RequestStateStoreConfig` is a global configuration interface that allows you to set default error and success handlers for all requestors in your application. This is useful for establishing consistent error handling patterns, logging, notifications, or analytics across your entire application.
+
+## Interface Definition
+
+```typescript
+export interface RequestStateStoreConfig {
+  /**
+   * if `useDefaultErrorHandler` is `true` this will run on each error if no other handler provided.
+   * else can be used by call `.useDefaultErrorHandler`
+   */
+  defaultErrorHandling?: (e?: any) => void;
+  
+  /**
+   * if `useDefaultErrorHandler` is `true` `defaultErrorHandling` will run on each error if no other handler provided.
+   */
+  useDefaultErrorHandler?: boolean;
+
+  /**
+   * will be called if `useDefaultSuccess` is used
+   */
+  defaultSuccessHandling?: <T>(e?: T) => void;
+}
+```
+
+## Injection Token
+
+```typescript
+export const RequestStateStoreConfigToken = new InjectionToken<RequestStateStoreConfig>('RequestStateConfig');
+```
+
+## Configuration Properties
+
+### `defaultErrorHandling`
+
+A function that handles errors globally for all requestors.
+
+**Type:** `(e?: any) => void`
+
+**Behavior:**
+- If `useDefaultErrorHandler` is `true`, this runs automatically on every error unless a specific error handler is registered
+- Can also be explicitly invoked by calling `.useDefaultErrorHandler()` on a requestor
+- If not provided and `useDefaultErrorHandler()` is called, falls back to `console.error`
+
+### `useDefaultErrorHandler`
+
+Controls whether the default error handler runs automatically for all requestors.
+
+**Type:** `boolean`
+
+**Behavior:**
+- When `true`: Every requestor automatically uses `defaultErrorHandling` unless it has an explicit error handler (via `onError`, `onErrorResponse`, etc.)
+- When `false` or `undefined`: Requestors only use the default handler if `.useDefaultErrorHandler()` is explicitly called
+
+### `defaultSuccessHandling`
+
+A function that handles successful responses globally.
+
+**Type:** `<T>(e?: T) => void`
+
+**Behavior:**
+- Only invoked when `.useDefaultSuccessHandler()` is explicitly called on a requestor
+- If not provided and `useDefaultSuccessHandler()` is called, falls back to `console.log('Success')`
+
+## Providing Configuration
+
+### Standalone Application (app.config.ts)
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useValue: {
+        defaultErrorHandling: (error) => {
+          console.error('Global Error Handler:', error);
+          // Add your global error handling logic
+        },
+        useDefaultErrorHandler: true,
+        defaultSuccessHandling: (response) => {
+          console.log('Global Success Handler:', response);
+          // Add your global success handling logic
+        }
+      }
+    },
+    // ... other providers
+  ]
+};
+```
+
+### Module-based Application
+
+```typescript
+import { NgModule } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+@NgModule({
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useValue: {
+        defaultErrorHandling: (error) => {
+          console.error('Global Error Handler:', error);
+        },
+        useDefaultErrorHandler: true
+      }
+    }
+  ]
+})
+export class AppModule { }
+```
+
+### Component-level Configuration
+
+You can also provide configuration at the component level to override global settings for a specific component and its children.
+
+```typescript
+import { Component } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+@Component({
+  selector: 'app-user-management',
+  template: `...`,
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useValue: {
+        defaultErrorHandling: (error) => {
+          // Component-specific error handling
+          console.error('User Management Error:', error);
+        },
+        useDefaultErrorHandler: false
+      }
+    }
+  ]
+})
+export class UserManagementComponent { }
+```
+
+## Usage Examples
+
+### Basic Global Error Handling
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useValue: {
+        defaultErrorHandling: (error) => {
+          console.error('API Error:', error);
+        },
+        useDefaultErrorHandler: true
+      }
+    }
+  ]
+};
+```
+
+With this configuration, all requestors automatically log errors unless they have explicit error handlers:
+
+```typescript
+// This requestor will automatically use the global error handler
+const getUserRequestor = createRequestor(
+  (id: number) => this.http.get<User>(`/api/users/${id}`)
+);
+
+// This requestor will NOT use the global error handler (explicit handler registered)
+const saveUserRequestor = createRequestor(
+  (user: User) => this.http.post<User>('/api/users', user)
+).onError((error) => {
+  console.log('Custom error handling for save');
+});
+```
+
+### Integration with Toast/Snackbar Service
+
+```typescript
+import { inject, ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+import { MatSnackBar } from '@angular/material/snackbar';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useFactory: () => {
+        const snackBar = inject(MatSnackBar);
+        
+        return {
+          defaultErrorHandling: (error) => {
+            const message = error?.message || 'An error occurred';
+            snackBar.open(message, 'Close', {
+              duration: 5000,
+              panelClass: ['error-snackbar']
+            });
+          },
+          useDefaultErrorHandler: true,
+          defaultSuccessHandling: () => {
+            snackBar.open('Operation completed successfully', 'Close', {
+              duration: 3000,
+              panelClass: ['success-snackbar']
+            });
+          }
+        };
+      }
+    }
+  ]
+};
+```
+
+### Integration with Error Tracking Service
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useFactory: () => {
+        const errorTracker = inject(ErrorTrackingService);
+        const logger = inject(LoggerService);
+        
+        return {
+          defaultErrorHandling: (error) => {
+            // Log to console
+            console.error('API Error:', error);
+            
+            // Track in analytics/monitoring service
+            errorTracker.captureException(error, {
+              context: 'HTTP Request',
+              level: 'error'
+            });
+            
+            // Log to logging service
+            logger.error('Request failed', { error });
+          },
+          useDefaultErrorHandler: true
+        };
+      }
+    }
+  ]
+};
+```
+
+### Conditional Error Handling
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+import { HttpErrorResponse } from '@angular/common/http';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useFactory: () => {
+        const router = inject(Router);
+        const notificationService = inject(NotificationService);
+        
+        return {
+          defaultErrorHandling: (error: HttpErrorResponse) => {
+            // Handle different error types
+            if (error.status === 401) {
+              // Unauthorized - redirect to login
+              router.navigate(['/login']);
+              notificationService.warn('Your session has expired. Please log in again.');
+            } else if (error.status === 403) {
+              // Forbidden
+              notificationService.error('You do not have permission to perform this action.');
+            } else if (error.status === 404) {
+              // Not found
+              notificationService.warn('The requested resource was not found.');
+            } else if (error.status >= 500) {
+              // Server error
+              notificationService.error('A server error occurred. Please try again later.');
+            } else {
+              // Other errors
+              notificationService.error(error.message || 'An unexpected error occurred.');
+            }
+          },
+          useDefaultErrorHandler: true
+        };
+      }
+    }
+  ]
+};
+```
+
+### Success Notifications
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { RequestStateStoreConfigToken } from 'angular-utilities';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    {
+      provide: RequestStateStoreConfigToken,
+      useFactory: () => {
+        const toastService = inject(ToastService);
+        
+        return {
+          defaultSuccessHandling: () => {
+            toastService.success('Operation completed successfully!');
+          }
+        };
+      }
+    }
+  ]
+};
+```
+
+Then use it in requestors:
+
+```typescript
+const saveRequestor = createRequestor(
+  (data: FormData) => this.http.post('/api/save', data)
+).useDefaultSuccessHandler();
+// Will show "Operation completed successfully!" toast on success
+```
+
+## Requestor-level Control
+
+Even with global configuration, individual requestors have full control over error handling behavior.
+
+### Explicit Error Handler (Overrides Global)
+
+```typescript
+const requestor = createRequestor(
+  (id: number) => this.http.get<User>(`/api/users/${id}`)
+).onError((error) => {
+  // This explicit handler prevents the global handler from running
+  console.log('Custom error handling');
+});
+```
+
+### Opt-in to Global Error Handler
+
+```typescript
+const requestor = createRequestor(
+  (id: number) => this.http.get<User>(`/api/users/${id}`)
+).useDefaultErrorHandler();
+// Explicitly uses the global error handler
+```
+
+### Opt-in to Global Success Handler
+
+```typescript
+const requestor = createRequestor(
+  (id: number) => this.http.delete(`/api/users/${id}`)
+).useDefaultSuccessHandler();
+// Explicitly uses the global success handler
+```
+
+### Combine Global and Custom Handlers
+
+```typescript
+const requestor = createRequestor(
+  (id: number) => this.http.get<User>(`/api/users/${id}`)
+)
+.useDefaultErrorHandler()  // Use global error handler
+.onSuccess((user) => {      // Add custom success handler
+  console.log('User loaded:', user.name);
+});
+```
+
+## Error Handler Priority
+
+The error handling priority is as follows:
+
+1. **Explicit error handlers** (`onError`, `onErrorResponse`, `onErrorRequest`, `onErrorWithRequest`) - Highest priority
+2. **Default error handler** (if `useDefaultErrorHandler: true` and no explicit handler) - Medium priority
+3. **No handling** - If neither explicit nor automatic default handling is configured
+
+```typescript
+// Scenario 1: Explicit handler (highest priority)
+createRequestor(...)
+  .onError((error) => { /* This runs */ });
+// Global handler does NOT run (explicit handler registered)
+
+// Scenario 2: Automatic default (useDefaultErrorHandler: true)
+// Config: { useDefaultErrorHandler: true, defaultErrorHandling: ... }
+createRequestor(...);
+// Global defaultErrorHandling runs automatically
+
+// Scenario 3: Explicit opt-in
+// Config: { useDefaultErrorHandler: false, defaultErrorHandling: ... }
+createRequestor(...)
+  .useDefaultErrorHandler();
+// Global defaultErrorHandling runs because explicitly opted-in
+
+// Scenario 4: No handling
+// Config: { useDefaultErrorHandler: false }
+createRequestor(...);
+// No error handling occurs (errors are silent)
+```
+
+## Best Practices
+
+### 1. Always Provide Global Error Handling
+
+Set up a global error handler to catch unexpected errors and prevent silent failures:
+
+```typescript
+{
+  provide: RequestStateStoreConfigToken,
+  useValue: {
+    defaultErrorHandling: (error) => {
+      console.error('Unhandled request error:', error);
+      // Log to monitoring service
+    },
+    useDefaultErrorHandler: true
+  }
+}
+```
+
+### 2. Use Different Handlers for Different Environments
+
+```typescript
+import { environment } from './environments/environment';
+
+{
+  provide: RequestStateStoreConfigToken,
+  useValue: {
+    defaultErrorHandling: (error) => {
+      if (environment.production) {
+        // Production: Send to monitoring service
+        errorTrackingService.captureException(error);
+      } else {
+        // Development: Detailed console logging
+        console.error('Development Error:', error);
+        console.table(error);
+      }
+    },
+    useDefaultErrorHandler: true
+  }
+}
+```
+
+### 3. Provide User-Friendly Error Messages
+
+Transform technical errors into user-friendly messages:
+
+```typescript
+{
+  provide: RequestStateStoreConfigToken,
+  useFactory: () => {
+    const translate = inject(TranslateService);
+    const snackBar = inject(MatSnackBar);
+    
+    return {
+      defaultErrorHandling: (error: HttpErrorResponse) => {
+        let message: string;
+        
+        if (!navigator.onLine) {
+          message = translate.instant('errors.offline');
+        } else if (error.status === 0) {
+          message = translate.instant('errors.network');
+        } else {
+          message = translate.instant('errors.generic');
+        }
+        
+        snackBar.open(message, 'OK', { duration: 5000 });
+      },
+      useDefaultErrorHandler: true
+    };
+  }
+}
+```
+
+### 4. Combine Global and Specific Handlers
+
+Use global handlers for common scenarios and specific handlers for special cases:
+
+```typescript
+// Global handler catches most errors
+// Config provides general error handling
+
+// Specific handlers for special cases
+const deleteUserRequestor = createRequestor(
+  (id: number) => this.http.delete(`/api/users/${id}`)
+)
+.onError((error) => {
+  if (error.status === 409) {
+    // Special handling for conflict errors
+    this.showConflictDialog();
+  } else {
+    // Let global handler take care of other errors
+    this.useDefaultErrorHandler();
+  }
+});
+```
+
+### 5. Opt-out for Silent Operations
+
+Some operations should fail silently without user notification:
+
+```typescript
+// Prefetch request - don't show errors to users
+const prefetchRequestor = createRequestor(
+  () => this.http.get('/api/prefetch-data')
+);
+// No error handler - fails silently even with useDefaultErrorHandler: true
+// (because when an explicit handler is not set and useDefaultErrorHandler is true,
+// the global handler runs - to truly silence, you'd need to add an empty handler)
+
+// To truly silence:
+const prefetchRequestor = createRequestor(
+  () => this.http.get('/api/prefetch-data')
+).onError(() => { /* Silent */ });
+```
+
+### 6. Log All Errors for Debugging
+
+Even if you don't show all errors to users, always log them:
+
+```typescript
+{
+  provide: RequestStateStoreConfigToken,
+  useFactory: () => {
+    const logger = inject(LoggerService);
+    const notificationService = inject(NotificationService);
+    
+    return {
+      defaultErrorHandling: (error) => {
+        // Always log for debugging
+        logger.error('Request failed', { error });
+        
+        // Only show to user for certain error types
+        if (error.status >= 400 && error.status < 500) {
+          notificationService.error('Please check your input and try again.');
+        }
+      },
+      useDefaultErrorHandler: true
+    };
+  }
+}
+```
+
+## Testing with Configuration
+
+### Mocking Configuration in Tests
+
+```typescript
+describe('UserComponent', () => {
+  let component: UserComponent;
+  let errorHandler: jasmine.Spy;
+  
+  beforeEach(() => {
+    errorHandler = jasmine.createSpy('errorHandler');
+    
+    TestBed.configureTestingModule({
+      declarations: [UserComponent],
+      imports: [HttpClientTestingModule],
+      providers: [
+        {
+          provide: RequestStateStoreConfigToken,
+          useValue: {
+            defaultErrorHandling: errorHandler,
+            useDefaultErrorHandler: true
+          }
+        }
+      ]
+    });
+    
+    component = TestBed.createComponent(UserComponent).componentInstance;
+  });
+  
+  it('should call global error handler on failure', () => {
+    const httpMock = TestBed.inject(HttpTestingController);
+    
+    component.userRequestor.request(1);
+    
+    const req = httpMock.expectOne('/api/users/1');
+    req.error(new ProgressEvent('error'), { status: 500 });
+    
+    expect(errorHandler).toHaveBeenCalled();
+  });
+});
+```
+
+### Testing Without Configuration
+
+```typescript
+beforeEach(() => {
+  TestBed.configureTestingModule({
+    declarations: [UserComponent],
+    imports: [HttpClientTestingModule]
+    // No RequestStateStoreConfigToken provided
+  });
+});
+
+// Configuration is optional - tests work fine without it
+```
+
+## Migration Guide
+
+### Adding Configuration to Existing Application
+
+If you're adding `RequestStateStoreConfig` to an application that already has requestors:
+
+1. **Add configuration gradually:**
+
+```typescript
+// Start with useDefaultErrorHandler: false
+{
+  provide: RequestStateStoreConfigToken,
+  useValue: {
+    defaultErrorHandling: (error) => {
+      console.warn('Unhandled error:', error);
+    },
+    useDefaultErrorHandler: false  // Start with false
+  }
+}
+```
+
+2. **Identify requestors without error handlers:**
+
+Look for requestors that don't have `.onError()` calls.
+
+3. **Test the global handler:**
+
+Temporarily add `.useDefaultErrorHandler()` to a few requestors to test.
+
+4. **Enable globally when ready:**
+
+```typescript
+useDefaultErrorHandler: true  // Enable for all
+```
+
+## See Also
+
+- [Requestor Documentation](./REQUESTOR.md)
+- [Error Handling Patterns](./REQUESTOR.md#error-handling)
+- [Success Handling Patterns](./REQUESTOR.md#success-handling)
+- [createRequestor Function](./CREATE-REQUESTOR.md)