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