@switchcase/node-lerror

This NPM module is designed to help simplify the management of common HTTP error codes.

Table of Contents

• Prerequisites
• Installation
• Building
• Testing
• Deployment
• Usage

Prerequisites

• node 12+ LTS

Installation

yarn add @switchcase/node-lerror

Building

yarn build

Testing

yarn install
yarn test

Usage

The intent of this module is to translate internal javascript API into consistent HTTP Error responses.

// https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html
export const handler = async (event: object = {}): Promise<object> => {
  console.log("Received event:", JSON.stringify(event, null, 2));
  const action = event.httpMethod;

  let body = event.body;
  if (event.isBase64Encoded === true) {
    const buff = new Buffer(event.body, "base64");
    body = buff.toString("utf8");
  }

  if (action === "POST") {
    console.log("handling POST calling processEvent");
    try {
      return await processEvent(body);
    } catch (e) {
      console.log("caught exception!", e);
      throw new BadRequestError("Something went wrong");
    }
  } else {
    console.log("throwing BadRequestError");
    throw new BadRequestError("Invalid action");
  }
};

Error Contract

The following are the public properties availabe for these error classes.

Property name	Type	Meaning
name	string	Programmatically-usable name of the error.
message	string	Human-readable summary of the failure. Programmatically-accessible details are provided through VError.info(err) class method.
stack	string	Human-readable stack trace where the Error was constructed.
statusCode	number	HTTP Status Code that should be presented for this error

{
  name: 'NotFoundError',
  statusCode: 404 ,
  message: "File Not Found",
  stack: Error().stack
}

Background

There are few different standards and conventions by Amazon API Gateway, Amazon Lambda, Node, Express, etc. that may conflict on how to handle errors and tracing such requests. The goal here is to create a single set of Error classes that incorporate the best practices and manages some of the details that will help us more consistently integrate with our observability and REST API contracts.

1. Be clear about what your function does.
2. Use Error objects (or subclasses) for all errors, and implement the Error contract.
3. Use the Error's name property to distinguish errors programmatically.
4. Augment the Error object with properties that explain details
5. If you pass a lower-level error to your caller, consider wrapping it instead.

It recommend to standardize on the following property name, so they can be used further down the stack.

Property name	Intended use
localHostname	the local DNS hostname (e.g., that you're accepting connections at)
localIp	the local IP address (e.g., that you're accepting connections at)
localPort	the local TCP port (e.g., that you're accepting connections at)
remoteHostname	the DNS hostname of some other service (e.g., that you tried to connect to)
remoteIp	the IP address of some other service (e.g., that you tried to connect to)
remotePort	the port of some other service (e.g., that you tried to connect to)
path	the name of a file, directory, or Unix Domain Socket (e.g., that you tried to open)
srcpath	the name of a path used as a source (e.g., for a rename or copy)
dstpath	the name of a path used as a destination (e.g., for a rename or copy)
hostname	a DNS hostname (e.g., that you tried to resolve)
ip	an IP address (e.g., that you tried to reverse-resolve)
propertyName	an object property name, or an argument name (e.g., for a validation error)
propertyValue	an object property value (e.g., for a validation error)
syscall	the name of a system call that failed
errno	the symbolic value of errno (e.g., "ENOENT"). Do not use this for errors that don't actually set the C value of errno. Use "name" to distinguish between types of errors.

This package builds on top of the verror NPM package.

Reference

• Node.js Production Practices: Error Handling in Node.js
• Node.js documentation: Errors
• AWS Lambda Developer Guide: AWS Lambda function errors in Node.js
• AWS Compute Blog: Error Handling Patterns in Amazon API Gateway and AWS Lambda (June 13th, 2016)
• Github Gist: Creating custom Error classes in Node.JS
• Error Tracing with ES6 Classes and Sentry (Agust 7th, 2020)