@yo1dog/cerror v2.1.1

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])

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)

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)

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)

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

Equivalent to:

err[CError.origStackSymbol]

CError.getRootError(err)

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)

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)

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)

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)

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])

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

CError.isChainable(val)

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.