Error Handling & Logging
Relevant source files
The following files were used as context for generating this wiki page:
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.
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.
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.
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.
// Example usage from context
export const withErrorHandling = <T extends any[], R>(
fn: (...args: T) => Promise<R>,
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.
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.