diff --git a/docs/DOCS.md b/docs/DOCS.md index 7653f10..6fcd8a8 100644 --- a/docs/DOCS.md +++ b/docs/DOCS.md @@ -8,4 +8,5 @@ The documentation is organized into sections by module. 1. [Handlers](/docs/utils/MIDDYFY.md) 1. [Configuration](/docs/services/CONFIG.md) -1. [DynamoDB Client](/docs//services/DYNAMO.md) +1. [DynamoDB Client](/docs/services/DYNAMO.md) +1. [Errors](/docs/errors/ERRORS.md) diff --git a/docs/errors/ERRORS.md b/docs/errors/ERRORS.md new file mode 100644 index 0000000..0041e3e --- /dev/null +++ b/docs/errors/ERRORS.md @@ -0,0 +1,151 @@ +:house: [Home](/README.md) | :books: [Docs](../DOCS.md) + +# Errors + +This document describes how to use the family of `Error` classes within the `@leanstacks/serverless-common` package. + +## How it works + +The `@leanstacks/serverless-common` package provides a family of error classes which may be utilized within AWS Lambda functions to ensure that a consistent response is returned when exception scenarios occur. + +## Using the errors + +There are two base error classes: `ServiceError` and `HttpError`. Both extend `Error` and, therefore, both have `name` and `message` properties. Additional properties are included to provide more information. + +### `ServiceError` + +A `ServiceError` may be used in any type of AWS Lambda function. The error has the following properties: + +- `name` -- The string "ServiceError". +- `message` -- A string message describing the error. +- `statusCode` -- Optional. A numeric [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) +- `code` -- Optional. A numeric value to convey further meaning to the API client regarding the cause of the error + +A `ServiceError` may be constructed with either a string or an Error as the first parameter. The optional second parameter is the numeric `code`. And, the optional third parameter is the `statusCode`. + +_Example: Throw a `ServiceError` with a message._ + +```ts +new ServiceError('Object not found in S3 bucket'); +``` + +_Example: Throw a `ServiceError` with an error and code._ + +```ts +try { + ... +} catch (err) { + throw new ServiceError(err, 1001); +} +``` + +### `HttpError` + +A `HttpError` and, more often, it's sub-classes are used in API Gateway Lambda functions. The error has the following properties: + +- `name` -- The string "HttpError". +- `message` -- A string message describing the error. +- `statusCode` -- A numeric [HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) + +A `HttpError` may be constructed with either a string or an Error as the first parameter and a status code as the second parameter. + +_Example: Throw a `HttpError` with a message and status code._ + +```ts +new HttpError('Not found', 404); +``` + +_Example: Throw a `HttpError` with an error and status code._ + +```ts +try { + ... +} catch (err) { + throw new HttpError(err, 500); +} +``` + +However, it is more common to use one of the `HttpError` sub-classes: + +- `BadRequestError` +- `ForbiddenError` +- `NotFoundError` + +### `BadRequestError` + +A `BadRequestError` extends `HttpError`. The error `name` is "BadRequestError" and the `statusCode` is 400. + +The `BadRequestError` constructor accepts an optional string `message` parameter. When provided, this value is set to the error `message` property, otherwise, the default HTTP status message for HTTP 400 is used. + +_Example: Throw a `BadRequestError` with the default message._ + +```ts +new BadRequestError(); +``` + +_Example: Throw a `BadRequestError` with a custom message._ + +```ts +try { + ... +} catch (err) { + throw new BadRequestError(err.message); +} +``` + +### `ForbiddenError` + +A `ForbiddenError` extends `HttpError`. The error `name` is "ForbiddenError" and the `statusCode` is 403. + +The `ForbiddenError` constructor accepts an optional string `message` parameter. When provided, this value is set to the error `message` property, otherwise, the default HTTP status message for HTTP 403 is used. + +_Example: Throw a `ForbiddenError` with the default message._ + +```ts +new ForbiddenError(); +``` + +_Example: Throw a `ForbiddenError` with a custom message._ + +```ts +try { + ... +} catch (err) { + throw new ForbiddenError(err.message); +} +``` + +### `NotFoundError` + +A `NotFoundError` extends `HttpError`. The error `name` is "NotFoundError" and the `statusCode` is 404. + +The `NotFoundError` constructor accepts an optional string `message` parameter. When provided, this value is set to the error `message` property, otherwise, the default HTTP status message for HTTP 404 is used. + +_Example: Throw a `NotFoundError` with the default message._ + +```ts +new NotFoundError(); +``` + +_Example: Throw a `NotFoundError` with a custom message._ + +```ts +try { + ... +} catch (err) { + throw new NotFoundError(err.message); +} +``` + +## Example API client response + +When any of the error family of classes is thrown from an API Gateway Lambda function, the `http-error-handler` middleware intercepts the error and, using the information within the error, creates an informative response for the API client. The response body payload is similar to the example below. + +````json +{ + "name": "NotFoundError", + "message": "The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.", + "code": 404, + "statusCode": 404 +}``` +````