@locustjs/exception

This library provides a base Exception class and a TryCatch utlity class with three Try(), Catch() and Finally() functions.

Current Version

2.2.0

Installation

NPM

npm i @locustjs/exception

Yarn

yarn add @locustjs/exception

Exception class

Exception class provides a better and more meaningful error compared to javascript errors. It is a base class from which all business exceptions could be derived.

constructor

Exception(settings)

parameters:

• settings: an Exception instance, javascript Error object or a custom object in the shape of such errors.

Properties

|Property|Type|Description |example |default| |--|--|--|--|--| | name |string|exception name| ArgumentNullException |exception class name| | baseName |string| Error object from which the exception is created| | undefined| | message |string| exception or error message|argument 'a' is null or undefined |empty string| | code |number| error code|200500 |undefined| | status |string| status code|argument-is-null |empty string| | host |string| Hosting application from which the exception is raised | Chrome58.0|undefined| | date |Date| date/time the exception is raised |2020-09-15T13:24:42|new Date()| | data |object |custom data included with the exception|{ fn: 'John', ln: 'Doe'}|null| | stack | string |function call stack at the time the exception was raised||Error.captureStackTrace()| | stackTrace | StackTrace |a helper StackTrace object that simplifies iterating in the stack info||null| | innerException |Exception|an exception by which current exception is raised | |null| | fileName |string|name of the javascript source file in which the exception was raised | myapp.js|undefined| | lineNumber |number |line number in the javascript source file in which the exception was raised|12|undefined| | columnNumber |number |column number in the javascript source file in which the exception was raised|5|undefined|

Methods

• toString(separator): converts the exception including its inner exception(s) hierarchy to a string separated by given separator (default = \n).
• flatten(): converts the hierarchy of inner exceptions to a flattened array.

example 1:

	const ex = new Exception({
		message: 'calling web api failed',
		code: 100324,
		status: 'call-api-failed',
		data: { url: '/api/v1/product', method: 'POST' data: { id: 1, title: 'Product II' } }
	});

example 2:

	try {
		var f;

		console.log(f.test())
	} catch (e) {
		const ex = new Exception(e);

		console.log(JSON.stringify(e));
	}

/*
{
 "name": "Exception",
 "baseName": "TypeError",
 "message": "Cannot read property 'test' of undefined",
 "stack": "TypeError: Cannot read properties of undefined (reading 'test')
    at foo (file:///C:/path/to/my/app/test.html:46:7)
    at HTMLButtonElement.<anonymous> (file:///C:/path/to/my/app/test.html:51:7)
    at HTMLButtonElement.dispatch (https://code.jquery.com/jquery-1.8.3.min.js:2:38053)
    at HTMLButtonElement.u (https://code.jquery.com/jquery-1.8.3.min.js:2:33916)",
 "stackTrace": {
 "items": [
	  {
	   "line": 46,
	   "col": 7,
	   "callSite": "foo",
	   "source": "file:///C:/path/to/my/app/test.html",
	   "message": "    at foo (file:///C:/path/to/my/app/test.html:46:7)"
	  },
	  {
	   "line": 51,
	   "col": 7,
	   "callSite": "HTMLButtonElement.<anonymous>",
	   "source": "file:///C:/path/to/my/app/test.html",
	   "message": "    at HTMLButtonElement.<anonymous> (file:///C:/path/to/my/app/test.html:51:7)"
	  },
	  {
	   "line": 2,
	   "col": 38053,
	   "callSite": "HTMLButtonElement.dispatch",
	   "source": "https://code.jquery.com/jquery-1.8.3.min.js",
	   "message": "    at HTMLButtonElement.dispatch (https://code.jquery.com/jquery-1.8.3.min.js:2:38053)"
	  },
	  {
	   "line": 2,
	   "col": 33916,
	   "callSite": "HTMLButtonElement.u",
	   "source": "https://code.jquery.com/jquery-1.8.3.min.js",
	   "message": "    at HTMLButtonElement.u (https://code.jquery.com/jquery-1.8.3.min.js:2:33916)\""
	  }
	 ]
	},
 "innerException": null,
 "data": null,
 "date": "2022-10-16T11:42:10.223Z"
}
*/

Derived classes

• PropertyReadOnlyException
• AbstractInstantiationException
• NotImplementedException
• NotSupportedException
• IndexOutOfRangeException
• ValueNotBetweenException
• ValueIsBetweenException
• ArgumentNullException
• ArgumentUndefinedException
• ArgumentNullOrUndefinedException
• ArgumentNullOrEmptyException
• ArgumentEmptyException
• ArgumentNothingException
• ArgumentTypeIncorrectException
• PropertyMissingException
• ComparisonFailedException
• NotInstanceOfException
• InvalidValueException
• InvalidHttpMethodException

StackTrace

Processes a stack-trace value and populates a list of StackTraceItem objects to facilitate working with a stack-trace information.

By default, Exception class processes stackTrace of a javascript Error object into a StackTrace instance.

constructor

	StackTrace(stackTrace: string)

parameters:

• stackTrace: strack trace of a javascript error object

Properties

|Property|Type|Description| |--|--|--| | items |StackTraceItem| List of stack-trace items|

example:

	const st = new StackTrace(`"TypeError: Cannot read properties of undefined (reading 'test')
    at foo (file:///C:/path/to/my/app/test.html:46:7)
    at HTMLButtonElement.<anonymous> (file:///C:/path/to/my/app/test.html:51:7)
    at HTMLButtonElement.dispatch (https://code.jquery.com/jquery-1.8.3.min.js:2:38053)
    at HTMLButtonElement.u (https://code.jquery.com/jquery-1.8.3.min.js:2:33916)"`);

	console.log(JSON.stringify(st, null, ' '));

/*
{
 "items": [
  {
   "line": 46,
   "col": 7,
   "callSite": "foo",
   "source": "file:///C:/path/to/my/app/test.html",
   "message": "    at foo (file:///C:/path/to/my/app/test.html:46:7)"
  },
  {
   "line": 51,
   "col": 7,
   "callSite": "HTMLButtonElement.<anonymous>",
   "source": "file:///C:/path/to/my/app/test.html",
   "message": "    at HTMLButtonElement.<anonymous> (file:///C:/path/to/my/app/test.html:51:7)"
  },
  {
   "line": 2,
   "col": 38053,
   "callSite": "HTMLButtonElement.dispatch",
   "source": "https://code.jquery.com/jquery-1.8.3.min.js",
   "message": "    at HTMLButtonElement.dispatch (https://code.jquery.com/jquery-1.8.3.min.js:2:38053)"
  },
  {
   "line": 2,
   "col": 33916,
   "callSite": "HTMLButtonElement.u",
   "source": "https://code.jquery.com/jquery-1.8.3.min.js",
   "message": "    at HTMLButtonElement.u (https://code.jquery.com/jquery-1.8.3.min.js:2:33916)\""
  }
 ]
}
*/

StackTraceItem

Processes one line of a stack-trace information and presents it as an object by extracting its details.

constructor

	StackTraceItem(line: string)

parameters:

• line: one line of a stack-trace information

Properties

|Property|Type|Description| |--|--|--| | line |number| line number of error | | col |number| column number of error | | callSite |string| function name at which the error was raised | | source |string| file name the error was raised at | | message |string| given error info |

example:

	let sti;
	
	sti = new StackTraceItem(`"	at foo (file:///C:/path/to/my/app/test.html:46:7)"`);

	console.log(JSON.stringify(sti, null, ' '));
	/*
	{
		line: 46,
		col: 7,
		callSite: "foo",
		source: "file:///C:/path/to/my/app/test.html"
	}
	*/

	sti = new StackTraceItem(`"	    at <anonymous>:1:10"`);

	console.log(JSON.stringify(sti, null, ' '));
	/*
	{
		line: 1,
		col: 10,
		callSite: "<anonymous>",
		source: ""
	}
	*/

Utility functions

throwIfInstantiateAbstract(classType, instance, host)

Checks whether classType is an abstract class and if so, throws a new AbstractInstantiationException.

class MyAbstractClass {
	constructor() {
		throwIfInstantiateAbstract(MyAbstractClass, this)
	}
	...
}
class MyConcreteClass extends MyAbstractClass {
	...
}

let obj = new MyAbstractClass();   // throws AbstractInstantiationException

throwIfNotInstanceOf(argName, classType, instance, ignoreNull = false, host = '')

Checks whether given object is an instance of the specified classType. If not, it throws a new NotInstanceOfException.

class FooBase {
	get Code() {
		return this._code;
	}
	set Code(value) {
		this._code = value;
	}
	...
}
class Foo extends FooBase {
	...
}

function validate(f) {
	throwIfNotInstanceOf(f, FooBase);   // make sure f is an instance of FooBase

	// f is a FooBase object. so, it definitely has a 'Code' prop.
	
	if (f.Code.length < 3) {
		...
	}
}

• throwNotImplementedException(method, host) This method is mainly used in abstract classes and throws a new NotImplementedException exception to show that child classes have to implement the method.

class FooBase {
	doSomething() {
		throwNotImplementedException(`${this.constructor.name}.doSomething`)
	}
	...
}

• throwIfNull(arg, argName, host) Checks arg and throws a ArgumentNullException exception if arg is null.

class FooBase {
	doSomething(foo) {
		throwIfNull(foo, 'foo')

		...
	}
	...
}

• throwIfUndefined(arg, argName, host) Checks arg and throws a ArgumentUndefinedException exception if arg is undefined.

class FooBase {
	doSomething(foo) {
		throwIfUndefined(foo, 'foo')

		...
	}
	...
}

• throwIfNullOrUndefined(arg, argName, host) Checks arg and throws a ArgumentNullOrUndefinedException exception if arg is null or undefined.

class FooBase {
	doSomething(foo) {
		throwIfNullOrUndefined(foo, 'foo')

		...
	}
	...
}

• throwIfNullOrEmpty(arg, argName, host) Checks arg and throws a ArgumentNullOrEmptyException exception if arg is null, undefined or zero-length string.

class FooBase {
	doSomething(foo) {
		throwIfNullOrEmpty(foo, 'foo')

		...
	}
	...
}

• throwIfEmpty Checks arg and throws a ArgumentEmptyException exception if arg is empty (null, undefined or empty strings).

class FooBase {
	doSomething(foo) {
		throwIfEmpty(foo, 'foo')

		...
	}
	...
}

• throwIfNothing Checks arg and throws a ArgumentNothingException exception if arg is empty (null, undefined, empty string or emty object).

class FooBase {
	doSomething(foo) {
		throwIfNothing(foo, 'foo')

		...
	}
	...
}

• throwIfTypeIncorrect(arg, argName, typeOrCheckType, host) Checks arg and throws a ArgumentTypeIncorrectException exception if arg's type does not match typeOrCheckType'.

typeOrCheckType could be a string specifying the type to be checked or a custom function that checks type matching.

Intrinsic supported types:

• number: number
• number+: non-zero number
• numeric: number or a string containing a number
• int or integer : integer
• int+ or integer+: a non-zero integer
• float: float
• float+: non-zero float
• string: string
• string+: non-zero length string
• bool: bool
• bool*: bool or a non-trimmed string containing true, false, True, False, TRUE, FALSE
• bool#: bool or a string containing true, false, True, False, TRUE, FALSE
• bool^: bool or a string containing true, false, True, False
• bool!: bool or a string containing true, false
• array: array
• array+: non-zero length array
• object: object
• object+: non-empty object
• date: date
• function: function
• basic: number, string, bool, date
• primitive: basic data type or instances of Number, String, Boolean, Date
• other: arg should be an instance of

class Foo { }
class Bar { }
...
function doSomething(a, b, c, d, e) {
	throwIfTypeIncorrect(a, 'a', 'Foo')
	throwIfTypeIncorrect(b, 'b', 'bool')
	throwIfTypeIncorrect(c, 'c', 'number')
	throwIfTypeIncorrect(d, 'd', 'string')
	throwIfTypeIncorrect(e, 'e', x => x instanceof Bar)
	...
}

By default, throwIfTypeIncorrect requires the argument not to be null or undefined. Using the ? suffix, we can make the argument optional.

function doSomething(a, b) {
	throwIfTypeIncorrect(a, 'a', 'number?')
	throwIfTypeIncorrect(b, 'b', 'string+?')
	...
}

List of helpers created over throwIfTypeIncorrect:

• throwIfNotNumber
• throwIfNotSomeNumber
• throwIfNotNumeric
• throwIfNotBool
• throwIfNotHasBool
• throwIfNotString
• throwIfNotSomeString
• throwIfNotDate
• throwIfNotObject
• throwIfNotSomeObject
• throwIfNotFunction
• throwIfNotInt
• throwIfNotSomeInt
• throwIfNotFloat
• throwIfNotSomeFloat
• throwIfNotArray
• throwIfNotSomeArray
• throwIfNotBasic
• throwIfNotPrimitive
• throwIfNotInShape

All of the helpers, except throwIfNotInShape have the following signature:

fn(arg, argName, host)

example:

function sum(arr, fromIndex, toIndex) {
	throwIfNotArray(arr, 'arr')
	throwIfNotNumber(fromIndex, 'fromIndex')
	throwIfNotNumber(toIndex, 'toIndex')

	// we are safe here
	...
}

throwIfNotInShape signature is as follows:

throwIfNotInShape(arg, argName, shape, host) example:

function validate(person) {
	throwIfNotInShape(person, 'person', {
		firstName: 'string+?',	// not required
		lastName: 'string+',	// required
		age: 'int?',	// not required
		phone: {
			required: true,
			validate: x => /^\d+$/.test(x)
		},
		location: {
			shape: {
				country: 'string',
				city: 'string'
			}
		},
		scores: {
			array: true,
			type: 'int',
			validate: x => x >= 0 && x <= 100
		}
	})

	// we are safe here
	...
}

• throwIfIndexOutOfRange(index, min, max, host) Checks index and throws a IndexOutOfRangeException exception if index is not between min (inclusive) and max (exclusive).

class Foo { }
...
function concat(arr, from, to) {
	throwIfIndexOutOfRange(from, `from`, 0, arr.length);
	throwIfIndexOutOfRange(to, `to`, 0, arr.length);
	...
}

• throwIfMissingProperty(obj, objName, prop, host) Checks whether obj contains a property named prop and if not throws a PropertyMissingException exception.

...
function login(credentials) {
	throwIfMissingProperty(credentials, `credentials`, 'username');
	throwIfMissingProperty(credentials, `credentials`, 'password');
	...
}

• throwIfComparisonFailed(arg) Checks arg.a and arg.b and throws a ComparisonFailedException exception if comparing arg.a and arg.b based on arg.operator does not succeed.

Structure of arg:

{
	a: 10,
	b: 20,
	operator: '<'
}

Example:

...
function concat(arr, from, to) {
	throwIfComparisonFailed({ a: from, b: to, operator: '>' });
	...
}

List of helpers created over throwIfComparisonFailed:

• throwIfLessThan(a, b)
• throwIfLessThanOrEqualTo(a, b)
• throwIfGreaterThan(a, b)
• throwIfGreaterThanOrEqualTo(a, b)
• throwIfEqualTo(a, b)
• throwIfNotEqualTo(a, b)
• throwIfTypeEqualTo(a, b)
• throwIfNotTypeEqualTo(a, b)
• throwIfNotBetween(x, from , to)
• throwIfBetween(x, from , to)

Example:

...
function concat(arr, from, to) {
	throwIfGreaterThan(from, to);
	...
}

Try/Catch/Finally

examples

Assume we have the following functions:

function f1(a) { return a.length }
function f2(a) { console.log(f1(a)) }

The ordinary try/catch block is this way:

	try {
		f2();
	} catch (e) {
		console.log(e);
	} finally {
		console.log('Finished.')
	}

Here is various examples of using Try/Catch:

Example 1 (basic):

 Try(_ => f2())
.Catch(e => console.log(e))
.Finally(_ => console.log('Finished.'))

Try/Catch provides multiple catch ability, a feature javascript try/catch does not support.

Example 2:

function f1(a) {
	if (a === null) {
		throw new ArgumentNullException('a');
	} else if (a === undefined) {
		throw new ArgumentUndefinedException('a');
	} else if (!isSomeString(a)) {
		throw new ArgumentTypeIncorrectException('a', 'string');
	}
	
	return a.length
}

function f2(a) {
	console.log(f1(a))
}

 Try(f1)
.Catch(ArgumentNullException, console.log)
.Catch(ArgumentUndefinedException, console.log)
.Catch(ArgumentTypeIncorrectException, console.log)
.Catch(e => console.log(`Other exception raised: ${e}`))	// this Catch() is not triggered
.Finally(_ => console.log('Finished.'))

Example 3: verbose

const x = Try(f2);

console.log('do something outside of previous Try');

x.Catch(e => console.log(e));
x.Finally(_ => console.log('Finished.'));

/* output:
TypeError: Cannot read property 'length' of undefined
    at f2 (<anonymous>:1:69)
    at f1 (<anonymous>:1:30)
    at TryCatch._fn (<anonymous>:1:19)
    at TryCatch.Run (<anonymous>:93:22)
    at Try (<anonymous>:161:16)
    at <anonymous>:1:9
    at <anonymous>:3:42
*/

Example 4: external catch (not possible using traditional try/catch)

function doSomething(a) {
	return Try(_ => {
		console.log(`name: ${a.name}`);
	});
}

doSomething()
	.Catch(e => console.log(e))
	.Finally('Finished');