README.md

node-error

Error codes, and a custom error function for Alien Creations node apps.

Install

$ yarn add @aliencreations/node-error

API

error

Custom error function which allows injection of metadata into an object of type Error. Simply invoke with an object containing any metadata you wish to make it to the logs. Preserves the stacktrace.

errors

Dictionary of error codes and messages for various parts of the Alien Creations NodeJS suite of apps. This is to be considered the source of truth for all error codes from 2020 onward.

Usage

Basic Usage

const { error, errors } = require('@aliencreations/node-error')

const { FORBIDDEN_API_ACCESS } = errors.auth;

if (someCondition) {
  throw error(FORBIDDEN_API_ACCESS());
}

console.log(err):

{ Error: Permission denied
    at error ...
    at runCallback (timers.js:705:18)
  code: 5004,
  statusCode: 403,
  isInternalError: true,
  message: 'Permission denied',
  debug: { internalMessage: 'Forbidden API access' } }

The errors parameter is optional. If errors isn't used, the Error created will be a standard Error object with the parameters object merged in.

Overriding Default Values

You can also override any default values by passing in parameters.

const err = error(
  errors.auth.FORBIDDEN_API_ACCESS({
    message: 'custom message',
    debug: { internalMessage: 'My internal message', otherProp: 'value' },
    statusCode: 400
  })
)

console.log(err):

{ Error: custom message
    at error ...
    at runCallback (timers.js:705:18)
  code: 5004,
  statusCode: 400,
  isInternalError: true,
  message: 'custom message',
  debug:
   { internalMessage: 'My internal message', otherProp: 'value' } }

The message property should always be safe to display to the user.

The messageContext property is optional and, if present, is concatenated to the message with a colon.

The debug property object contains additional information that should only be available to services on the back end or to all users in development, demo, or test environments, but never to front end users in production. The debug property can be removed in a root error handler (e.g., Express error handler middleware or AWS Lambda catch statement at the end of the handler) when necessary.

To remove the debug property: R.omit(['debug'], err)

The isInternalError property is true for all errors created by our apps, as long as this package generates the Errors. Errors generated by third party libraries and services will not have this property set. In a root error handler, you can check for the presence of isInternalError to decide if it is safe to serialize the Error's own properties as is and return it to the user, or whether a new Error should be created with wraps this error. When wrapping a third party Error, use error.system.UNCAUGHT.

Note that when serializing an Error message, the stack property should be removed, at least for all front end production users.

When creating a new Error, if you want to wrap an existing Error, you should add it to the debug.originalError property.

const originalError = new Error('Some third Party library Error')

const err = error(
  errors.auth.TOKEN_EXPIRED({
    message: 'override message4',
    debug: { prop3: 'value3', prop0: 'newvalue', internalMessage: 'Custom Internal Message', originalError }
  }),

)

console.log(err):

{ Error: override message4
    at error ...
    at runCallback (timers.js:705:18)
  code: 5003,
  statusCode: 401,
  isInternalError: true,
  message: 'override message4',
  debug:
   { internalMessage: 'Custom Internal Message',
     prop3: 'value3',
     prop0: 'newvalue',
     originalError:
      Error: Some third Party library Error
          at UserContext.fit ...
          at processImmediate (timers.js:658:5) } }

You can add any additional details to debug for developers to read. For additional human-readable details, add them to debug.internalMessage. If internalMessage is populated in the configuration, it will be overridden by the value passed in the error function.

Changelog

1.0.0

• Initial commit

1.0.1

• Update dependencies

1.0.3

• Update README

1.0.3

• Fix isInternalError typo