Errr

"Error factory with the ability to append stack traces from previous errors, as well as appending debug params to stack traces. Great if you want one appended stack trace that defines the error at many levels of your code. This concept works wonders when using promise chains because you get the stack trace at each level of your code.

Best Practices

1. Each layer of your code should catch an error, and append that error to the incoming error.
2. Add debug params to each error build to assist debugging later.
3. Do NOT add large objects to debug params. It only makes reading the logs more difficult.
4. Throw all errors to the top layer of code and only log the error in that layer of code. Doing this ensures you have one log statement with the entire stack trace which will make debugging much easier.

Install

Example

Example Output

NPM Scripts

1. npm run test - Run linter and unit tests.
2. npm run ut - Use Maddox to Run Unit Tests.
3. npm run perf - Use Maddox to Performance metrics.
4. npm run uap - Use Maddox to Unit Tests and Performance metrics.
5. npm run lint - Run linter.
6. npm run docs - Rebuild public API Docs.

API

Error

Error Builder allows you to use optional functions to build an error object. The error can have appended stack traces and debug params to assist with debugging.

Kind: global class

• Error
  • new Error([message], [template])
  • .debug(params, [shouldDebug]) ⇒ ErrorBuilder
  • .set(key, value, [force]) ⇒ ErrorBuilder
  • .setAll(object, [force]) ⇒ ErrorBuilder
  • .appendTo(err) ⇒ ErrorBuilder
  • .get() ⇒ Error
  • .throw()

new Error([message], [template])

Provides an interface to build an error. Then allows you to get or throw the error.

| Param | Type | Description | | --- | --- | --- | | [message] | String | Error message that will supplied to Error Object. | | [template] | Array | Array of parameters. If given, util.format(message, template) will be applied to the message string. |

error.debug(params, [shouldDebug]) ⇒ ErrorBuilder

Add parameters to the stack trace that will make it easier to debug the problem. These values will appear in a in an object labeled "Debug Params" in the stack trace. You may call the 'debug' function as many times as you'd like on an ErrorBuilder instance. If the same key is passed in many times, the time it is passed in, will be the value that appears in the stack trace.

Unlike the 'set' function, which merges 'set' values from different Errr instances with its own instance, the debug params start as an empty object for each Errr instance. They are attached to the stack trace and then forgotten.

Kind: instance method of Error
Returns: ErrorBuilder - - Returns the instance of errorBuilder to allow chainability.

| Param | Type | Description | | --- | --- | --- | | params | Object | Object Map of key value parameters that will make it easier to debug the error. | | [shouldDebug] | Boolean | If shouldDebug === false, then debug params will not print. Any other value (including undefined), and the debug params will be printed. Useful if you want to only print debugParams given an Environment Variable. |

error.set(key, value, [force]) ⇒ ErrorBuilder

Sets a value on the error object using the key as the variable name. Values added using the 'set' function will be appended to new error objects when using the the .appendTo function. I.e. the values on the appendTo err will be copied to the new error. These values are immutable though unless you use the 'force' value. As soon as you set a value with a given key, it cannot be reset unless you pass in 'true' for the force variable.

The reason for enforcing an immutable paradigm, is to allow for values to be set on the error object at the level where the error was originally thrown (seemingly where the most important info will come from). This allows the user to set a value such as 'reason' on the error object at all level of your code, but only the most important reason will value will persist on the error object.

Kind: instance method of Error

| Param | Type | Description | | --- | --- | --- | | key | String | The key that will be used to set the value on the error object. | | value | Object | The value that will be set on the object. | | [force] | Boolean | If force equals true, then this value will override a value with the same key from an errr passed in using the 'appendTo' function. |

error.setAll(object, [force]) ⇒ ErrorBuilder

Same concept and functionality as the 'set' function. The difference is that you can set all values in a given object onto the Errr instance.

Follows the same immutable paradigm as the 'set' function. The difference is that you are setting the force override for all value in the given object.

See set to understand functionality better.

Kind: instance method of Error

| Param | Type | Description | | --- | --- | --- | | object | Object | Many key / value pairs to be set on the object. | | [force] | Boolean | If force equals true, then this value will override a value with the same key from an errr passed in using the 'appendTo' function. |

error.appendTo(err) ⇒ ErrorBuilder

Append the error being built, to the end of this error's stack trace.

Kind: instance method of Error
Returns: ErrorBuilder - - Returns the instance of errorBuilder to allow chainability.

| Param | Type | Description | | --- | --- | --- | | err | Error | The stack trace of the error being built, will be appended to this error's stack trace. |

error.get() ⇒ Error

Returns a new Error object using the given parameters from the builder.

Kind: instance method of Error
Returns: Error - - Returns a new Error object using the given parameters from the builder.

error.throw()

Throws a new Error object using the given parameters from the builder.

Kind: instance method of Error
Throws:

• Error - Throws a new Error object using the given parameters from the builder.

Errr

Static class that contains the 'newError' factory function. Use the 'newError' factory function to return an ErrorBuilder instance.

Kind: global class

• Errr
  • .newError([message], [template]) ⇒ FromMessage
  • ~~.fromError(err) ⇒ FromError~~

Errr.newError([message], [template]) ⇒ FromMessage

Gets a new ErrorBuilder instance.

Kind: static method of Errr
Returns: FromMessage - Gets an ErrorBuilder to get or throw an Error.

| Param | Type | Description | | --- | --- | --- | | [message] | String | Error message that will supplied to Error Object. | | [template] | Array | Array of parameters. If given, util.format(message, template) will be applied to the message string. |

~~Errr.fromError(err) ⇒ FromError~~

Deprecated

Kind: static method of Errr
Returns: FromError - Gets an ErrorBuilder to get or throw an Error.

| Param | Type | Description | | --- | --- | --- | | err | String | Will be used for the top level error and stack trace. |

FromError

Error Builder allows you to use optional functions to build an error object. The error can have appended stack traces and debug params to assist with debugging.

Kind: global class

new FromError(error)

Provides an interface to build an error from an error. Then allows you to get or throw the error.

| Param | Type | Description | | --- | --- | --- | | error | String | Will be used for the top level error and stack trace. |

FromMessage

Error Builder allows you to use optional functions to build an error object. The error can have appended stack traces and debug params to assist with debugging.

Kind: global class

new FromMessage([message], [template])

Provides an interface to build an error from a message. Then allows you to get or throw the error.

| Param | Type | Description | | --- | --- | --- | | [message] | String | Error message that will supplied to Error Object. If not given, empty string will be used for the error message. | | [template] | Array | Array of parameters. If given, util.format(message, template) will be applied to the message string. |