node-cerror

Chainable Errors

npm install @yo1dog/cerror

Quick Start

const {CError} = require('@yo1dog/cerror');
const {MyError} = require('MyError');

const sysErr = new Error('system failure');

// chain with CError class
console.log(
  new CError(sysErr, 'Unable to do thing A.')
);

/*
CError: Unable to do thing A.
    at readme.js:6:51
    at Script.runInThisContext (vm.js:123:20)
    ...
    
----- Caused By -----

Error: system failure
    at readme.js:4:16
    at Script.runInThisContext (vm.js:123:20)
    ...
*/

// chain custom/any error classes
console.log(
  CError.chain(sysErr, new MyError('Unable to do thing B.'));
)

/*
MyError: Unable to do thing B.
    at readme.js:7:34
    at Script.runInThisContext (vm.js:123:20)
    ...
    
----- Caused By -----

Error: system failure
    at readme.js:4:16
    at Script.runInThisContext (vm.js:123:20)
    ...
*/

// chain non-Error instances
const errObj = {status:500};

console.log(
  new CError(errObj, 'Unable to do thing C.')
);

/*
MyError: Unable to do thing C.
    at readme.js:7:34
    at Script.runInThisContext (vm.js:123:20)
    ...
    
----- Caused By -----

(type: object, constructor: Object) {status: 500}
*/

Docs

new CError(cause, [message])

param | type | description ----------|--------|------------- cause | Error | The cause of this Error. message | string | A human-readable description of the error.

Creates an error with a cause.

Equivalent to:

CError.chain(cause, new Error(message))

CError.prototype.getCause()

Returns the cause of this error (the next error in the chain).

Equivalent to:

this[CError.causeSymbol]
CError.getCause(this)

CError.prototype.getUnchainedStack()

Returns the original stack of this error before it was chained.

Equivalent to:

this[CError.origStackSymbol]
CError.getUnchainedStack(this)

CError.chain(...errs)

param | type | description -------|---------|------------- errs | Error[] | Errors to chain together.

Chains together errors such that the first error is the root cause and the last error is the result.

Returns the last error.

CError.getCause(err)

param | type | description -------|-------|------------- err | Error | Start of error chain to traverse.

Returns the cause of the given error (the next error in the chain).

Equivalent to:

err[CError.causeSymbol]
CError.getChain(err)[1]

CError.getUnchainedStack(err)

param | type | description -------|-------|------------- err | Error | Error in chain.

Returns the original stack of the given error before it was chained.

Equivalent to:

err[CError.origStackSymbol]

CError.getRootError(err)

param | type | description -------|-------|------------- err | Error | Start of error chain to traverse.

Returns the root error of the given error's chain.

Note: If the given error does not have a cause, the given error is the root and is returned.

Equivalent to

CError.getChain(err).pop()

CError.getChain(err)

param | type | description -------|-------|------------- err | Error | Start of error chain to traverse.

Returns the given error's chain of errors as an array.

Note: the chain contains the given error at index 0.

Equivalent to

Array.from(CError.getChainIterator(err, true))

CError.findInChain(err, callback)

param | type | description -----------|----------|------------- err | Error | Start of error chain to traverse. callback | function | Testing function.

Callback params: param | type | description --------|--------|------------- err | Error | Current error in chain. depth | number | Current depth in chain.

Returns the first error in the given error's chain that satisfies the given testing function.

Similar to except the arguments passed to callback differ slighty:

CError.getChain(err).find(callback)

CError.getFirstInstanceOf(err, constructor)

param | type | description --------------|----------|------------- err | Error | Start of error chain to traverse. constructor | function | Testing function.

Returns the first error in the given error's chain that is an instance of the given constructor.

Equivalent to:

CError.findInChain(err, err => err instanceof constructor)

CError.getErrorAt(err, depth)

param | type | description --------|--------|------------- err | Error | Start of error chain to traverse. depth | number | Depth to traverse to.

Returns the error in the given depth in the given error's chain.

A depth of 0 will return the given error. 1 will return the given error's cause. etc.

Similar to except this function will traverse circular references (won't throw an error):

CError.getChain(err)[depth]

CError.getChainIterator(err, [checkCircular])

param | type | description ----------------|---------|------------- err | Error | Start of error chain to traverse. checkCircular | boolean | If an error should be thrown on circular references (true) or not (false). Defaults to false.

Returns an interator that traverses the given error's chain.

CError.isChainable(val)

param | type | description -------|-------|------------- val | any | Value to check.

Returns if the given value can store a cause and be at the end or middle of a chain.

CError.causeSymbol

Symbol for accessing the cause of an error.

CError.origStackSymbol

Symbol for accessing the original stack of an error before it was chained.