README
Middy Exception Handler
HTTP exception handler middleware for the middy framework, the stylish Node.js middleware engine for AWS Lambda
Automatically handles any uncaught errors and creates a proper HTTP response for them (using the message and the status code provided by HttpException
class).
This exception handler was inspired by Nest.js's built-in exception filters.
This middleware should be set as the last error handler unless you also want to register the http-reponse-serializer
. If so, this middleware should come second-last and the http-response-serializer
should come last.
This is an alternative to standard Middy error handler with the following differences:
- it contains built in exception classes
- it always returns JSON object and not text
- it handles any uncaught error, not just the ones with
statusCode
andmessage
Install
To install this middleware you can use NPM:
npm install --save middy-exception-handler
Options
logger
(defaults toconsole
) - a logging function that is invoked with the current error as an argument. You can passfalse
if you don't want the logging to happen.level
(defaults toerror
) - log level to use for the error log entry
Example
The response argument defines the JSON response body. It can be a string or an object as described below. The status argument defines the HTTP status code.
import middy from '@middy/core';
import { NotFoundException, exceptionHandler } from 'middy-exception-handler';
const handler = middy(() => {
throw new NotFoundException();
});
handler
.use(exceptionHandler());
// when Lambda runs the handler...
handler({}, {}, (_, response) => {
expect(response).toEqual({
statusCode: 404,
body: JSON.stringify({ status: 404, message: 'Not Found' }),
})
})
Usage
The HttpException
constructor takes two required arguments which determines the response:
statusCode
: defaults to the HTTP status code provided in the status argumentmessage
: a short description of the HTTP error
Full list of exceptions
- BadGatewayException
- BadRequestException
- ConflictException
- ForbiddenException
- GatewayTimeoutException
- GoneException
- HttpVersionNotSupportedException
- ImATeapotException
- InsufficientSpaceOnResourceException
- InsufficientStorageException
- InternalServerErrorException
- LockedException
- MethodNotAllowedException
- NetworkAuthenticationRequiredException
- NotAcceptableException
- NotFoundException
- NotImplementedException
- PaymentRequiredException
- PreconditionRequiredException
- RequestHeaderFieldsTooLargeException
- RequestTimeoutException
- RequestTooLongException
- RequestURITooLongException
- ServiceUnavailableException
- TooManyRequestsException
- UnauthorizedException
- UnavailableForLegalReasonsException
- UnprocessableEntityException
- UnsupportedMediaTypeException
Using a custom message
const handler = middy(() => {
throw new UnauthorizedException('A custom message');
});
response:
{
"status": 401,
"message": "A custom message"
}
Include additional details in response
const handler = middy(() => {
throw new UnauthorizedException('A custom message', { abcd: 'efg' });
});
response:
{
"status": 401,
"message": "A custom message",
"details": {
"abcd": "efg"
}
}
Exception name and timestamp
You can also configure to include a timestamp and exception name to the response:
handler
.use(exceptionHandler({ includeTimestamp: true, includeExceptionName: true }));
response:
{
"timestamp": "2022-02-04T14:41:22.457Z",
"status": 401,
"exception": "BadRequestException",
"message": "A custom message"
}
Contributing
Everyone is very welcome to contribute to this repository. Feel free to raise issues or to submit Pull Requests.