@thebosco/the-bosco-internal-error

Internal Error

This package exposes an InternalError class to your Node application, making error handling more predictable and consistent across applications. Each InternalError is composed of the following standard elements:

Code

The error code provides a semantic explanation of the problem that has occurred. For InternalErrors that pertain to HTTP requests, all error codes will follow Mozilla's definitions of HTTP Response Status Codes in both name (e.g., 'Not Found' has an error code of 'NOT_FOUND'). An InternalError that does not correspond to an HTTP request can use a custom code name, but must implement HTTP-like features to ensure that InternalErrors thrown to an HTTP response block can interpret them correctly.

Level

The error level property specifies the level at which logging (and priorty) should be considered for errors of this kind. When a logging package is provided, InternalErrors will be automatically logged using this level, unless logging is disabled for the error, or an alternate level is provided instead. For more information of the available logging levels, see The Bosco Server Logger.

Message

An InternalError must contain a message property to provide users with more context about the reason an InternalError was thrown. Default message properties must be provided, but typically will not provide as much semantic value as a message given while initializing an InternalError, and so it's strongly encouraged to provide more information at this time, even if it may seem redundant or self-evident at the time of writing. Errors that explain themselves are better than errors that don't!

Status Code

Corresponding with the HTTP Response Status Codes above, a numerical status_code must accompany the default instantiation of an InternalError to allow for simplified HTTP response handling, when InternalErrors are utilized inside of response-handling blocks. Custom Status Codes may be given, but are not encouraged, and should only be utilized when providing backwards-compatibility support for legacy code.

Status

To provide legacy support for old HTTP Response handlers, an InternalError should have a status that corresponds to the Code property. Custom statuses may be provided as well, but really shouldn't be. We plan on removing the 'Status' property as soon as all prior applications no longer use property.

Sample Usage

# Import the class and assign it to the global object.
# Provide a logging package as a parameter if one is desired, or leave out the parameter.
global.InternalError = require('@thebosco/the-bosco-internal-error')(optionalLoggingPackage?)

try {
  throw new InternalError(ERROR_CODE, message, {
    level,               // Enum - See available levels [here](https://github.com/thebosco/the-bosco-server-logger)
    data,                // Object - Additional data to be logged, if using logging.
    responseMessage,     // String - A message to be sent in the HTTP Response. Use if different from the message.
    responseDetail,      // Object - Additional data to send to the user in the HTTP Response.
    useMessage           // Boolean - Whether the message provided should be sent to the user, or a default response.
  })
} catch (error) {
  // Do something with your error
}

Contributions

All new codes implemented must be submitted to this package in order to be utilized. Furthermore, the package will then need to be updated and deployed accordingly:

1. Update the package, and commit the work in Github.
2. Update the package's version number with npm version [type] (see SemVer Rules below for type guidance).
3. Publish the package with npm publish.
4. Update your application with npm update @thebosco/the-bosco-internal-error.

SemVer Rules

Updates to the package will follow Semantic Versioning as closely as possible. In order to accomplish this, here's some rule-of-thumb definitions to remember:

Major

A Major update will be any update that requires all implementations of the package to be updated in order to continue to be usable. This includes any updates that change the way in which the package is imported, or the way in which each instance of the InternalError class is utilized in the application. Major updates are not backwards compatible.

Minor

A Minor update will be any new feature addition which is backwards compatible. This will include any update which extends the functionality of the package, either by adding new Error Instances, or new methods to the InternalError package, or the way in which it is imported into the application (as long as it does not require those changes be made in order to continue working).

Patch

A Patch update will be any update that fixes bugs only, and is backwards compatible. Performing Minor or Major work alongside of Patch work will defer to the higher type (i.e., making breaking changes with a bug fix will mean you need to update Major, not Patch).