/node-cerror

Chainable Errors

Primary LanguageTypeScript

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.