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

npm install errr

Example

// debug, set, and appendTo are optional
// Throws an error
try {
  Errr.newError(message, template).debug(this.debugParams)
    .set("reason", someReason).set("statusCode", 404)
    .appendTo(someError).throw();
} catch (err) {
  let reason = err.reason; // Get value from someReason
  let allDebugParams = err.getAllDebugParams() // Get an array of all the debug params from all appended errors
}

// Returns an error.
let errr = Errr.newError(message, template).debug(this.debugParams)
  .set("reason", someReason).set("statusCode", 404)
  .appendTo(someError).get();
  
let reason = errr.reason; // Get value from someReason
let allDebugParams = errr.getAllDebugParams() // Get an array of all the debug params from all appended errors

Example Output

Error: [0d7c45075935b73716643af5] Some Error
    at ErrorBuilder._build_ (/Users/corybillparrish/workspace/errr/lib/error-builder.js:89:17)
    at ErrorBuilder.get (/Users/corybillparrish/workspace/errr/lib/error-builder.js:73:17)
    at Object.context.entryPointObject.run (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1297:74)
    at FromSynchronousScenario.test (/Users/corybillparrish/workspace/errr/node_modules/maddox/lib/scenarios/functional/from-synchronous-scenario.js:17:46)
    at Context. (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1309:10)
    at callFnAsync (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:338:8)
    at Test.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:290:7)
    at Runner.runTest (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:422:10)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:533:12
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:342:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:352:7
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:284:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:315:7
    at done (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:276:5)
    at callFn (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:333:7)
    at Hook.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:308:7)
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:298:10)
    at Immediate._onImmediate (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:320:5)
    at processImmediate [as _immediateCallback] (timers.js:383:17)
Debug Params: {
  "someParam": "c926b1d07df0749bc61b7cfc"
}
     ------------------------- FROM -------------------------
Error: [79f35d4d75e0653e6ff3b0f0] Some Error 3
    at ErrorBuilder._build_ (/Users/corybillparrish/workspace/errr/lib/error-builder.js:89:17)
    at ErrorBuilder.get (/Users/corybillparrish/workspace/errr/lib/error-builder.js:73:17)
    at Object.context.setupAppendErrors (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1277:43)
    at Context. (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1303:15)
    at callFnAsync (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:338:8)
    at Test.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:290:7)
    at Runner.runTest (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:422:10)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:533:12
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:342:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:352:7
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:284:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:315:7
    at done (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:276:5)
    at callFn (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:333:7)
    at Hook.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:308:7)
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:298:10)
    at Immediate._onImmediate (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:320:5)
    at processImmediate [as _immediateCallback] (timers.js:383:17)
     ------------------------- FROM -------------------------
Error: [880a280e670b68a4f2d0efc6] Some Error 2
    at ErrorBuilder._build_ (/Users/corybillparrish/workspace/errr/lib/error-builder.js:89:17)
    at ErrorBuilder.get (/Users/corybillparrish/workspace/errr/lib/error-builder.js:73:17)
    at Object.context.setupAppendErrors (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1268:43)
    at Context. (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1303:15)
    at callFnAsync (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:338:8)
    at Test.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:290:7)
    at Runner.runTest (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:422:10)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:533:12
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:342:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:352:7
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:284:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:315:7
    at done (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:276:5)
    at callFn (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:333:7)
    at Hook.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:308:7)
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:298:10)
    at Immediate._onImmediate (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:320:5)
    at processImmediate [as _immediateCallback] (timers.js:383:17)
Debug Params: {
  "someParam2": "7e8a3ef64acc245d87ce49f0"
}
     ------------------------- FROM -------------------------
Error: [cff70d396b7cac6ddf12c8c2] Some Error 1
    at ErrorBuilder._build_ (/Users/corybillparrish/workspace/errr/lib/error-builder.js:89:17)
    at ErrorBuilder.get (/Users/corybillparrish/workspace/errr/lib/error-builder.js:73:17)
    at Object.context.setupAppendErrors (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1255:42)
    at Context. (/Users/corybillparrish/workspace/errr/spec/unit/errr-spec.js:1303:15)
    at callFnAsync (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:338:8)
    at Test.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:290:7)
    at Runner.runTest (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:422:10)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:533:12
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:342:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:352:7
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:284:14)
    at /Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:315:7
    at done (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:276:5)
    at callFn (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:333:7)
    at Hook.Runnable.run (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runnable.js:308:7)
    at next (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:298:10)
    at Immediate._onImmediate (/Users/corybillparrish/workspace/errr/node_modules/mocha/lib/runner.js:320:5)
    at processImmediate [as _immediateCallback] (timers.js:383:17)

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.
3. npm run uap - Use Maddox to Unit Tests and Performance metrics.
4. npm run lint - Run linter.
5. 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.

Errr

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

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.

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.

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])](#new_Error_new)
* [.debug(params, [shouldDebug])](#Error+debug) ⇒ ErrorBuilder
* [.set(key, value, [force])](#Error+set) ⇒ ErrorBuilder
* [.setAll(object, [force])](#Error+setAll) ⇒ ErrorBuilder
* .appendTo(err) ⇒ ErrorBuilder
* .get() ⇒ Error
* .throw()

$3

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. |

$3

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. |

$3

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. |

$3

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. |

$3

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. |

$3

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.

$3

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])](#Errr.newError) ⇒ FromMessage
* ~~.fromError(err) ⇒ FromError~~

$3

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. |

$3

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

$3

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

$3

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. |