API Reference

donavon edited this page Dec 16, 2014 · 7 revisions
Clone this wiki locally

Creating a publisher/emitter pair

new pubit.Publisher(options)

Creates a new publisher object, with two properties: a publish method, and an emitter object.

pubit.makeEmitter(target, options)

Mixes emitter capabilities into target, and returns a publish function.

Publisher options

When creating a publisher/emitter pair, you can optionally pass an options object with any of the following properties:

  • async: a boolean indicating whether listeners should be run in the next turn of the event loop after an event is published. Default: false.
  • events: an array of event names that indicate events this publisher/emitter are responsible for. If this option is supplied, either publishing or subscribing to an event not in this list will throw an error.
  • onListenerError: a function taking a single object, called if a listener throws an error. The default behavior is to throw the error in the next turn of the event loop.

Publishing events

publish(eventName, …args)

Publishes an event. All supplied arguments get passed to the subscribers.

publish.when(eventName, …args)

Publishes an event and returns a promise. All supplied arguments get passed to the subscribers. The promise is fulfilled when all subscribers have been called and fulfilled their promise. The promise is resolved with each element of the array representing the resolved value of each subscriber.

Note that onListenerError and async options are NOT supported using publish.when.

Example:

// The publisher.
publish.when("vote", candidates).done(function(votes) {
    var winner = tallyVotes(votes);
    publish("winner", winner);
});

// Each subscriber.
voter.on("vote", function(candidates) {
    var deferred = Q.defer();

    voter.once("winner", displayWinner);

    function onsubmit(myChoice) {
        deferred.resolve(myChoice);
    }

    setupForm(onSubmit, candidates);
    return deferred.promise;
});

Subscribing to events

on(eventName:string, listener:Function):Function

Subscribes to an event. Returns a function that can be used to unsubscribe.

var unsubscribe = thingie.on("something", doSomething);

// The following two lines are equivalent.
unsubscribe();
thingie.off("something", doSomething);

once(eventName:string, listener:Function):Function

Subscribes to an event only for the next time it is published. Subsequent publication will not result in listener being called.

off(eventName:string, listener:Function):void

Unsubscribes a listener from an event. Note: if it is subscribed using both on and once, both instances will be unsubscribed.

off(eventName)

Unsubscribes all listeners from an event.

Using event-to-listener hashes

on, once, and off all have a variant that takes an event-to-listener hash, like so:

var hash = {
  connect: onConnected,
  disconnect: onDisconnected
};

emitter.on(hash);
emitter.off(hash);

Listener helpers

pubit.throttledListener(aggregateListener, time, asap)

Creates a "throttled listener" that, when called repeatedly, stores the first argument every time it is called, and passes the results off as an array to aggregateListener every time milliseconds.

If asap is truthy, the aggregate listener will be called in the next turn of the event loop the first time the throttled listener is called, instead of waiting time milliseconds before the first call (which is the default).

This allows events to be published repeatedly, but only reacted to in a rate-controlled manner.

pubit.debouncedListener(aggregateListener, time, asap)

Creates a "debounced listener" that, when called repeatedly, stores the first argument every time it is called, and passes the results off as an array to aggregateListener after time milliseconds have gone by without the debounced listener being called.

If asap is truthy, the aggregate listener will be called in the next turn of the event loop the first time the debounced listener is called, instead of waiting time milliseconds before the first call (which is the default).

This allows events to be published repeatedly, but reacted to all at once, after they have stopped coming in.