A comprehensive TypeScript exception library with HTTP status code support, detailed JSDoc documentation, and backward compatibility. Provides structured error handling for web applications and APIs.
npm install jsm-exceptions
A comprehensive TypeScript exception library with HTTP status code support, detailed JSDoc documentation, and backward compatibility. Provides structured error handling for web applications and APIs.
- 🎯 HTTP Status Code Alignment: Each exception corresponds to appropriate HTTP status codes
- 📝 Comprehensive JSDoc: Detailed documentation with examples for every exception
- 🔄 Backward Compatibility: Maintains compatibility with existing code using @deprecated annotations
- 🏗️ TypeScript Support: Full TypeScript support with proper type definitions
- 🧩 Modular Design: Import only what you need
- 🔍 Rich Context: Support for additional context and metadata in exceptions
- ⏰ Timestamps: Automatic timestamp tracking for debugging
- 🎨 Validation Support: Built-in support for Joi validation errors
``bash`
npm install jsm-exceptions
`typescript
import { BadRequestException, ValidationException, ItemNotFoundException } from 'jsm-exceptions';
// Simple usage
throw new BadRequestException('Invalid request format');
// With additional context
throw new ItemNotFoundException('User not found', { userId: '12345' });
// Validation with field errors
throw new ValidationException('Validation failed', {
email: { value: 'invalid-email', message: 'Email format is invalid' },
age: { value: -1, message: 'Age must be positive' }
});
`
`typescript
import { BaseException } from 'jsm-exceptions';
// Custom exception extending BaseException
class CustomBusinessException extends BaseException {
constructor(message: string, context?: Record
super(message, 422, context); // HTTP 422 Unprocessable Entity
}
}
throw new CustomBusinessException('Business rule violation', {
rule: 'maximum-orders-per-day',
limit: 10,
current: 11
});
`
| Exception | HTTP Code | Description |
|-----------|-----------|-------------|
| BadRequestException | 400 | Malformed or invalid requests |UnauthorizedException
| | 401 | Authentication required or invalid |InvalidPasswordException
| | 401 | Password authentication failures |JWTTokenExpiredException
| | 401 | Expired JWT tokens |ForbiddenException
| | 403 | Insufficient permissions |ItemNotFoundException
| | 404 | Resource not found |NoItemsFoundException
| | 404 | Search returned no results |MethodNotAllowedException
| | 405 | HTTP method not supported |RequestTimeoutException
| | 408 | Request timeouts |ValueAlreadyExistsException
| | 409 | Resource conflicts |ValidationException
| | 422 | Input validation failures |UnprocessableEntityException
| | 422 | Semantic errors |TooManyRequestsException
| | 429 | Rate limiting |
| Exception | HTTP Code | Description |
|-----------|-----------|-------------|
| InternalServerErrorException | 500 | Unexpected server errors |NotImplementedException
| | 501 | Unimplemented features |ServiceUnavailableException
| | 503 | Temporary service unavailability |
| Exception | HTTP Code | Description |
|-----------|-----------|-------------|
| NoContentException | 204 | Valid request with no response body |
`typescript
import Joi from 'joi';
import { ValidationException } from 'jsm-exceptions';
const schema = Joi.object({
email: Joi.string().email().required(),
age: Joi.number().min(0).required()
});
try {
const { error } = schema.validate(data);
if (error) {
throw new ValidationException('Validation failed', error);
}
} catch (joiError) {
// ValidationException automatically handles Joi.ValidationError
throw new ValidationException('Input validation failed', joiError);
}
`
`typescript
import express from 'express';
import { BaseException, InternalServerErrorException } from 'jsm-exceptions';
const app = express();
// Error handling middleware
app.use((error: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
if (error instanceof BaseException) {
return res.status(error.status).json({
success: false,
error: {
name: error.name,
message: error.message,
context: error.context,
timestamp: error.timestamp
}
});
}
// Handle unexpected errors
const internalError = new InternalServerErrorException('Unexpected error occurred');
res.status(500).json({
success: false,
error: internalError.toJSON()
});
});
`
`typescript
import { TooManyRequestsException } from 'jsm-exceptions';
class RateLimiter {
checkLimit(userId: string, limit: number, windowMs: number) {
const requests = this.getUserRequests(userId, windowMs);
if (requests.length >= limit) {
throw new TooManyRequestsException('Rate limit exceeded', {
userId,
limit,
windowMs,
requestCount: requests.length,
retryAfter: this.getRetryAfter(requests[0], windowMs)
});
}
}
}
`
The library maintains backward compatibility, but we recommend migrating to the new exception names:
`typescript
// ❌ Old (deprecated)
import { JsmException, InternalServerError, JWTTokenExpired } from 'jsm-exceptions';
// ✅ New (recommended)
import { BaseException, InternalServerErrorException, JWTTokenExpiredException } from 'jsm-exceptions';
`
Deprecated exports will show warnings in TypeScript and include @deprecated JSDoc annotations.
All exceptions extend BaseException and include:
`typescript`
interface ExceptionProperties {
name: string; // Exception class name
message: string; // Error message
status: number; // HTTP status code
context?: Record
timestamp: Date; // When the exception was created
stack?: string; // Stack trace
}
`typescript
const exception = new BadRequestException('Invalid input', { field: 'email' });
console.log(exception.toJSON());
// Output:
// {
// name: 'BadRequestException',
// message: 'Invalid input',
// status: 400,
// context: { field: 'email' },
// timestamp: '2025-07-22T10:30:00.000Z',
// stack: '...'
// }
`
The foundation class for all exceptions.
`typescript`
class BaseException extends Error {
constructor(message?: string, status?: number, context?: Record
toJSON(): object
toString(): string
}
Special handling for validation errors with field-specific information.
`typescript``
class ValidationException extends BaseException {
fields: ErrorFields;
isJoi: boolean;
isMongoose: boolean;
isCelebrate: boolean;
}
Contributions are welcome! Please read our contributing guidelines and submit pull requests for any improvements.
This project is licensed under the MIT License - see the LICENSE file for details.