remie v0.1.5

REMIE (Rich Error Module Is Excellent)

Encapsulates additional information about an error that occurred in a standardized error object called a Remie error.

Installation

Install and save the Remie npm module to the package.json.

$ npm install --save remie

Usage

Create and configure an instance of Remie. Then create a new Remie error from a Node.js system error.

// Require the Remie module.
let Remie = require('remie');

// Create and configure a new instance of Remie.
let remie = new Remie();

let myVariable,
  error;

// Let's make an error occur.
try {
  myVariable.myMethod();
} catch(e) {
  // Create a Remie error to extend the information provided in the error object.
  error = remie.create(e, {
    level: Remie.ERROR_LEVEL_FATAL,  // Give it an error level e.g. warning or fatal
    referenceData: {                 // Hint at what data could have caused the error.
      myVariable: myVariable
    }
  });
}

The error can be converted to an object to be passed between internal services as JSON.

console.log(error.toObject());

The above command produces the following console logs:

{
  error: {
	  code: undefined,
		message: 'Cannot read property \'myMethod\' of undefined',
		stack: 'TypeError: Cannot read property \'myMethod\' of undefined\n    at Object.<anonymous> (/remie/examples/basic.js:17:13)\n    at Module._compile (module.js:541:32)\n    at Object.Module._extensions..js (module.js:550:10)\n    at Module.load (module.js:458:32)\n    at tryModuleLoad (module.js:417:12)\n    at Function.Module._load (module.js:409:3)\n    at Function.Module.runMain (module.js:575:10)\n    at startup (node.js:160:18)\n    at node.js:449:3'
	},
  internalOnly: false,
  internalMessage: undefined,
  level: 'fatal',
  messageData: undefined,
  referenceData: {
	  myVariable: undefined
	},
  statusCode: 500
}

The same object can then used to create a Remie error instance again.

let myRemieError = remie.create(error);

Or, you can sanitize the error and send it to a client.

console.log(error.sanitize());

The above command produces the following console logs:

{
  error: {
	  message: 'Cannot read property \'myMethod\' of undefined'
	},
  internalOnly: false,
	level: 'fatal',
	referenceData: {
	  myVariable: undefined
	},
	statusCode: 500
}

Table of Contents

• Examples
• Remie
  • Configure Remie
  • Error Levels
  • Events
  • Remie Methods
• Remie Error
  • Error Methods

• Tests

Remie

Remie Methods

The Remie instance is used to create Remie errors with a standard set of configurations. The following Remie methods are available.

• Copy
• Create
  • Create from String
  • Create from Locale
  • Create from Node.js Error
  • Create from Remie Error
• Create Internal
• Get
• Set

Create

Builds a new Remie error instance. You can build it from a string, i18next locale, Node.js error, or an existing Remie error object.

remie.create(error, options);

Create from String

Create a new Remie error object with a string as the error parameter. Pass along any additional configurations in the options object parameter.

let error = remie.create("Something went horribly wrong", {  level: Remie.ERROR_LEVEL_FATAL  });

Create from Locale

Create a new Remie error object with an i18next string locale as the error parameter. Pass along any additional configurations in the options object parameter.

Note: i18next must be configured and included in the remie instance to handle the translation lookup.

// Require and configure i18next.
let remie = new Remie({ i18next: i18next });

let error = remie.create("server.400.notFound", {  
  error: {
    code: "server.400.notFound"
  },
  "messageData": { page: "http://my.domain.com/this/page/doesnt/exist"}
});

Create from Node.js Error

Create a new Remie error object from an existing Node.js error as a parameter. Pass along any additional configurations in the options object parameter.

let myVariable = undefined;

// Let's make an error occur.
try {
  myVariable.myMethod();
} catch(e) {
  // Create a Remie error to extend the information provided in the error object.
  error = remie.create(e, {
    referenceData: {                 // Hint at what data could have caused the error.
      myVariable: myVariable
    }
  });
}

Create from Remie Error

Create a new Remie error object from an existing Remie error object as a parameter. Pass along any additional configurations in the options object parameter.

// Require and configure i18next.
let error1 = remie.create("something is wrong.");

let error2 = remie.create(error1, {
  internalMessage: "This is a copy of error1"
});

Create Internal

Same as create only the error will be marked as internal only by setting the internalOnly attribute to true.

remie.createInternal(error, options);

let error = remie.createInternal("Something went horribly wrong", {  level: Remie.ERROR_LEVEL_FATAL  });

copy

Make a copy of an existing Remie error instance.

remie.copy(error, options);

let error1 = remie.create("this is an error");
let error2 = remie.copy(error1);

set

Set an option in the Remie instance. Provide the option name and new value as parameters. See available Remie configurations.

remie.set(option, value);

remie.set("defaultErrorMessage", "An internal error has occurred.");

get

Get an option in the Remie instance by providing the option name as a parameter. See available Remie configurations.

remie.get(option);

let defaultErrorMessage = remie.get("defaultErrorMessage");

Events

Events are emitted by Remie using the standard Node.js EventEmitter. You can listen for these events.

let Remie = require('remie');

let remie = new Remie();

remie.on("MyEventHere", function() { /* Do Something Here */ });

ON_CREATE_INTERNAL_MESSAGE

Called when an internal message is added to a Remie error instance.

let Remie = require('remie');

let remie = new Remie();

remie.on(Remie.ON_CREATE_INTERNAL_MESSAGE, function(error, options) {
  console.log("[Internal Message]: " + error.internalMessage);
});

Error Levels

Remie includes several standard error levels that can be used to categorizing or logging errors. Remie uses the same error levels as node-bunyan.

You can access the error levels statically using the Remie npm module instance.

let Remie = require('remie');

console.log(Remie.ERROR_LEVEL_FATAL);

Note: You cannot access these on a remie instance, aka non-statically.

let Remie = require('remie');
let remie = new Remie();

Remie.ERROR_LEVEL_FATAL  // GOOD!  Works!    WOW!
remie.ERROR_LEVEL_FATAL  // BAD!   NO WORK!  WOW!

Configure Remie

You can configure the Remie instance at anytime using the following attributes:

To configure a Remie instance while being created pass values into the constructor as an object.

let remie = new Remie({
    defaultErrorMessage: "Oh crap!",
    defaultErrorStatusCode: 200       // Everything is ok, it's fine, really... no problems.
});

You can also change a configuration at anytime using the set method.

remie.set("defaultErrorStatusCode", 500);  // Nvm, it's bad, really bad.

Remie Error

• Attributes
• Methods

Remie Error Attributes

i18next Translations

When using i18next the locale will be placed in the error.code and options.messageData will contain any parameter keys/values included in the locale.

Remie Error Methods

• build
• get
• set
• sanitize
• toObject

Build

Builds the current Remie error instance. You can build it from a string, i18next locale, Node.js error, or an existing Remie error object. The Remie Create method calls this method internally, see the create method documentation for more details.

error.build(error, options, remie)

See the Create method documentation for more details.

• Create from String
• Create from Locale
• Create from Node.js Error

• Create from Remie Error

Error Get

Get an attribute in the Remie error instance by providing the attribute name as a parameter. See available Remie error attributes.

error.get(attribute);

Error Set

Set an attribute in the Remie error instance. Provide the attribute name and new value as parameters. See available Remie error attributes.

error.set(attribute, value);

error.set("internalOnly", true);

Sanitize

Convert the Remie error instance into a JSON object that can then be passed to a client or user. This removes attributes that are considered private or not needed by a client or user. Include an attributes name as the key with a value of false in the options parameter to exclude it from the returned sanitized object.

error.santitize(options);

toObject

Convert the Remie error instance into a JSON object. This object can be passed from system to system as JSON, then be used to recreate the Remie error instance again.

error.toObject();

Examples

A series of examples exist to help you understand how to use remie. They are all located in the examples folder. You can follow these steps to use and play with the examples.

1. Download or clone the repo.

   git clone https://github.com/livio/remie.git

2. Navigate to the examples folder.

   cd remie/examples

3. Install dependencies

   npm install

4. Run any example using node nameOfExampleFile.js

   node basic.js

Tests

Remie includes tests using the mocha framework. Run and ensure these tests pass before submitting code to a stable branch or finished pull-request.

1. Download or clone the repo.

   git clone https://github.com/livio/remie.git

2. Install dependencies

   npm install

3. Run the tests

   npm test