event-system

Node.js Event class system

Event class system has been developed for systematize event logging. You have three base classes:

• ErrorEvent;
• InfoEvent;
• WarningEvent.

All classes can be found at EventSystem.events. Each class can be inherited by calling static method .extend from class. Each class can be instantiated via new.

Quick start example

Install it

npm install --save event-system

Require and use

const EventSystem = require("event-system");
 
EventSystem.setOutput(EventSystem.events.ErrorEvent, process.stderr); // setting output stream
let myError = new EventSystem.events.ErrorEvent(); // creating error event
EventSystem.log(myError); // logging event

As result, you will see same output:

Tue Jul 04 2017 12:27:34 GMT+0300 (MSK) - Error:
Stacktrace:
        at constructor.BaseEvent (/home/bymsx/Documents/logger/lib/logger/lib/events.js:12:29)
        at new constructor (/home/bymsx/Documents/logger/lib/logger/lib/events.js:38:23)
        at Object.<anonymous> (/home/bymsx/Documents/logger/test.js:4:15)
        at Module._compile (module.js:571:32)
        at Object.Module._extensions..js (module.js:580:10)
        at Module.load (module.js:488:32)
        at tryModuleLoad (module.js:447:12)
        at Function.Module._load (module.js:439:3)
        at Module.runMain (module.js:605:10)
        at run (bootstrap_node.js:422:7)
        at startup (bootstrap_node.js:143:9)
        at bootstrap_node.js:537:3

Note: header of that message will be red.

Inheritance and event fields

Events have fields which describe event.

Name	Type	Description	Inheritance
header	String	Name of event	increases
description	String	Short description of event	replaces
timestamp	Date	Time when event instantiated	-
stack	Array	Stacktrace	-
data	Object	Additional data, you can use it as you want	increases

Column 'Inheriting' means that field can be replaced, such as description and increased such as name. Here's an example:

Value	FileSystemErrorEvent	FileNotFoundErrorEvent
header	'Error FileSystem'	'Error FileSystem FileNotFound'
description	'Error in IO'	'File not found'
data	{ someData: true }	{ someData: true, code: -1 }

As you see, header has a name from base class and the name from child class, provided to .extend.

Event's data

Field data has type Object and designed as storage for any information about event, such as filename of file not found error. It increases by inheritance and by constructor. Here's an example:

const EventSystem = require("event-system");
const fs = require("fs");
 
const FileSystemErrorEvent = EventSystem.events.ErrorEvent.extend('FileSystem', 'Error in IO', { someData: true });
const FileNotFoundErrorEvent = FileSystemErrorEvent.extend('FileNotFound', 'File not found', { code: -2 });
 
EventSystem.setOutput(EventSystem.events.ErrorEvent, process.stderr);
 
fs.readFile('UNKNOWN_PATH', function (err, data) {
    if (err) {
        EventSystem.log(new FileNotFoundErrorEvent({ filename: err.path }));
    } else {
        // do anything else
    }
});

In result, data will contains:

{ someData: true, code: -1, filename: 'UNKNOWN_PATH' }

So, if you needn't provide data into constructor, you can call it without arguments:

new FileNotFoundErrorEvent();

Also you can call .extend without data:

const FileSystemErrorEvent = EventSystem.events.ErrorEvent.extend('FileSystem', 'Error in IO');

BaseEvent#serialize

Serialize method called to transform data field before output. By defaults, .serialize returns JSON-string, generated from data. You can override this function when calls .extend. Here's example:

function FileSystemSerialize () {
    return `File: ${this.data.filename}, code: ${this.data.code}`;
}
 
const FileSystemErrorEvent = EventSystem.events.ErrorEvent.extend('FileSystem', 'Error in IO', FileSystemSerialize);

Now you can instantiate event, call log and in output you will see you prepared message instead of JSON-string.

BaseEvent#extend

This function accepts four arguments:

• header;
• description;
• serialize;
• data.

Header and description are mandatory arguments, but serialize and data you can combine in any order.

FileSystemErrorEvent = EventSystem.events.ErrorEvent.extend('FileSystem', 'Error in IO', { someData: true }, function () {}); // works fine

or

FileSystemErrorEvent = EventSystem.events.ErrorEvent.extend('FileSystem', 'Error in IO', function () {}, { someData: true }); // also works fine

Output and logging

Event system provides a logger for events.

EventSystem#setOutput

You can set output stream for each of three base classes. Function setOutput has two parameters:

• Base class;
• Output stream. Output stream must be an instance of Stream.Writable. Here's an example.

const fs = require("fs");
 
EventSystem.setOutput(EventSystem.events.ErrorEvent, process.stderr);
EventSystem.setOutput(EventSystem.events.WarningEvent, process.stderr);
EventSystem.setOutput(EventSystem.events.InformationEvent, fs.createWriteStream('./events.log'));

If you call setOutput with invalid arguments, it will throw an Error.

EventSystem#log

This function accepts one argument - instance of event. It logs information about event into stream, which specified for this type of event. If output stream isn't specified, event won't logged. If argument isn't instance of Event (or inherited), it will throw an Error. Example:

EventSystem.log(new EventSystem.events.ErrorEvent());

EventSystem#setUseColors

Here you can enable or disable colored output. Available modes are: true (enabled) and false (disabled). You can set it for all output and for each stream severally.

EventSystem.setUseColors(true); // Enable colors for ALL output
EventSystem.setUseColors(EventSystem.events.ErrorEvent, false); // Disable colors for ErrorEvent's output

If you call setUseColors with invalid arguments, it will throw an Error.

EventSystem#setPrintStackTrace

Same as #setUseColors, but for stacktrace.

EventSystem.setPrintStackTrace(true); // Enable stacktrace for all output
EventSystem.setPrintStackTrace(EventSystem.events.ErrorEvent, false); // Disable stacktrace for ErrorEvent's output

Testing

For tests you can run npm test. If you need extra output, follow the mocha documentation.

Bugs, Wishes, etc.

Now I haven't any bugtracker, so you can contact me by e-mail: [e-mail]

I will be glad to see your feedback.