Error Handler Package

A robust error handling system with i18n support for frontend applications. This package provides centralized error handling, translation capabilities, and multiple error handling strategies.

Features

• 🎯 Centralized Error Handling: Single service to manage all errors across your application
• 🌍 i18n Support: Built-in error translation capabilities
• 🔄 Multiple Strategies: Toast notifications, console logging, silent handling, and translation-only
• 🎨 Framework Agnostic: Works with any frontend framework
• 🎭 Vue.js Integration: Special Vue composition API support
• 📦 TypeScript: Full TypeScript support with type definitions
• 🚀 Lightweight: Minimal dependencies, tree-shakeable

Installation

npm install @amirkhodam/error-handler
# or
yarn add @amirkhodam/error-handler

Quick Start

Basic Usage

import { errorHandler } from '@amirkhodam/error-handler'

// Handle an error with toast notification
errorHandler.handleError(error, {
  strategy: 'toast',
  severity: 'error',
  summary: 'Error Title',
  detail: 'Error details'
})

// Handle an error silently
errorHandler.handleError(error, {
  strategy: 'silent'
})

// Log error to console
errorHandler.handleError(error, {
  strategy: 'console'
})

Vue.js Usage

import { useErrorHandler } from '@amirkhodam/error-handler/vue'

export default {
  setup() {
    const { handleError, handleApiError, handleValidationError } = useErrorHandler()

    const someFunction = async () => {
      try {
        // Your code here
      } catch (error) {
        handleApiError(error, {
          summary: 'API Error',
          severity: 'error'
        })
      }
    }

    return {
      someFunction
    }
  }
}

Error Handling Strategies

1. Toast Strategy

Display errors as toast notifications to users.

errorHandler.handleError(error, {
  strategy: 'toast',
  severity: 'error', // 'error' | 'warn' | 'info' | 'success'
  summary: 'Error Title',
  detail: 'Error details',
  life: 5000, // Duration in milliseconds
  closable: true,
  group: 'api-errors'
})

2. Console Strategy

Log errors to the browser console for debugging.

errorHandler.handleError(error, {
  strategy: 'console'
})

3. Silent Strategy

Handle errors without any user feedback or logging.

errorHandler.handleError(error, {
  strategy: 'silent'
})

4. Translate Strategy

Return translated error messages for custom handling.

const translatedError = errorHandler.handleError(error, {
  strategy: 'translate',
  prefix: 'api',
  default: 'An error occurred'
})
// Returns: { message, status, error, translate, errorObject }

Vue Composition API

The package provides a Vue composition API hook with convenient methods:

import { useErrorHandler } from '@amirkhodam/error-handler/vue'

const {
  handleError,           // General error handler
  handleApiError,        // API-specific error handler
  handleValidationError, // Validation error handler
  handleSilentError,     // Silent error handler
  handleDebugError,      // Console debug handler
  handleTranslateError   // Translation-only handler
} = useErrorHandler()

Predefined Error Handlers

API Error Handler

handleApiError(error, {
  strategy: 'toast',
  severity: 'error',
  summary: 'Service Error',
  life: 5000
})

Validation Error Handler

handleValidationError(error, {
  summary: 'Please check your input'
})

Error Translation

The package includes built-in error translation capabilities:

import { translator } from '@amirkhodam/error-handler'

const translatedError = translator.translateError(error, {
  prefix: 'api',
  default: 'An error occurred'
})

Event Bus Integration

The package includes a simple event bus for toast notifications:

import { useEventBus } from '@amirkhodam/error-handler'

const eventBus = useEventBus()

// Listen for toast events
eventBus.on('toast.add', (toastData) => {
  // Handle toast notification
  console.log('Toast:', toastData)
})

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  ErrorHandlingOptions, 
  IErrorTranslate, 
  ErrorHandlingStrategy 
} from '@amirkhodam/error-handler'

const options: ErrorHandlingOptions = {
  strategy: 'toast',
  severity: 'error',
  summary: 'Error'
}

Configuration

Custom Event Bus

You can provide your own event bus implementation:

import { EventBus } from '@amirkhodam/error-handler'

// Create custom event bus
const customEventBus = new EventBus()

// Use in your application
customEventBus.emit('toast.add', toastData)

Custom Error Translation

Extend the translation service for your needs:

import { ErrorTranslator } from '@amirkhodam/error-handler'

class CustomTranslator extends ErrorTranslator {
  translateError(error: any, options: ErrorHandlingOptions): IErrorTranslate {
    // Custom translation logic
    return super.translateError(error, options)
  }
}

API Reference

ErrorHandlingService

handleError<T>(error: any, options: ErrorHandlingOptions & { strategy: T }): ErrorTranslateReturn<T>

Main method to handle errors with specified strategy.

useErrorHandler (Vue)

handleError(error: any, options: ErrorHandlingOptions)

General error handler.

handleApiError(error: any, options?: Partial<ErrorHandlingOptions>)

API-specific error handler with default settings.

handleValidationError(error: any, options?: Partial<ErrorHandlingOptions>)

Validation error handler with warning severity.

handleSilentError(error: any)

Silent error handler.

handleDebugError(error: any)

Console debug error handler.

handleTranslateError(error: any, options?: Partial<ErrorHandlingOptions>)

Translation-only error handler.

Error Handling Options

interface ErrorHandlingOptions {
  strategy: 'toast' | 'console' | 'silent' | 'translate'
  severity?: 'error' | 'warn' | 'info' | 'success'
  summary?: string
  detail?: string
  life?: number
  closable?: boolean
  group?: string
  prefix?: string
  default?: string
  inline?: boolean
}

Error Response Structure

interface IErrorTranslate {
  message: string
  status: number
  error: string
  translate: string
  errorObject: any
}

Development

Building

npm run build

Development Mode

npm run dev

Testing

npm test

Linting

npm run lint

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For support and questions, please open an issue on GitHub.