js-lang-exception v1.0.2
js-lang-exception
Synopsis
An extendable, testable and intuitively usable error-handling Exception class built and based on the standard, built-in Error object. Written in UMD.
Compatible with ECMAScript 6.
Install
npm install js-lang-exception
Usage - Include/Initialization
AMD (e.g.: RequireJS)
define(['js-lang-exception'], function(Exception) { // you can now use Exception });
CommonJS (e.g.: NodeJS)
var Exception = require('js-lang-exception'); // you can now use Exception
Browser
// load the source from "node_modules/js-lang-exception/dist/js-lang-exception.js" - for development // or from "node_modules/js-lang-exception/dist/js-lang-exception.min.js" - for production var Exception = js_lang_exception; // it is available in the global namespace // you can now use Exception
Usage - After Initialization
General usage:
// similar to the ordinary Error throw new Exception(); // with a custom message throw new Exception('With a custom message'); // custom message with arguments throw new Exception(['With a custom message and one argument: {}', 1]); throw new Exception(['With 2 arguments: {}, {}', 1, 2]); throw new Exception(['With multiple arguments: {} + {} = {}', 20, 22, 42]); // custom message with arguments - with direct indexing // will be "With directly addressed arguments: {3} - {2} - {1}" // **NOTE** - array indexing starts with 0 after the message, not 1, // so here the {2} will be 3, {1} will be 2 and lastly {0} will be the number 1 from the array throw new Exception(['With directly addressed arguments: {2} - {1} - {0}', 1, 2, 3]); // custom message + custom ID throw new Exception('With another message', 42); throw new Exception('With another message', 1001);
Advanced usage:
// custom message without arguments + custom ID + custom data throw new Exception('With another nice message', 1404, { custom : false, data : 1492 }); // **NOTE** - if an array is passed with the custom message only, // it will be just as if it would be passed as a string, chill and wonder ;) throw new Exception(['With another nice message'], 1404, { custom : false, data : 1492 }); // custom message with arguments + custom ID + custom data throw new Exception(['With another nice message with: {}, {} and {}', 1, 2, 3], 1404, { custom : false, data : 1492 }); // custom message + custom data - ignoring custom ID by passing **null** as an argument for the ID throw new Exception('With a message.', null, {custom : 'data'}); // custom ID + custom data - ignoring custom message by passing **null** as an argument for the message throw new Exception(null, 1984, {custom : 'data'}); // custom data - ignoring both custom message and custom ID throw new Exception(null, null, {custom : 'data'});
Advanced usage with custom exceptions
// subclassing - **ES5** function CustomException() { // call with the default values Exception.call(this); // also can be called with custom arguments Exception.call(this, 'Custom message', 1001, {custom : 'data'}); } CustomException.prototype = Object.create(Exception.prototype); CustomException.constructor = CustomException; try { throw new CustomException(); } catch (e) { // check whether custom message, custom ID and custom data was passed console.log(e.hasMessage()); console.log(e.hasID()); console.log(e.hasData()); // get custom message, ID and data console.log(e.getMessage()); console.log(e.getID()); console.log(e.getData()); // you can check them, these will be all === true console.log(e instanceof CustomException); console.log(e instanceof Exception); console.log(e instanceof Error); }
// subclassing - **ES6** class CustomException extends Exception { constructor() { // call with the default values super(); // also can be called with custom arguments super('Custom message', 1001, {custom : 'data'}); } } try { throw new CustomException(); } catch (e) { // check whether custom message, custom ID and custom data was passed console.log(e.hasMessage()); console.log(e.hasID()); console.log(e.hasData()); // get custom message, ID and data console.log(e.getMessage()); console.log(e.getID()); console.log(e.getData()); // you can check them, these will be all === true console.log(e instanceof CustomException); console.log(e instanceof Exception); console.log(e instanceof Error); }
Documentation
Check the source here since it's well structured and documented. Also you can find the rendered jsDoc documentation on Doclets.io.
Also, check the unit tests in order to grasp the full-fledged capabilities.
Have fun! ;)
Issues
If you find any bugs and other issues, check the GSDC Guide - Issues section on how to submit issues in a standardized way on the project's issues page.
In case you have any suggestions regarding the project (features, additional capabilities, etc.), check the GSDC Guide - Suggestions section on how to submit suggestions in an easy, standardized way on the project's issues page.
Contribution
In order to contribute to this project, check the GSDC Guide for an easy, standardized way on how to contribute to projects.
Support
If you by any means find this project useful, consider supporting the organization.
There are multiple options to support the project and the developers. Any means of support is beneficial and helpful.
License
MIT @ Richard King