Relevant source files

The following files were used as context for generating this wiki page: - [utils/errorHandler.ts](https://github.com/RogerDevAndroid/elmecV2-Demo/blob/main/utils/errorHandler.ts) - [utils/logger.ts](https://github.com/RogerDevAndroid/elmecV2-Demo/blob/main/utils/logger.ts) - [README.md](https://github.com/RogerDevAndroid/elmecV2-Demo/blob/main/README.md) - [FIXES-APLICADOS.md](https://github.com/RogerDevAndroid/elmecV2-Demo/blob/main/FIXES-APLICADOS.md) - [TEST_REPORT.md](https://github.com/RogerDevAndroid/elmecV2-Demo/blob/main/TEST_REPORT.md)

# Error Handling & Logging The Error Handling and Logging system in ElmecV2 provides a robust framework for capturing, categorizing, and reporting application failures and events. Its primary purpose is to ensure application stability by providing user-friendly feedback while simultaneously collecting detailed technical data for developers to troubleshoot issues across production and development environments. The system is designed with an "Offline First" philosophy, utilizing local queues to store logs and errors when connectivity is unavailable. It integrates deeply with backend services like Supabase, mapping database-specific errors to standardized application error types. Sources: [README.md:25](), [utils/errorHandler.ts:182-205](). ## System Architecture The architecture consists of two primary utility classes: `ErrorHandler` and `Logger`. While they serve distinct purposes, they are tightly integrated. the `Logger` can consume `AppError` objects generated by the `ErrorHandler` to ensure that every significant application failure is recorded with full context. Sources: [utils/logger.ts:168-175](). ### Core Components | Component | Description | |-----------|-------------| | **ErrorHandler** | Centralized class for catching, parsing, and transforming raw errors into structured `AppError` objects. | | **Logger** | Handles the distribution of log messages to the console, local memory, or remote endpoints based on severity. | | **withErrorHandling** | A Higher-Order Function (HOF) used to wrap asynchronous operations with automatic error catching and reporting. | | **Error Queue** | A local buffer that stores the last 100 error entries to prevent data loss during network instability. | Sources: [utils/errorHandler.ts:36](), [utils/errorHandler.ts:241-248](), [utils/logger.ts:30](). ### Error Classification Errors are categorized by severity and type to determine the appropriate response, such as showing an alert to the user or sending a silent report to a remote server. ```mermaid classDiagram class ErrorSeverity { <> LOW MEDIUM HIGH CRITICAL } class ErrorCategory { <> AUTH NETWORK DATABASE VALIDATION PERMISSION UNKNOWN } class AppError { +string code +string message +ErrorCategory category +ErrorSeverity severity +string timestamp +string userMessage +boolean retryable } AppError --> ErrorSeverity AppError --> ErrorCategory ``` Sources: [utils/errorHandler.ts:4-23](). ## Error Handling Logic The `ErrorHandler` class features specialized handlers for different error domains, specifically targeting Supabase (database), Authentication, and Network issues. Sources: [utils/errorHandler.ts:41-155](). ### Database Error Mapping The system maps specific PostgreSQL/Supabase error codes to internal application codes to provide better context. | Supabase Code | App Code | Severity | Description | |---------------|----------|----------|-------------| | `42P17` | `RLS_RECURSION` | CRITICAL | Security configuration error. | | `PGRST116` | `NOT_FOUND` | LOW | Requested resource does not exist. | | `23505` | `DUPLICATE_KEY` | MEDIUM | Unique constraint violation. | | `23503` | `FOREIGN_KEY_VIOLATION` | HIGH | Data integrity/reference error. | Sources: [utils/errorHandler.ts:45-86](). ### Flow of an Error When an error occurs within a wrapped function, it follows a structured path from detection to user notification and logging. ```mermaid flowchart TD A[Async Function Call] --> B{Error Occurs?} B -- No --> C[Return Result] B -- Yes --> D[withErrorHandling Catch] D --> E[Identify Error Type] E --> F[Generate AppError] F --> G[Log to Local Queue] G --> H{Production?} H -- Yes --> I[Send to Remote Service] H -- No --> J[Console Error] I --> K[Show User Alert] J --> K ``` Sources: [utils/errorHandler.ts:241-285](). ## Logging System The `Logger` class manages application telemetry, including debug information, user actions, and performance metrics. It uses a session-based ID to group logs within a single execution period. Sources: [utils/logger.ts:34-45](). ### Logging Levels The logger supports multiple levels, with a configurable threshold typically set via environment variables. * **DEBUG**: Detailed information for development. * **INFO**: Standard highlights (API calls, user actions). * **WARN**: Potentially harmful situations. * **ERROR**: Error events that might still allow the app to continue. * **FATAL**: Severe error events that will presumably lead the application to abort. Sources: [utils/logger.ts:16-24](). ### Remote Logging Integration In production environments, the logger is configured to send logs of level `ERROR` or higher to a remote endpoint via the `sendToRemote` method. ```mermaid sequenceDiagram participant App as Application Logic participant Log as Logger Class participant Cons as Console participant Rem as Remote Endpoint App->>Log: log(level, message, data) Log->>Log: Add to local logs array alt enableConsoleLogging is true Log->>Cons: console.log(...) end alt level >= LogLevel.ERROR AND enableRemoteLogging Log->>Rem: POST logEntry to remoteEndpoint end ``` Sources: [utils/logger.ts:68-100](). ## Technical Implementation Details ### Higher-Order Error Handling The `withErrorHandling` utility is the standard way to implement safety in service calls. It allows developers to define a `fallbackValue` to ensure the application state remains valid even after a failure. Sources: [utils/errorHandler.ts:241-288](). ```typescript // Example usage from context export const withErrorHandling = ( fn: (...args: T) => Promise, context?: string, options?: { showUserError?: boolean; fallbackValue?: R; } ) => { ... }; ``` Sources: [utils/errorHandler.ts:241-246](). ### Monitoring and Statistics Both systems provide methods to retrieve health statistics, allowing for "Health Check" components or admin dashboards to monitor application state. Sources: [utils/logger.ts:145-166](), [utils/errorHandler.ts:213-239](). ```mermaid graph TD subgraph Stats_Collection A[getErrorStats] --> B[Total Errors] A --> C[Severity Distribution] A --> D[Category Breakdown] E[getLogStats] --> F[Total Logs] E --> G[Last 24 Hours count] end ``` Sources: [utils/errorHandler.ts:222-237](), [utils/logger.ts:151-163](). ## Conclusion The Error Handling & Logging system in ElmecV2 provides a comprehensive safety net. By transforming technical exceptions into structured `AppError` objects and maintaining a robust `Logger`, the project ensures that developers have the necessary data to resolve production issues while maintaining a professional and helpful interface for the end-user. The inclusion of offline queuing and severity-based remote reporting makes it a production-ready solution for mobile environments. Sources: [README.md:126-131](), [FIXES-APLICADOS.md:235-245](), [TEST_REPORT.md:273-285]().