coherence

Coherence

A safety oriented Flux Store factory

Usage

Defining a Store

var Coherence = require('coherence');

function AnimalStore(dependencies) {
  const animalData = dependencies.animalData;

  const store = Coherence(dependencies.dispatcher, function(router, actions, state) {
    router.register('/animals/:animalId', showAnimal);
    actions.register('speak', speak);

    // action handler
    function speak(action) {
      state.set({words: action.words});
    }

    // route handler
    function show(path, params) {
      animalData.fetch(params.animalId).then(function(animal) {
        state.set({showAnimal: animal});
      });
    }
  });

  return store;
};

AnimalStore.instance = AnimalStore({
  dispatcher: require('./my-app-dispatcher'),
  animalData: require('./my-animal-data'),
});

module.exports = AnimalStore;

Using your Store

In your controller components

var animalStore = require('./animal_store').instance;
var AnimalView = React.createClass({
  componentWillMount: function() {
    animalStore.addChangeListener(this.updateState);
  },
  componentWillUnmount: function() {
    animalStore.removeChangeListener(this.updateState);
  },
  updateState: function() {
    this.setState({animalData: animalStore.data()});
  },
  render: function() {
    return (<div>...</div>);
  }
});

Features

Routing

"Routing" with Coherence, is really just a wrapper around action handling, with route matching and param parsing baked in (via dumb-router).

Registered routes listen for Actions with a type of Coherence.NAVIGATE_ACTION_TYPE, and with a path property.

To trigger your routes:

yourDispatcher.dispatch({
  type: Coherence.NAVIGATE_ACTION_TYPE,
  path: whereYouWantToGo,
});

API

Coherence

• Coherence.NAVIGATE_ACTION_TYPE
  • the action type to which registered routes will respond

Defining a Store

var store = Coherence(dispatcher, function(router, actions, state) {
  /* define store behavior here */
});

The Coherence function takes two arguments:

• dispatcher

  • must define a register method that conforms to the semantics described by Flux

• configurer

  • a callback, that accepts three arguments, used together to define the behavior of the returned store instance

    • router.register(routeString, routeHandler)

      • binds a handler function that gets called when a matching "navigate" action is dispatched - see dumb-router for more information
      • the handler function receives two params: the matching path string, and a params object

    • actions.register(actionType, actionHandler)

      • binds a handler function that gets called when a matching action is dispatched
      • the handler function receives the action payload object

    • state.set(newValues)

      • updates the values returned by the public method store.data(), and triggers the event handlers bound by store.addChangeListener()

Public Instance Methods

• store.addChangeListener(callback)

  • binds the callback to be invoked, whenever coherence.set is called, for use when mounting controller components

• store.removeChangeListener(callback)

  • removes the change callbacks, for use when unmounting controller components

• store.data()

  • returns any data set by state.set

• store.path(...pathParts)

  • returns a path string, if the parts match one of the routes registered by router.register - see dumb-router for more information

Development

Add or modify tests to reflect the change you want.

Run them with npm test, and update the code in src/ till your tests pass.

Running the tests will run npm run compile, which outputs the code as ES5, polyfilled via core-js.