Exception Tree

This library makes it easy to produce error messages that clearly indicate where the problem exists.

This library is different from an Error's stack trace because it does not tell you where in the code the error is. Instead, it produces a message that is easily human readable, can target problems within nested structures, and can join multiple problems into a single error. This library shines when it comes to validating configurations.

Example

This example shows two errors:

1. One at one > two > a as Error 1
2. Another at one > two > b > 0 as Error 2

const { Exception } = require('exception-tree')

const exception = new Exception('Header 1')
const subException = exception.at('one').at('two')
subException.at('a').message('Error 1');
subException.at('b').at(0).message('Error 2');

console.log(exception)
// Header 1
//   at: one > two
//     at: a
//       Error 1
//     at: b > 0
//       Error 2

Instance Properties

count

Exception.count : number

The number of messages added to an Exception, including those added to any child Exception instances.

Example

const { Exception } = require('exception-tree')

const parent = new Exception('Header 1')
parent.message('Parent message')

const child = parent.at('x')
child.message('Child message')

console.log(parent.count) // 2
console.log(child.count)  // 1

hasException

Exception.hasException : boolean

Whether an Exception instance has any messages or not.

Example

const { Exception } = require('exception-tree')

const exception = new Exception('Header 1')
console.log(exception.hasException) // false

exception.message('Failed to compute')
console.log(exception.hasException) // true

Instance Methods

at

Exception.prototype.at ( path: string ) : Exception

Use this method to create a child exception that indicates a sub path. This differs from the nest function in that it creates a shared Exception space where the provided path is the key.

Parameters:

Parameter	Description	Type	Default
path	The label for the sub path being created.	string

Returns: The child Exception instance

Example

const { Exception } = require('exception-tree')
const exception = new Exception('Header 1')

const subPathException = exception.at('some path')
subPathException.message('No soup for you')

console.log(exception)
// Header 1
//   at: some path
//     No soup for you

nest

Exception.prototype.nest ( header: string ) : Exception

Use this method to create a child exception. Unlike the at function, this will not share messages with other nested exceptions that share the same header value.

Parameters:

Parameter	Description	Type	Default
header	The label for the sub Exception instance being created.	string

Returns: The child Exception instance

Example

const { Exception } = require('exception-tree')
const exception = new Exception('There was an error')

const subException = exception.nest('Could not do action X')
subException.message("I'm a teapot")
subException.message('Too busy to comply')

console.log(exception)
// There was an error
//   Could not do action X
//     I'm a teapot
//     Too busy to comply

message

Exception.prototype.message ( message: string [, code: string [, reference: string ]] ) : Exception

Add a message to the Exception instance. Once a message is added then the Exception instance is considered to have an exception.

Parameters:

Parameter	Description	Type	Default
message	The message to add.	string
code	An optional error code to associate with the message. The codes will only show if config.showCodes is set to true. This parameter will be required if config.requireCodes == true.	string
reference	An optional reference string citing where correct operation is defined. This could be a URL.	string

Returns: The Exception instance that the message was added to

Example

const { Exception } = require('exception-tree')

const exception = new Exception('Header 1')
exception.message('Message 1')

console.log(exception)
// Header 1
//   Message 1

push

Exception.prototype.push ( value: Exception ) : Exception

This method can be used to add an EnforcerInstance object to another EnforcerInstance.

Parameters:

Parameter	Description	Type	Default
value	An Exception instance to add as a child to this Exception instance.	Exception

Returns: The Exception instance that was passed in

Example

const { Exception } = require('exception-tree')

const child = new Exception('Header 2')
child.message('Message 2')

const parent = new Exception('Header 1')
parent.push(child)

console.log(exception)
// Header 1
//   Header 2
//     Message 2

toString

Exception.prototype.toString () : string

Get the error message that represents the Exception instance. If the Exception instance and its children have no messages then this will return an empty string, otherwise it will show the error(s) in an organized hierarchy.

Parameters:

None

Returns: a string

Global Configuration

The global configuration allows you to affect the behavior of the exception library.

There are two ways to set the global configuration properties, both of which are demonstrated in the following example.

const { Exception, config } = require('exception-tree')

config.displayCodes = false
Exception.config.requireCodes = true

Property	Description	Type	Default
displayCodes	Set to true to display message codes along with messages. This is especially useful to allow users to specify skipCodes, another global configuration option.	boolean	true
displayReferences	Set to true to display references along with messages.	boolean	true
requireCodes	This option is useful for the developer who is producing exception messages. If you'd like to require that calling the message method includes the code parameter then set this to true.	boolean	false
skipCodes	This option is useful for whoever receives the exceptions. Specify any codes that you'd like to not have added to the exception's message list. This is especially useful if you're using this library to produce warning messages.	string[]	[]