preach
Preach is a lightweight pubsub utility for node and the browser. The browser version is ~2kb gzipped.
Installation
node
For npm install preach --save
For browsers
bower install preach
or
git clone git@githubcom:zeusdeux/preachgit
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:
Changelog
- 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
API
- 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 )
Preach.prototype.pub(channel, [data], [data], [...])
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 = ;preach;preach;preach;preach; //will publish data to all channels beginning with 'channel'
Preach.prototype.sub(channel, subscriber)
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 = ;preach; //truepreach; //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.
Preach.prototype.unsub(channel, subscriber)
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 = ;preach; //truepreach; //true preach; //truepreach; //truepreach; //true //function(){} is now unsubscribed from *all* channels
Preach.prototype.purge()
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 = ;preach;preach;preach; //["test1", "test2"]preach; //Object {test1: Array[1], test2: Array[1]}preach; //PURGE! return val -> truepreach; //[]preach; //{}
Preach.prototype.channels()
This method returns an array of the current active channels.
var preach = ;preach; //truepreach; //truepreach; //["test1", "test2"]
Preach.prototype.subscribers(channel)
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 = ;preach;preach;preach; //Object {test1: Array[1], test2: Array[1]}preach; //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
.
Preach.prototype.subscriberCount(channel)
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 = ;preach;preach;preach;preach; //Object {test1: 2, test2: 1}preach; //Object {test2: 1}preach; //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
.
Preach.prototype.setMaxSubscribers(n)
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 = ;preach;//analogous tovar preach = 10;
Note:
If
n
is lesser thanzero
thenPreach
willthrow
.