Tidal

javascript pub/sub library

Dependencies

none

Usage

var tidal = new Tidal();

Tidal is built so that you can create new Tidal instances each with their own event cache. Many other pub/sub libraries are implemented as singletons and thus only allow creation of instances by using some form of Object.create or .extend().

Tidal.prototype.subscribe('name', fn, [context])

@param {string} name - event namespace
@param {function} fn - callback
@param {object=} context - context to apply callback with (optional)
@returns {number} token

var tokenOne = tidal.subscribe('eventone', fn);
var tokenTwo = tidal.subscribe('eventtwo', fn, context)

The context argument lessens the overhead of having to rely on other libraries to create proxy functions like jQuery.proxy() or _.bind()

Tidal.prototype.publish('name', ...)

@param {string} name - event name
 @param (...anything=) args (optional)
 @returns {Tidal}

publish will accept a list of arguments or an argument array

tidal.publish('eventone', 1, 2, 3, 'arg');	// subscribers called with `Function.prototype.apply`
tidal.publish('eventthree', [1, 2, 3]);		// subscribers called with `Function.prototype.call`

Optimized to use Function.prototype.call when less than 4 arguments are passed in. Inspired by Backbone.js

Tidal.prototype.unsubscribe( token | ['name', fn] | 'eventname' | fn )

Allows unsubscribing with:

• token - will unsubscribe a single subscription

   tidal.unsubscribe(tokenOne);

• handler - will unsubscribe any subscriptions with the passed in name and callback

   var eventName = 'thebigevent';
   var callback = function () {};
   tidal.subscribe(eventName, callback);
   todal.unsubscribe([eventName, callback]);

• event namespace - will unsubscribe any subscriptions for an event namespace

   tidal.subscribe('test-event', functionOne);
   tidal.subscribe('test-event', functionTwo);
   tidal.unsubscribe('test-event');

• callback - will unsubscribe any subscriptions for any event with a specified callback

   tidal.subscribe('event-one', singleFunction);
   tidal.subscribe('event-two', singleFunction);
   tidal.unsubscribe(singleFunction);