create-dispatcher v1.4.0

create-dispatcher

create-dispatcher provides a simple, minimal event dispatcher.

Install

npm install create-dispatcher --save

Usage

import createDispatcher from 'create-dispatcher';

const { dispatch, subscribe } = createDispatcher({ defaultChannel: '!!GLOBAL!!' });

const unsubscribeGlobal = subscribe((channel, event) => {
  // !!GLOBAL!! {"type":"hello world","payload":{"hello":"world"}}
  console.log(channel, event);
});

const unsubscribeChannel = subscribe('custom:channel', (event) => {
  // {"type":"PING"}
  console.log(event);
});

dispatch({ type: 'hello world', payload: { hello: 'world' } });
dispatch('custom:channel', { type: 'PING' });

unsubscribeGlobal();
unsubscribeChannel();

API

dispatcher exports a single function for creating a Dispatcher instance:

createDispatcher(options:Object) => Dispatcher

The function accepts a single (optional) argument — an object which can contain a defaultChannel property that will be used when a channel is not specified in the subscribe and dispatch methods (defaults to *).

The returned Dispatcher is an object exposing three methods:

Dispatcher.dispatch

The dispatch method can be provided with one or two arguments. If two arguments are provided, the first argument will be treated as a channel to dispatch to and the second will be treated as the event. If one argument is provided, it will be treated as the event and the channel will default to the defaultChannel. The function will return a bool, indicating whether the event was successfully dispatched or not.

Dispatcher.dispatch(channel:String, event:?) => Boolean
Dispatcher.dispatch(event:?) => Boolean

Dispatcher.subscribe

The subscribe method can be called with one or two arguments.

If the method is called with two arguments, the first argument will be treated as a channel to subscribe to and the second will be treated as a receiver function. The receiver will be called with the signature of (channel: String, event: ?) whenever an event is dispatched to the channel.

If one argument is provided, it will be treated as a receiver function. If the receiver function accepts two arguments ((channel: String, event: ?)), it will be called whenever an event is dispatched to any channel. If it only accepts one argument, it will only be called when events are dispatched to the defaultChannel.

If the subscription is successful, the function will return an unsubscribe function which can be called to cancel the subscription — it will return true the first time it's called and false thereafter. If the subscription is not successful (i.e. you've called destroy), the function will return false.

Dispatcher.subscribe(channel:String, receiver:Function) => unsubscribe:Function|Boolean
Dispatcher.subscribe(receiver:Function) => unsubscribe:Function|Boolean

Dispatcher.destroy

The destroy method can be used to untrack all subscriptions and prevent new ones. I recommend you try not to use this method and instead just cancel any subscriptions you create (using the returned unsubscribe function). The function will return true the first time it's called and false thereafter.

Dispatcher.destroy() => Boolean