generic-exceptions provides some generic exception classes and useful methods to check and handle some typical programming errors.
Version | Changes |
---|---|
3.0.0 |
|
2.0.0 | New exception class: NoSuchProp
|
1.3.0 | Supported multiple expectations for .check()
|
Getting Started
Install via NPM:
npm i generic-exceptions
Then, require()
the exception classes that you want to use:
const { <ExceptionClass>, ... } = require('generic-exceptions');
Available Exceptions (v3.0.0+):
NoSuchProp
InvalidType
InvalidValue
Exception
APIs
Here is a small summary of APIs in generic-exceptions. The full documentations are here: https://amekusa.github.io/generic-exceptions/latest/
class Exception
Exception
class is the base class of all the other exceptions. That means every exception basically derives the methods and the properties from this class. Also Exception
is a subclass of Error.
constructor ( msg[, info] )
Assign any type of value to info
and you can access it as .info
property.
try {
throw new Exception('error', { reason: 'unknown' });
} catch (e) {
console.error(e.info.reason); // 'unknown'
}
.trigger ( )
Throws the instance if handler
option ( explained later ) is not set.
static .option ( name[, value] )
Returns the option value by name
. If value
is provided, assigns the value to the option instead of returning it.
You can customize the default behavior of Exception
at some level by changing the option values.
Available options:
Name | Type | Description |
---|---|---|
handler |
function | Runs when trigger() is called. Receives the triggered exception instance as the argument |
Exception.option('handler', e => {
console.error(e.message);
});
new Exception('error').trigger(); // This doesn't throw because of the handler
class InvalidType
Thrown to indicate that the type of a value isn't expected.
static .check ( value, expected[, ... ] )
Checks if the type of value
matches with expected
. If it doesn't match, triggers an InvalidType
exception instance. Otherwise, just returns value
.
The triggered exception holds value
and expected
as .info.checked
and .info.expected
.
And the actual type is stored in .info.actual
.
var X = 'ABC';
try {
InvalidType.check(X, 'string'); // OK
InvalidType.check(X, 'number'); // Throws
} catch (e) {
console.error(e.info);
// { checked:'ABC', expected:'number', actual:'string' }
}
Multiple expectations are also supported:
var X = 'ABC';
try {
InvalidType.check(X, 'number', 'string'); // OK (expects: number OR string)
InvalidType.check(X, 'boolean', 'object'); // Fails (expects: boolean OR object)
} catch (e) {
console.error(e.info);
// { checked:'ABC', expected:['boolean', 'object'], actual:'string' }
}
.expects()
method is useful for checking what type is expected for:
var X = 'ABC';
var expectations = ['boolean', 'object'];
try {
InvalidType.check(X, ...expectations); // Fails
} catch (e) {
if (e.expects('boolean')) { ... } // true
if (e.expects('object')) { ... } // true
if (e.expects('number')) { ... } // false
}
You can also check an object's class by passing a class constructor:
var obj = new String();
InvalidType.check(obj, String); // OK
var arr = [];
InvalidType.check(arr, Array); // OK
Additionally, InvalidType
supports some special type keywords that can be passed to expected
:
Type Keyword | Description |
---|---|
iterable |
Matches for iterable objects like Array , Map , etc. |
int , integer
|
Matches only for integer numbers. |
bool |
Alias of boolean
|