Silver

Silver is a fast, powerful and lightweight 1KB! event management library for node. It's written in plain Javascript and has no dependencies.

NPM page: silverjs

Github page: kcreate/silver

How to install

npm install --save silverjs

var Silver = require('silverjs');

Once you've installed it with npm, you can compress it by just running gulp against the directory and then replacing the index.js with index.min.js. However this is not required.

Creating a new silver object

new Silver(name = Date.now()+"")

You should always pass the same name you took for your variable into the Silver initializer. If you don't pass anything, Silver will just use the current Date.now() value.

var abc = new Silver("abc");

Add a new event

addEvent(eventName)

var abc = new Silver("abc");
abc.addEvent("myEvent");

Remove an event

removeEvent(eventName)

var abc = new Silver("abc");
abc.addEvent("myEvent");
abc.removeEvent("myEvent");

Removing an event that has active subscriptions, will fire the callbacks of the subscribers with the following data:

{
	"error":{
		"Event got removed while still being subscribed."
	}
}

removeEvent also takes a second parameter, but it's only used internally.

Check if an event exists

hasEvent(eventName)

var abc = new Silver("abc");
abc.addEvent("myEvent");
var hasEvent = abc.hasEvent("myEvent"); // true

Subscribe to an event

subscribeToEvent(object, eventName, callback)

To send data back to the caller of the event, return it in the callback

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data) {
        if(data.error){
			// handle error
		}

		return data+" world";
});

When you try to subscribe to an event that doesn't exist, the callback will be called immediately with the following content:

{
	"error": {
		"message":"An event called myEvent doesn't exist."
	}
}

If the object already has a subscription, it will be replaced.

Unsubscribing from an event

unsubscribeFromEvent(object, eventName)

Unsubscribing from an event that doesn't exist, or you're not subscribed to in the first place, will return false. On success it will return true;

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data){
        if(data.error){
			// handle error
		}

		return data+" world";
});
def.unsubscribeFromEvent(abc, "myEvent");

Get all subscribers for an event

subscribersForEvent(eventName)

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data){

});
var subscribers = abc.subscribersForEvent("myEvent");

The content of subscribers will be:

[
	{
		object:[Silver],
		name:'abc',
		callback:[
			Function
		]
	}
]

Check if an object is subscribed to another

isSubscribed(object, eventName)

This returns false if the object is not subscribed or if the event doesn't exist.

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data){
        // do stuff with data
});
var subscribed = def.isSubscribed(abc, "myEvent"); // true

Fire an event

fireEvent(eventName, parameters, callback)

The responses variable in the callback contains the responses that get returned in the subscribeToEvent method.

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data){
        return data + " world";
});
abc.fireEvent("myEvent", "hello", function(responses) {
        // [ 'hello world' ]
});

### Get all events an object has events()

The events method returns an array of all events an object has.

### Transfering an event transferEvent(object, eventName, keepSubscriptions, overwriteExisting)

This transfer an event from the owner to a new object. If keepSubscriptions is set to true, all subscriptions will be transfered over. If they are being removed, all callbacks will receive an error with the following content:

{
	"message":"Event got transfered to another object",
	"newObject":object
}

If overwriteExisting is set to true, it will overwrite an existing event with the same name on the new object. If keepSubscriptions and overwriteExisting are both set to true, Silver will try to merge all subscriptions into one event. If an object is subcribed to both events, the subscription to the overwritten event will be removed.

### Chainability

You can also chain most methods with each other. So for example if you'd wanted to add a new event and then immediately check if it really got created, you could write that like this:

var abc = new Silver('abc');
var exists = abc.addEvent('test').hasEvent('test');
// -> true

Or if you want to fire an event and then immediately remove it afterwards

abc.fireEvent('test', "world", function(response) {
	// your code goes here
}).removeEvent('test');
// -> abc does not have the event 'test' anymore

Error handling

Most of the time if an error happens, it will be reported via the callback specified in the subscribeToEvent method.

An error report always looks like this:

{
	"error":{
		"message":"Some error message..."
	}
}

You should aways check for a error object inside the callback method like that:

var abc = new Silver("abc");
var def = new Silver("def");

abc.addEvent("myEvent");
def.subscribeToEvent(abc, "myEvent", function(data) {
    if (data.error){
		// check the message here
		console.log(data.error.message);
	}
});

License

This library is licensed under the MIT License.