README

syphon

Syphon is an implementation of the Flux architectural pattern for React applications inspired by ClojureScript and Om. It helps structure your application around a single immutable state value and implements the dispatching of actions to various state-transitioning handler functions.

Example
State
Handlers
Dispatcher
Components
Observe
Mixin
Install
License

Example

var syphon = require('syphon');

var state = syphon.atom({ text: 'Hello World' });

var dispatcher = syphon.dispatcher();

dispatcher.handler('update-text', function (state, text) {
  return state.set('text', text);
});

var Component = React.createClass({
  mixins: [syphon.mixin],

  setText: function (e) {
    this.dispatch('update-text', e.currentTarget.value);
  },

  render: function () {
    return React.DOM.div({},
      React.DOM.input({ onChange: this.setText }),
      React.DOM.p({}, this.props.data.get('text')));
  }
});

syphon.root(Component, state, {
  dispatcher: dispatcher,
  el: document.getElementById('app')
});

State

Application state is stored in an immutable data structure and passed as a prop (called data) to the root component in the hierarchy. A single mutable reference to the immutable state is held in an atom:

var state = syphon.atom({ foo: 'bar' });

To access the value inside the atom you must deref it:

var data = state.deref();

This will return the Immutable.js data structure. Since the data cannot be mutated directly, our only way to update the application state is to swap the atom's reference with a new state value:

var state = syphon.atom({ foo: 'bar' });

state.swap(function (current) {
  // `current` is an Immutable.js map
  console.log(current.toJS());
  // => { foo: 'bar' }

  // Return a new state by modifying the current state.
  // Refer to the Immutable.js docs for availble methods.
  return current.set('foo', 'baz');
});

console.log(state.deref().toJS());
// => { foo: 'baz' }

Handlers (see below) are responsible for implementing these state transitioning functions.

You can watch for state changes via a callback:

state.addWatch('mywatcher', function (key, ref, old, state) {
  console.log('the state is now:', state);
});

Refer to the js-atom docs for more information about atoms.

Handlers

Handlers are functions of the form:

function (state, value) {
  return newState;
}

The first argument is the current (dereferenced) application state.
The remaining arguments are the values passed to dispatch
The handler must return a new immutable state. Refer to the Immutable.js docs for information about mofifying the state.

While handlers are pure functions in the sense that they do not directly mutate application state, they may have other side-effects (such as making a network request or calling out to some other stateful browser API). Since the handler functions are called synchronously, any asynchronous results must re-dispatched and handled elsewhere:

dispatcher.handler('fetch-post', function (state, id) {
  var self = this;

  // Make network request
  fetchPost(id, function (err, post) {
    if (err) {
      self.dispatch('fetch-post-error', id, err);
    } else {
      self.dispatch('fetch-post-success', post);
    }
  });

  return state.set('loading', true);
});

dispatcher.handler('fetch-post-success', function (state, post) {
  return state
    .set('loading', false)
    .set('post', post);
});

dispatcher.handler('fetch-post-error', function (state, id, err) {
  return state
    .set('loading', false)
    .set('notice', 'There was an error fetching the post with id=' + id)
    .set('error', err);
});

Dispatcher

You will typically only need a single dispatcher per application since it can coordinate multiple handlers. To add handlers to a dispatcher either pass them to the constructor or call the handler function:

var dispatcher = syphon.dispatcher({
  foo: function (state, value) { ... },
  bar: function (state, value) { ... }
});

var dispatcher = syphon.dispatcher();

dispatcher.handler('foo', function (state, value) { ... });
dispatcher.handler('bar', function (state, value) { ... });

To dispatch an action, call the dispatch function, passing the handler name and any additional values:

dispatcher.dispatch('example', 'foo', { bar: 123 });

The dispatcher emits a dispatch event after each handler is called:

dispatcher.on('dispatch', function (dispatch) {
   console.log(dispatch.name);  // name of the handler invoked
   console.log(dispatch.args);  // additional args passed to the handler
   console.log(dispatch.state); // state returned from the handler
});

Components

To mount your component hierarchy and automatically re-render when the state changes, Syphon provides the root function:

syphon.root(MyComponent, state, {
  dispatcher: dispatcher,
  el: document.getElementById('app')
});

On every render, your root component will receive the current (dereferenced) state in a prop called data. Your component can then pass parts of the state to child components and so on.

Observe

You may encounter cases where your data hierarchy does not directly correspond to your component hierarchy and a component needs to access application state it was not passed as a prop. In these cases you can observe arbitrary paths in the application state:

var Component = React.createClass({
  mixins: [syphon.mixin],

  componentWillMount: function () {
    this.text = this.observe(['path', 'to', 'text']);
  },

  render: function () {
    return React.DOM.p({}, this.text());
  }
});

Syphon tracks which components are observing certain paths and ensures that they update when the application state changes at those paths.

Mixin

The Syphon mixin adds some helpers to your components that make it easier to dispatch values, observe state, and access shared data. It also implements React's shouldComponentUpdate method to take advantage of fast immutable data structure equality checks.

By using the mixin you can...

Dispatch new actions:

var MyComponent = React.createClass({
  mixins: [syphon.mixin],

  onClick: function () {
    this.dispatch('button-clicked');
  }
});

Share data with the entire component hierarchy:

var MyComponent = React.createClass({
  mixins: [syphon.mixin],

  componentWillMount: function () {
    console.log(this.shared().foo); // => 'bar'
  }
});

syphon.root(MyComponent, state, {
  dispatcher: dispatcher,
  el: document.getElementById('app'),
  shared: { foo: 'bar' }
});

And observe application state:

var MyComponent = React.createClass({
  mixins: [syphon.mixin],

  componentWillMount: function () {
    this.text = this.observe(['path', 'to', 'text']);
  },

  render: function () {
    return React.DOM.p({}, this.text());
  }
});

Install

npm install syphon

License

The MIT License (MIT)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Usage no npm install needed!