Preach is a lightweight pubsub utility for node and the browser. The browser version is ~2kb gzipped.
npm install preach --save
bower install preach
or
git clone git@github.com:zeusdeux/preach.git
If you plan to use it with browserify, then just require
index.js
.
If you plan to use it directly in the browser, then include browser/preach.min.js
. This will export
a global require
function.
You can then do:
<script>
var Preach = require('Preach');
var preachInstance = new Preach;
</script>
- 0.3.0
Preach
is now a lot more forgiving (no more throws, yay!)
- 0.2.0
Preach
now exports a constructor whenrequire
-ed instead of a monolithic instance (incompatible change)
- 0.1.0
- Initial version
- Preach.prototype.pub( channel, [data], [data], [...] )
- Preach.prototype.sub( channel, subscriber )
- Preach.prototype.unsub( channel, subscriber )
- Preach.prototype.purge()
- Preach.prototype.channels()
- Preach.prototype.subscribers( channel )
- Preach.prototype.subscriberCount( channel )
- Preach.prototype.setMaxSubscribers( n )
This method is used to publish data
to channel
.
This method takes the following parameters:
channel
:String
channel name or a regular expression (RegExp
)data
: Any valid javascript value. Also, this is an optional parameter
Example:
var preach = new Preach;
preach.pub('channel1');
preach.pub('channel2', 1234);
preach.pub('channel3', {a: 100}, 'test');
preach.pub(/^channel.*/, 10, {a: 'boop'}); //will publish data to all channels beginning with 'channel'
This method is used to add a subscriber
to channel
.
This method takes the following parameters:
channel
:String
channel name or a regular expression (RegExp
)subscriber
: A validFunction
. ThisFunction
is called whenever data is published to thechannel
.
A subscriber
can subscribe to as many channels as required and even publish to any channel.
####Note: If a
subscriber
publishes to a channel that it is subscribed to, then that will result in infinite recursion.
Example:
var preach = new Preach;
preach.sub('channel1', console.log.bind(window.console)); //true
preach.sub(/^channel.*/, function(){
console.log('I will get subscribed to any existing channel that has a name starting with the string "channel"');
}); //true
####Note: If a String is passed as
channel
and there are no channels that match it, then a newchannel
will be created andsubscriber
will be subscribed to it.
This method is used to unsubscribe a subscriber
from channel
.
This method takes the following parameters:
channel
:String
channel name or a regular expression (RegExp
)subscriber
: A validFunction
. ThisFunction
is removed as asubscriber
ofchannel
Example:
var preach = new Preach;
preach.sub('channel1', console.log.bind(window.log)); //true
preach.unsub('channel1', console.log.bind(window.log)); //true
preach.sub('test1', function(){}); //true
preach.sub('test2', function(){}); //true
preach.unsub(/.*/, function(){}); //true
//function(){} is now unsubscribed from *all* channels
This method purges all channels and their subscribers and gives you a fresh Preach
instance to work with.
This method is quite destructive and hence caution is advised in its usage.
Example:
var preach = new Preach;
preach.sub('test1', function(){});
preach.sub('test2', function(){});
preach.channels(); //["test1", "test2"]
preach.subscribers(); //Object {test1: Array[1], test2: Array[1]}
preach.purge(); //PURGE! return val -> true
preach.channels(); //[]
preach.subscribers(); //{}
This method returns an array of the current active channels.
var preach = new Preach;
preach.sub('test1', function(){}); //true
preach.sub('test2', function(){}); //true
preach.channels(); //["test1", "test2"]
This method returns information about the subscribers for a channel
.
This method takes the following parameter:
channel
:String
channel name or a regular expression (RegExp
) Not providing a value forchannel
is the same as passing/.*/
i.e., basically "GET ALL THE CHANNELS AND THEIR SUBSCRIBERS!".
Example:
var preach = new Preach;
preach.sub('test1', function(){});
preach.sub('test2', function(){});
preach.subscribers(); //Object {test1: Array[1], test2: Array[1]}
preach.subscribers('test1'); //Object {test1: Array[1]}
####Note: If a RegExp or String is passed as
channel
and there are no channels that match it, thenPreach.subscribers
returns an empty object ie{}
and does notthrow
.
This method returns the no of subscribers a channel has.
This method takes the following parameter:
channel
:String
channel name or a regular expression (RegExp
) Not providing a value forchannel
is the same as passing/.*/
i.e., basically "GET THE SUBSCRIBER COUNT FOR ALL THE CHANNELS".
Example:
var preach = new Preach;
preach.sub('test1', function(){});
preach.sub('test1', function(d){ console.log(d); });
preach.sub('test2', function(){});
preach.subscriberCount(); //Object {test1: 2, test2: 1}
preach.subscriberCount('test2'); //Object {test2: 1}
preach.subscriberCount(/1$/); //Object {test1: 2}
####Note: If a RegExp or String is passed as
channel
and there are no channels that match it, thenPreach.subscriberCount
returns an empty object ie{}
and does notthrow
.
This sets the max listeners for each channel at n
. Default is unlimited which is set by making n
zero
.
This can also be set during Preach
initialization.
var preach = new Preach;
preach.setMaxSubscribers(10);
//analogous to
var preach = new Preach(10);
####Note: If
n
is lesser thanzero
thenPreach
willthrow
.