🚨 Elysia HTTP Exception

A comprehensive Elysia plugin for handling HTTP 4xx and 5xx errors with structured exception classes and automatic error responses. This plugin provides a clean, type-safe way to handle HTTP exceptions in your Elysia applications.

✨ Features

• 🎯 Complete HTTP Status Coverage - Support for all standard 4xx and 5xx HTTP status codes
• 🔧 Type-Safe - Full TypeScript support with proper type definitions
• 🚀 Easy Integration - Simple plugin installation with zero configuration required
• 🎨 Flexible Error Data - Support for string messages, objects, and Error instances
• 🔄 Two Usage Patterns - Use either throw statements or the httpException decorator
• 🛡️ Automatic Error Handling - Built-in error handler for common Elysia errors (PARSE, VALIDATION, NOT_FOUND, etc.)
• 📦 Lightweight - Minimal overhead with tree-shakable exports
• 🧪 Well Tested - Comprehensive test coverage for reliability

📦 Installation

bun add elysia-http-exception

🚀 Quick Start

Basic Setup

import { Elysia } from 'elysia';
import { httpExceptionPlugin, NotFoundException, BadRequestException } from 'elysia-http-exception';

const app = new Elysia()
  .use(httpExceptionPlugin())
  .get('/users/:id', ({ params }) => {
    const userId = parseInt(params.id);
    
    if (isNaN(userId)) {
      throw new BadRequestException('User ID must be a valid number');
    }
    
    if (userId === 404) {
      throw new NotFoundException(`User with ID ${userId} not found`);
    }
    
    return { id: userId, name: `User ${userId}`, email: `user${userId}@example.com` };
  })
  .listen(3000);

Using the Decorator Pattern

import { Elysia } from 'elysia';
import { httpExceptionPlugin, NotFoundException, BadRequestException } from 'elysia-http-exception';

const app = new Elysia()
  .use(httpExceptionPlugin())
  .get('/users/:id', ({ params, httpException }) => {
    const userId = parseInt(params.id);
    
    if (isNaN(userId)) {
      return httpException(new BadRequestException('User ID must be a valid number'));
    }
    
    if (userId === 404) {
      return httpException(new NotFoundException(`User with ID ${userId} not found`));
    }
    
    return { id: userId, name: `User ${userId}`, email: `user${userId}@example.com` };
  })
  .listen(3000);

📚 Available Exception Classes

4xx Client Error Exceptions

| Exception Class | Status Code | Description | |---|---|---| | BadRequestException | 400 | Bad Request | | UnauthorizedException | 401 | Unauthorized | | PaymentRequiredException | 402 | Payment Required | | ForbiddenException | 403 | Forbidden | | NotFoundException | 404 | Not Found | | MethodNotAllowedException | 405 | Method Not Allowed | | NotAcceptableException | 406 | Not Acceptable | | RequestTimeoutException | 408 | Request Timeout | | ConflictException | 409 | Conflict | | GoneException | 410 | Gone | | LengthRequiredException | 411 | Length Required | | PreconditionFailedException | 412 | Precondition Failed | | PayloadTooLargeException | 413 | Payload Too Large | | UriTooLongException | 414 | URI Too Long | | UnsupportedMediaTypeException | 415 | Unsupported Media Type | | RangeNotSatisfiableException | 416 | Range Not Satisfiable | | ExpectationFailedException | 417 | Expectation Failed | | ImATeapotException | 418 | I'm a teapot | | MisdirectedRequestException | 421 | Misdirected Request | | UnprocessableEntityException | 422 | Unprocessable Entity | | LockedException | 423 | Locked | | FailedDependencyException | 424 | Failed Dependency | | TooEarlyException | 425 | Too Early | | UpgradeRequiredException | 426 | Upgrade Required | | PreconditionRequiredException | 428 | Precondition Required | | TooManyRequestsException | 429 | Too Many Requests | | RequestHeaderFieldsTooLargeException | 431 | Request Header Fields Too Large | | UnavailableForLegalReasonsException | 451 | Unavailable For Legal Reasons |

5xx Server Error Exceptions

| Exception Class | Status Code | Description | |---|---|---| | InternalServerErrorException | 500 | Internal Server Error | | NotImplementedException | 501 | Not Implemented | | BadGatewayException | 502 | Bad Gateway | | ServiceUnavailableException | 503 | Service Unavailable | | GatewayTimeoutException | 504 | Gateway Timeout | | HttpVersionNotSupportedException | 505 | HTTP Version Not Supported | | VariantAlsoNegotiatesException | 506 | Variant Also Negotiates | | InsufficientStorageException | 507 | Insufficient Storage | | LoopDetectedException | 508 | Loop Detected | | NotExtendedException | 510 | Not Extended | | NetworkAuthenticationRequiredException | 511 | Network Authentication Required |

💡 Usage Examples

1. Simple String Messages

app.get('/simple', () => {
  throw new BadRequestException('Invalid input provided');
});

Response:

{
  "statusCode": 400,
  "message": "Invalid input provided"
}

2. Custom Object Data

app.post('/validate', ({ body }) => {
  throw new UnprocessableEntityException({
    error: 'VALIDATION_FAILED',
    details: {
      field: 'email',
      message: 'Invalid email format'
    },
    timestamp: new Date().toISOString()
  });
});

Response:

{
  "error": "VALIDATION_FAILED",
  "details": {
    "field": "email",
    "message": "Invalid email format"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

3. Error Object Handling

app.get('/error-object', () => {
  const validationError = new Error('Database validation failed');
  throw new InternalServerErrorException(validationError);
});

Response:

{
  "statusCode": 500,
  "message": "Database validation failed"
}

4. Rate Limiting Example

app.get('/api/data', () => {
  const rateLimitExceeded = checkRateLimit(); // Your rate limit logic
  
  if (rateLimitExceeded) {
    throw new TooManyRequestsException({
      message: 'Rate limit exceeded',
      retryAfter: 60,
      limit: 100,
      remaining: 0
    });
  }
  
  return { data: 'Your API data' };
});

5. Authentication Example

app.get('/profile', ({ headers }) => {
  const authHeader = headers['authorization'];
  
  if (!authHeader) {
    throw new UnauthorizedException({
      error: 'MISSING_AUTH_HEADER',
      message: 'Authorization header is required',
      requiredFormat: 'Bearer <token>'
    });
  }
  
  if (!authHeader.startsWith('Bearer ')) {
    throw new UnauthorizedException('Invalid authorization format');
  }
  
  return { user: { id: 1, name: 'John Doe' } };
});

6. File Upload Example

app.post('/upload', ({ request }) => {
  const contentLength = parseInt(request.headers.get('content-length') || '0');
  const maxSize = 5 * 1024 * 1024; // 5MB
  
  if (contentLength > maxSize) {
    throw new PayloadTooLargeException({
      error: 'FILE_TOO_LARGE',
      message: 'File size exceeds maximum allowed size',
      maxSize: `${maxSize / 1024 / 1024}MB`,
      receivedSize: `${(contentLength / 1024 / 1024).toFixed(2)}MB`
    });
  }
  
  return { message: 'Upload successful' };
});

7. E-commerce Example

app.post('/checkout', ({ body }) => {
  const data = body as any;
  
  if (!data.items?.length) {
    throw new BadRequestException({
      error: 'EMPTY_CART',
      message: 'Cart cannot be empty for checkout'
    });
  }
  
  const outOfStockItem = data.items.find((item: any) => !item.inStock);
  if (outOfStockItem) {
    throw new ConflictException({
      error: 'ITEM_OUT_OF_STOCK',
      message: 'Some items in your cart are no longer available',
      unavailableItems: [outOfStockItem]
    });
  }
  
  return { message: 'Checkout successful', orderId: 'order-123' };
});

🔧 Built-in Error Handling

The plugin automatically handles common Elysia errors:

• PARSE: JSON parsing errors → 400 Bad Request
• VALIDATION: Schema validation errors → 400 Bad Request
• NOT_FOUND: Route not found → 404 Not Found
• INVALID_COOKIE_SIGNATURE: Invalid cookies → 400 Bad Request
• INVALID_FILE_TYPE: Unsupported file types → 415 Unsupported Media Type

🏗️ API Reference

httpExceptionPlugin()

The main plugin function that adds HTTP exception handling to your Elysia app.

import { httpExceptionPlugin } from 'elysia-http-exception';

const app = new Elysia().use(httpExceptionPlugin());

HttpException Base Class

All exception classes extend from the base HttpException class:

class HttpException extends Error {
  public readonly statusCode: number;
  public readonly code: string;
  public readonly data?: unknown;
  public readonly isHttpException = true;
  
  constructor(httpError: HttpError, message?: string | object | Error | unknown);
  toBody(): unknown;
}

Exception Constructor Parameters

Each exception class accepts an optional message parameter:

• string: Simple error message
• object: Custom error data (returned as-is in response)
• Error: Error instance (uses error.message)
• undefined: Uses default message for the status code

🧪 Testing

The plugin includes comprehensive tests. Run them with:

# Run all tests
bun test

# Run unit tests only
bun test:unit

# Run e2e tests only
bun test:e2e

# Run tests with coverage
bun test:coverage

# Watch mode
bun test:watch

📋 Examples

Check out the comprehensive examples in the /example directory:

• example-throw.ts: Demonstrates using throw statements
• example-decorator.ts: Demonstrates using the httpException decorator

Run the examples:

cd example
bun run example-throw.ts     # Server on http://localhost:3000
bun run example-decorator.ts # Server on http://localhost:3001

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• Elysia - The fast and friendly Bun web framework
• HTTP Status Codes - For comprehensive status code reference
• The Bun and TypeScript communities for their excellent tooling

🔗 Links

• GitHub Repository
• npm Package
• Elysia Documentation
• TypeScript Documentation