Dispatcher

Dispatcher is used to broadcast payloads to registered callbacks. This is different from generic pub-sub systems in two ways:

Callbacks are not subscribed to particular events. Every payload is dispatched to every registered callback.
Callbacks can be deferred in whole or part until other callbacks have been executed.

Check out Dispatcher.js for the source code.

API #

register(function callback): string Registers a callback to be invoked with every dispatched payload. Returns a token that can be used with waitFor().
unregister(string id): void Removes a callback based on its token.
waitFor(array<string> ids): void Waits for the callbacks specified to be invoked before continuing execution of the current callback. This method should only be used by a callback in response to a dispatched payload.
dispatch(object payload): void Dispatches a payload to all registered callbacks.
isDispatching(): boolean Is this Dispatcher currently dispatching.

Example #

For example, consider this hypothetical flight destination form, which selects a default city when a country is selected:

var flightDispatcher = new Dispatcher();

// Keeps track of which country is selected
var CountryStore = {country: null};

// Keeps track of which city is selected
var CityStore = {city: null};

// Keeps track of the base flight price of the selected city
var FlightPriceStore = {price: null};

When a user changes the selected city, we dispatch the payload:

flightDispatcher.dispatch({
  actionType: 'city-update',
  selectedCity: 'paris'
});

This payload is digested by CityStore:

flightDispatcher.register(function(payload) {
  if (payload.actionType === 'city-update') {
    CityStore.city = payload.selectedCity;
  }
});

When the user selects a country, we dispatch the payload:

flightDispatcher.dispatch({
  actionType: 'country-update',
  selectedCountry: 'australia'
});

This payload is digested by both stores:

 CountryStore.dispatchToken = flightDispatcher.register(function(payload) {
  if (payload.actionType === 'country-update') {
    CountryStore.country = payload.selectedCountry;
  }
});

When the callback to update CountryStore is registered, we save a reference to the returned token. Using this token with waitFor(), we can guarantee that CountryStore is updated before the callback that updates CityStore needs to query its data.

CityStore.dispatchToken = flightDispatcher.register(function(payload) {
  if (payload.actionType === 'country-update') {
    // `CountryStore.country` may not be updated.
    flightDispatcher.waitFor([CountryStore.dispatchToken]);
    // `CountryStore.country` is now guaranteed to be updated.

    // Select the default city for the new country
    CityStore.city = getDefaultCityForCountry(CountryStore.country);
  }
});

The usage of waitFor() can be chained, for example:

FlightPriceStore.dispatchToken =
  flightDispatcher.register(function(payload) {
    switch (payload.actionType) {
      case 'country-update':
      case 'city-update':
        flightDispatcher.waitFor([CityStore.dispatchToken]);
        FlightPriceStore.price =
          getFlightPriceStore(CountryStore.country, CityStore.city);
        break;
  }
});

The country-update payload will be guaranteed to invoke the stores' registered callbacks in order: CountryStore, CityStore, then FlightPriceStore.