@arela/uploader 0.2.4 → 0.2.6

package/src/errors/ErrorHandler.js

@@ -0,0 +1,278 @@
+import {
+  ApiError,
+  ArelaError,
+  ConfigurationError,
+  DatabaseError,
+  DetectionError,
+  FileOperationError,
+  NetworkError,
+  UploadServiceError,
+  ValidationError,
+} from './ErrorTypes.js';
+
+/**
+ * Error Handler Service
+ * Provides centralized error handling, logging, and user-friendly error messages
+ */
+export class ErrorHandler {
+  constructor(logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * Handle and format error for user display
+   * @param {Error} error - The error to handle
+   * @param {Object} context - Additional context about where the error occurred
+   * @returns {Object} Formatted error information
+   */
+  handleError(error, context = {}) {
+    const errorInfo = this.#analyzeError(error, context);
+
+    // Log the error with appropriate level
+    this.#logError(errorInfo);
+
+    return errorInfo;
+  }
+
+  /**
+   * Handle fatal errors that should terminate the application
+   * @param {Error} error - The fatal error
+   * @param {Object} context - Additional context
+   */
+  handleFatalError(error, context = {}) {
+    const errorInfo = this.handleError(error, context);
+
+    console.error('\n❌ Fatal Error - Application will exit');
+    console.error(`   ${errorInfo.userMessage}`);
+
+    if (this.logger.isVerboseEnabled() && errorInfo.technicalDetails) {
+      console.error(`   Technical Details: ${errorInfo.technicalDetails}`);
+    }
+
+    this.logger.flush();
+    process.exit(1);
+  }
+
+  /**
+   * Create a user-friendly error from a technical error
+   * @param {string} userMessage - User-friendly error message
+   * @param {Error} originalError - The original technical error
+   * @param {string} code - Error code
+   * @returns {ArelaError} User-friendly error
+   */
+  createUserFriendlyError(userMessage, originalError, code = 'USER_ERROR') {
+    const error = new ArelaError(userMessage, code, {
+      originalError: originalError.message,
+      originalStack: originalError.stack,
+    });
+
+    return error;
+  }
+
+  /**
+   * Analyze error and determine appropriate handling
+   * @private
+   * @param {Error} error - Error to analyze
+   * @param {Object} context - Error context
+   * @returns {Object} Error analysis result
+   */
+  #analyzeError(error, context) {
+    const analysis = {
+      type: error.constructor.name,
+      code: error.code || 'UNKNOWN_ERROR',
+      message: error.message,
+      userMessage: this.#getUserFriendlyMessage(error),
+      technicalDetails: error.details || null,
+      context,
+      timestamp: error.timestamp || new Date().toISOString(),
+      severity: this.#determineSeverity(error),
+      recoverable: this.#isRecoverable(error),
+      stack: error.stack,
+    };
+
+    return analysis;
+  }
+
+  /**
+   * Generate user-friendly error message
+   * @private
+   * @param {Error} error - Error to process
+   * @returns {string} User-friendly message
+   */
+  #getUserFriendlyMessage(error) {
+    if (error instanceof ConfigurationError) {
+      return `Configuration issue: ${error.message}`;
+    }
+
+    if (error instanceof FileOperationError) {
+      const filePath = error.details?.filePath;
+      return `File operation failed${filePath ? ` for ${filePath}` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof UploadServiceError) {
+      const serviceName = error.details?.serviceName;
+      return `Upload failed${serviceName ? ` (${serviceName})` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof ApiError) {
+      const statusCode = error.details?.statusCode;
+      return `API request failed${statusCode ? ` (HTTP ${statusCode})` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof DatabaseError) {
+      const operation = error.details?.operation;
+      return `Database operation failed${operation ? ` (${operation})` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof DetectionError) {
+      const filePath = error.details?.filePath;
+      return `File detection failed${filePath ? ` for ${filePath}` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof ValidationError) {
+      const field = error.details?.field;
+      return `Validation failed${field ? ` for ${field}` : ''}: ${error.message}`;
+    }
+
+    if (error instanceof NetworkError) {
+      return `Network error: ${error.message}`;
+    }
+
+    if (error instanceof ArelaError) {
+      return error.message;
+    }
+
+    // Generic error handling
+    return `An unexpected error occurred: ${error.message}`;
+  }
+
+  /**
+   * Determine error severity
+   * @private
+   * @param {Error} error - Error to analyze
+   * @returns {string} Severity level
+   */
+  #determineSeverity(error) {
+    if (error instanceof ConfigurationError) {
+      return 'fatal';
+    }
+
+    if (error instanceof NetworkError || error instanceof ApiError) {
+      return 'high';
+    }
+
+    if (error instanceof DatabaseError || error instanceof UploadServiceError) {
+      return 'high';
+    }
+
+    if (
+      error instanceof FileOperationError ||
+      error instanceof DetectionError
+    ) {
+      return 'medium';
+    }
+
+    if (error instanceof ValidationError) {
+      return 'low';
+    }
+
+    return 'medium';
+  }
+
+  /**
+   * Determine if error is recoverable
+   * @private
+   * @param {Error} error - Error to analyze
+   * @returns {boolean} True if recoverable
+   */
+  #isRecoverable(error) {
+    if (error instanceof ConfigurationError) {
+      return false;
+    }
+
+    if (error instanceof NetworkError || error instanceof ApiError) {
+      // Network errors might be temporary
+      return true;
+    }
+
+    if (error instanceof FileOperationError) {
+      // File errors might be recoverable depending on the specific error
+      return true;
+    }
+
+    if (error instanceof DetectionError || error instanceof ValidationError) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Log error with appropriate level
+   * @private
+   * @param {Object} errorInfo - Error analysis result
+   */
+  #logError(errorInfo) {
+    const logMessage = `${errorInfo.type}: ${errorInfo.message}`;
+    const contextInfo = errorInfo.context
+      ? ` | Context: ${JSON.stringify(errorInfo.context)}`
+      : '';
+    const detailsInfo = errorInfo.technicalDetails
+      ? ` | Details: ${JSON.stringify(errorInfo.technicalDetails)}`
+      : '';
+
+    const fullLogMessage = `${logMessage}${contextInfo}${detailsInfo}`;
+
+    switch (errorInfo.severity) {
+      case 'fatal':
+        this.logger.error(`FATAL: ${fullLogMessage}`);
+        break;
+      case 'high':
+        this.logger.error(`HIGH: ${fullLogMessage}`);
+        break;
+      case 'medium':
+        this.logger.warn(`MEDIUM: ${fullLogMessage}`);
+        break;
+      case 'low':
+        this.logger.info(`LOW: ${fullLogMessage}`);
+        break;
+      default:
+        this.logger.error(fullLogMessage);
+    }
+
+    // Log stack trace in verbose mode
+    if (this.logger.isVerboseEnabled() && errorInfo.stack) {
+      this.logger.debug(`Stack trace: ${errorInfo.stack}`);
+    }
+  }
+
+  /**
+   * Wrap a function with error handling
+   * @param {Function} fn - Function to wrap
+   * @param {Object} context - Context for error handling
+   * @returns {Function} Wrapped function
+   */
+  wrapWithErrorHandling(fn, context = {}) {
+    return async (...args) => {
+      try {
+        return await fn(...args);
+      } catch (error) {
+        this.handleError(error, context);
+        throw error;
+      }
+    };
+  }
+
+  /**
+   * Create error handler middleware for async operations
+   * @param {Object} context - Context for error handling
+   * @returns {Function} Error handler middleware
+   */
+  createAsyncErrorHandler(context = {}) {
+    return (error) => {
+      this.handleError(error, context);
+    };
+  }
+}
+
+export default ErrorHandler;

package/src/errors/ErrorTypes.js

@@ -0,0 +1,104 @@
+/**
+ * Custom Error Types for Arela Uploader
+ */
+
+/**
+ * Base error class for Arela Uploader
+ */
+export class ArelaError extends Error {
+  constructor(message, code = 'ARELA_ERROR', details = null) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+
+    // Ensure proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Configuration related errors
+ */
+export class ConfigurationError extends ArelaError {
+  constructor(message, details = null) {
+    super(message, 'CONFIGURATION_ERROR', details);
+  }
+}
+
+/**
+ * File operation related errors
+ */
+export class FileOperationError extends ArelaError {
+  constructor(message, filePath = null, details = null) {
+    super(message, 'FILE_OPERATION_ERROR', { filePath, ...details });
+  }
+}
+
+/**
+ * Upload service related errors
+ */
+export class UploadServiceError extends ArelaError {
+  constructor(message, serviceName = null, details = null) {
+    super(message, 'UPLOAD_SERVICE_ERROR', { serviceName, ...details });
+  }
+}
+
+/**
+ * API related errors
+ */
+export class ApiError extends ArelaError {
+  constructor(message, statusCode = null, response = null, details = null) {
+    super(message, 'API_ERROR', { statusCode, response, ...details });
+  }
+}
+
+/**
+ * Database operation related errors
+ */
+export class DatabaseError extends ArelaError {
+  constructor(message, operation = null, details = null) {
+    super(message, 'DATABASE_ERROR', { operation, ...details });
+  }
+}
+
+/**
+ * File detection related errors
+ */
+export class DetectionError extends ArelaError {
+  constructor(message, filePath = null, details = null) {
+    super(message, 'DETECTION_ERROR', { filePath, ...details });
+  }
+}
+
+/**
+ * Validation related errors
+ */
+export class ValidationError extends ArelaError {
+  constructor(message, field = null, value = null, details = null) {
+    super(message, 'VALIDATION_ERROR', { field, value, ...details });
+  }
+}
+
+/**
+ * Network related errors
+ */
+export class NetworkError extends ArelaError {
+  constructor(message, url = null, details = null) {
+    super(message, 'NETWORK_ERROR', { url, ...details });
+  }
+}