locustjs-exception

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

Exception class

Exception class provides a better and more meaningful error compared to javascript's internal object. It is a base class from which all business exceptions should be derived.

constructor

Exception(settings)

parameters:

• settings: an Exception, Error or custom object.

Properties

It has the following 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 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	The 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 with its inner exception into a string separated by given separator (default = \n).
• flatten(): converts he hierarchy of the exception and its inner exceptions into an 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
• ArgumentNullException
• ArgumentEmptyException
• NotInstanceOfException
• InvalidHttpMethodException

StackTrace

This utility class processes a string stack-trace value and populates a list of StackTraceItem objects to facilitate working with a stack-trace information.

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

This utility class 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()

• 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()

• throwIfNull(arg, argName, host)

  checks whether arg is null or not and if so, it throws a new ArgumentNullException().

• throwIfEmpty

  checks whether arg is empty or not and if so, it throws a new ArgumentEmptyException().

• throwNotImplementedException

  throws a new NotImplementedException()

• throwPropertyReadOnlyException

  throws a new PropertyReadOnlyException()

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 approach 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.'))

example 2:

function f1(a) {
	if (a == null) {
		throw new ArgumentNullException('a');
	}
	
	return a.length
}
function f2(a) { console.log(f1(a)) }

 Try(f1)
.Catch(ArgumentNullException, e => console.log(e.message)
.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');