npm:generic-exceptions

README

generic-exceptions provides some generic exception classes and useful methods to check and handle some typical programming errors.

📘 Documentations

Version	Changes
3.0.0	Moved some basic features of `Exception` to the new class: `InvalidValue` New feature: formatting the message
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`

Author

Satoshi Soma

Usage no npm install needed!