@eyjs/shared-errors

Shared error codes and messages for the EyJS framework. Provides standardized error handling across all EyJS packages and applications.

Features

• 🎯 Standardized Error Codes - Consistent error codes across the entire framework
• 📝 Default Error Messages - Pre-defined error messages for common scenarios
• 🔧 TypeScript Support - Full TypeScript definitions and type safety
• 🚀 Zero Dependencies - Lightweight package with no external dependencies
• 📦 Framework Agnostic - Can be used independently or with EyJS

Installation

# Using Bun (recommended)
bun add @eyjs/shared-errors

# Using npm
npm install @eyjs/shared-errors

# Using yarn
yarn add @eyjs/shared-errors

# Using pnpm
pnpm add @eyjs/shared-errors

Quick Start

import { ErrorCodes, DefaultErrorMessages } from '@eyjs/shared-errors'

// Throw standardized errors
throw new Error(ErrorCodes.USER_NOT_FOUND)

// Get default error message
const message = DefaultErrorMessages[ErrorCodes.USER_NOT_FOUND]
console.log(message) // "User not found"

// Use in error handling
try {
  // Some operation
} catch (error) {
  if (error.message === ErrorCodes.AUTH_MISSING) {
    // Handle authentication error
  }
}

API Reference

ErrorCodes

A collection of standardized error codes:

enum ErrorCodes {
  AUTH_MISSING = 'AUTH_MISSING',
  AUTH_INVALID = 'AUTH_INVALID',
  TOKEN_EXPIRED = 'TOKEN_EXPIRED',
  USER_NOT_FOUND = 'USER_NOT_FOUND',
  USER_ALREADY_EXISTS = 'USER_ALREADY_EXISTS',
  VALIDATION_FAILED = 'VALIDATION_FAILED',
  PAYLOAD_MALFORMED = 'PAYLOAD_MALFORMED',
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  RESOURCE_NOT_FOUND = 'RESOURCE_NOT_FOUND',
  SERVER_ERROR = 'SERVER_ERROR',
  UNKNOWN = 'UNKNOWN'
}

DefaultErrorMessages

Pre-defined error messages for each error code:

const DefaultErrorMessages = {
  [ErrorCodes.AUTH_MISSING]: 'Authentication required',
  [ErrorCodes.AUTH_INVALID]: 'Invalid authentication token',
  [ErrorCodes.TOKEN_EXPIRED]: 'Session expired',
  [ErrorCodes.USER_NOT_FOUND]: 'User not found',
  [ErrorCodes.USER_ALREADY_EXISTS]: 'User already exists',
  [ErrorCodes.VALIDATION_FAILED]: 'Validation failed',
  [ErrorCodes.PAYLOAD_MALFORMED]: 'Malformed data',
  [ErrorCodes.PERMISSION_DENIED]: 'Access denied',
  [ErrorCodes.RESOURCE_NOT_FOUND]: 'Resource not found',
  [ErrorCodes.SERVER_ERROR]: 'Server error',
  [ErrorCodes.UNKNOWN]: 'Unknown error'
}

Available Error Codes

| Code | Description | Use Case | |------|-------------|----------| | AUTH_MISSING | Authentication required | When user tries to access protected resource without auth | | AUTH_INVALID | Invalid authentication token | When token is malformed or invalid | | TOKEN_EXPIRED | Session expired | When JWT token has expired | | USER_NOT_FOUND | User not found | When user ID doesn't exist in database | | USER_ALREADY_EXISTS | User already exists | When trying to create duplicate user | | VALIDATION_FAILED | Validation failed | When input data doesn't pass validation | | PAYLOAD_MALFORMED | Malformed data | When request body is invalid JSON | | PERMISSION_DENIED | Access denied | When user lacks required permissions | | RESOURCE_NOT_FOUND | Resource not found | When requested resource doesn't exist | | SERVER_ERROR | Server error | For unexpected server-side errors | | UNKNOWN | Unknown error | For unhandled or unexpected errors |

Usage Examples

Basic Error Handling

import { ErrorCodes, DefaultErrorMessages } from '@eyjs/shared-errors'

function findUser(userId: string) {
  const user = database.findUser(userId)
  
  if (!user) {
    throw new Error(ErrorCodes.USER_NOT_FOUND)
  }
  
  return user
}

// Error handling
try {
  const user = findUser('123')
} catch (error) {
  if (error.message === ErrorCodes.USER_NOT_FOUND) {
    return { 
      error: ErrorCodes.USER_NOT_FOUND,
      message: DefaultErrorMessages[ErrorCodes.USER_NOT_FOUND]
    }
  }
}

Custom Error Class

import { ErrorCodes, DefaultErrorMessages } from '@eyjs/shared-errors'

class EyJsError extends Error {
  constructor(public code: ErrorCodes, customMessage?: string) {
    super(customMessage || DefaultErrorMessages[code])
    this.name = 'EyJsError'
  }
}

// Usage
throw new EyJsError(ErrorCodes.VALIDATION_FAILED, 'Email format is invalid')

API Response Format

import { ErrorCodes, DefaultErrorMessages } from '@eyjs/shared-errors'

function handleError(error: Error) {
  const errorCode = Object.values(ErrorCodes).includes(error.message as ErrorCodes) 
    ? error.message as ErrorCodes 
    : ErrorCodes.UNKNOWN

  return {
    success: false,
    error: {
      code: errorCode,
      message: DefaultErrorMessages[errorCode],
      timestamp: new Date().toISOString()
    }
  }
}

Integration with EyJS

This package is designed to work seamlessly with other EyJS packages:

// In @eyjs/auth
import { ErrorCodes } from '@eyjs/shared-errors'

if (!token) {
  throw new Error(ErrorCodes.AUTH_MISSING)
}

// In @eyjs/http-server
import { ErrorCodes, DefaultErrorMessages } from '@eyjs/shared-errors'

app.onError((error) => {
  return {
    error: ErrorCodes.SERVER_ERROR,
    message: DefaultErrorMessages[ErrorCodes.SERVER_ERROR]
  }
})

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions