API Reference

DomenicDenicola edited this page Jan 27, 2012 · 1 revision
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.

Subscribing to events

on(eventName, listener)

Subscribes to an event.

onNext(eventName, listener)

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

off(eventName, listener)

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

off(eventName)

Unsubscribes all listeners from an event.

Using event-to-listener hashes

on, onNext, 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.