Natural Preference for Minification

    preach

    0.3.0 • Public • Published

    preach

    Build Status

    Preach is a lightweight pubsub utility for node and the browser. The browser version is ~2kb gzipped.

    Installation

    For node

    npm install preach --save

    For browsers

    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> 

    Changelog

    • 0.3.0
      • Preach is now a lot more forgiving (no more throws, yay!)
    • 0.2.0
      • Preach now exports a constructor when require-ed instead of a monolithic instance (incompatible change)
    • 0.1.0
      • Initial version

    API

    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 = 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'

    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 valid Function. This Function is called whenever data is published to the channel.

    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 new channel will be created and subscriber 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 valid Function. This Function is removed as a subscriber of channel

    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

    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 = 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(); //{}

    Preach.prototype.channels()

    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"]

    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 for channel 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, then Preach.subscribers returns an empty object ie {} and does not throw.

    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 for channel 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, then Preach.subscriberCount returns an empty object ie {} and does not throw.

    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 = new Preach;
    preach.setMaxSubscribers(10);
    //analogous to
    var preach = new Preach(10);

    Note:

    If n is lesser than zero then Preach will throw.

    Install

    npm i preach

    DownloadsWeekly Downloads

    7

    Version

    0.3.0

    License

    MIT

    Last publish

    Collaborators

    • zeusdeux