safeevents
SafeEvents is a very simple event emitter with basic feature: this library prevents loops. This solution was developed for front-end usage, but can be used and on nodejs level.
npm
Install
Just attach library to your HTML page.
<script type="text/javascript" src="safeevents.js"></script>Or include it to project as a module
var SafeEvents = require('./safeevents.js')Using
You can use a library directly:
var safeevents = new SafeEvents();Or inherit functionality.
var instance = function () { };
SafeEvents.inherit(instance);
instance = new instance();You will get access to several methods:
- bind - bind your handle with some event;
- unbind - unbind handle from event;
- trigger - execute event;
- safely - wrapper for async callbacks Here is a simple example:
var safeevents = new SafeEvents();
safeevents.bind('A', function () {
window.console.log('Event A triggered');
});
safeevents.trigger('A');See more examples in folder "examples".
Anti-loop
A main feature of SafeEvents is: blocking of loops. SafeEvents checks a stack and if some event triggers itself, SaveEvents blocks a process (block loop), generates an exception (with a full stack, include async). Let's see on next example:
var safeevents = new SafeEvents();
safeevents.bind('A', function () {
safeevents.trigger('B');
});
safeevents.bind('B', function () {
safeevents.trigger('C');
});
safeevents.bind('C', function () {
safeevents.trigger('A');
});
safeevents.trigger('A');Event A triggers B; B -> C and C again A. This is a loop. But SafeEvents will block it and you will see in console something like this: "Uncaught Error: Event [A] called itself. Full chain: A, B, C". And sure, a full stack will available.
To prevent loops in async callbacks you should use a method "safely", like in next example:
var safeevents = new SafeEvents();
safeevents.bind('A', function () {
safeevents.trigger('B');
});
safeevents.bind('B', function () {
safeevents.trigger('C');
});
safeevents.bind('C', function () {
/*
* Use method "safely" to wrap your async methods and create safe callback.
*/
setTimeout(safeevents.safely(function () {
safeevents.trigger('A');
}), 10);
});
safeevents.trigger('A');Get full stack
If you did not use async callbacks, you will get a full stack in any case in your browser's console. If you used some async callbacks, you should activate in devTools async.
Prevention of exception
To prevent exception (on loop) you can attach a listener for such event.
var safeevents = new SafeEvents();
/*
* Test F. Classic loop. Prevent exception
* Events ordering: A -> B -> C -> A -> loop.
*
* Console: Uncaught Error: Event [A] called itself. Full chain: A, B, C
*/
safeevents.bind('A', function () {
safeevents.trigger('B');
});
safeevents.bind('B', function () {
safeevents.trigger('C');
});
safeevents.bind('C', function () {
safeevents.trigger('A');
});
safeevents.bind(safeevents.onloop, function (e, chain, last_event, stack) {
console.log('Error message: ' + e);
console.log('Full chain of events: ' + chain.join(', '));
console.log('Last event (generated loop): ' + last_event);
console.log('Error stack: ' + stack);
});
safeevents.trigger('A');Now your application will not be stopped, but a loop will be stopped in any case. Such feature can be useful on nodejs level, where we should keep the server alive. You can use this feature to make some logs or notifications.
Do not break loop
In case if you do not need break loop, you can listen [onloop] event and return as result [false]. In this case loop will not be stopped.
var safeevents = new SafeEvents(),
count = 0;
/*
* Test F. Classic loop. Prevent exception. Stop loop on 5th circle.
* Events ordering: A -> B -> C -> A -> loop.
*
* Console: Uncaught Error: Event [A] called itself. Full chain: A, B, C
*/
safeevents.bind('A', function () {
safeevents.trigger('B');
});
safeevents.bind('B', function () {
safeevents.trigger('C');
});
safeevents.bind('C', function () {
safeevents.trigger('A');
});
safeevents.bind(safeevents.onloop, function (e, chain, last_event, stack) {
console.log('Error message: ' + e);
console.log('Full chain of events: ' + chain.join(', '));
console.log('Last event (generated loop): ' + last_event);
console.log('Error stack: ' + stack);
console.log('This is circle #: ' + count++);
count > 5 && console.log('Breaking loop');
//Break loop if it's 5th circle
return count <= 5 ? false : true;
});
safeevents.trigger('A');In this example, loop will be stopped ather 5th circle of loop.
Event markers
SafeEvents creates event markers to make debug process easy. If you will take a look on examples/example_a in colsole you will find next information
trigger @ safeevents.js:29
(anonymous function) @ example_a.html:24
(anonymous function) @ safeevents.js:45
event_C_$$$0_1_2$ @ VM8802:2 //Marker for event "C"
(anonymous function) @ safeevents.js:44
setTimeout (async)
(anonymous function) @ safeevents.js:41
trigger @ safeevents.js:40
(anonymous function) @ example_a.html:21
(anonymous function) @ safeevents.js:45
event_B_$$$0_1$ @ VM8801:2 //Marker for event "B"
(anonymous function) @ safeevents.js:44
setTimeout (async)
(anonymous function) @ safeevents.js:41
trigger @ safeevents.js:40
(anonymous function) @ example_a.html:18
(anonymous function) @ safeevents.js:45
event_A_$$$0$ @ VM8800:2 //Marker for event "A"
(anonymous function) @ safeevents.js:44
setTimeout (async)
(anonymous function) @ safeevents.js:41
trigger @ safeevents.js:40
(anonymous function) @ example_a.html:26So, in console you see names of all events in chain. It will help you with debug process.
Changelog
0.0.1
- base version
0.0.2
- fix module property checking (prevent gulp conflict);
0.0.3
- cleanup correction
0.0.4
- optimization: removed try ... catch ... blocks
0.0.5
- optimization: cleanup
0.0.6
- refactoring: removed event's name limitation (name of event now can be any)
0.0.7
- add event markers for debug process
0.0.8
- add possibility do not break loop
