Keflux

Keflux is a library that allows to use event streams to build a Flux architecture in a front-end React app. It uses [Kefir][] for all FRP-related code, and as part of the library name.

Stores

Keflux promotes the concept of self-contained stores, each defining its data structure and the actions that are available to perform on it. Below is an example store for a todo-list app:

const TodoStore = Keflux.Store({

  create(stream) {
    return stream.
      filter((text) => text.trim().length > 0).
      map((text) => {
        const todo = Immutable.OrderedMap({
          id: uuid.v1(),
          text: text,
          completed: false,
        });
        return (data) => data.set(todo.get("id"), todo);
      });
  },

  updateText(stream) {
    return stream.
      filter((params) => params.text.trim().length > 0).
      map((params) => {
        return (data) => data.setIn([params.id, "text"], params.text);
      });
  },

  toggleComplete(stream) {
    return stream.map((todo) => {
      return (data) => data.setIn([todo.id, "completed"], !todo.completed);
    });
  },

  destroy(stream) {
    return stream.map((todo) => {
      return (data) => data.remove(todo.id);
    });
  },

  clearCompleted(stream) {
    return stream.map(() => {
      return (data) => data.filter((todo) => !todo.get('completed'));
    });
  },

  toggleAll(stream) {
    return stream.map((checked) => {
      return (data) => data.map((todo) => todo.set('completed', checked));
    });
  },

});

Each action method receives a stream of events, each event being an invocation by the app to trigger that particular action. These action methods can then transform this stream using traditional FRP functions (filter, map, etc.)

The resulting stream should issue a series of functions, that when applied to the underlying data structure, modifies it in a way consistent with the action invoked.

For more real-world-like examples, take a look to a couple of stores in the examples/ directory. Those are todo-list stores but with persistend storage (one to local storage, and the other to an ajax json api).

Understanding how it works

To better understand this concept, let's look in detail at the create action from the example above:

create(stream) {
  return stream.
    filter((text) => text.trim().length > 0).
    map((text) => {
      const todo = Immutable.OrderedMap({
        id: uuid.v1(),
        text: text,
        completed: false,
      });
      return (data) => data.set(todo.get("id"), todo);
    });
}

The stream received as argument above will emit a new value each time the app invokes this action on the store. The first thing the action does is filtering out those invocations made with an empty text, since we do not want to-do items whose text is an empty string.

Then the valid events (those with non-empty text) are mapped to a function that receives the underlying data structure of the store (an immutable map), and returns a copy of it, but with the new todo-item added to it.

The result is a new stream of functions, that when applied to the store's data structure, each add a new todo item to it, as requested by the app using this store. The store takes care of applying these functions to the underlying data structure, on each iteration of the stream processing.

Usage on a React.js app

Keflux stores expose a stream called changes, which emits a new value each time the underlying data structure changes as a result of triggering one of its actions.

So once stores are defined like it is described above, a React.js component can subcribe to the changes on this store, and update its state to match the store's data. This is shown in the following example:

const TodoApp = React.createClass({
  propTypes: {
    store: React.PropTypes.object,
  },

  getInitialState() {
    return {
      data: this.props.store.data,
    };
  },

  componentDidMount() {
    this.props.store.changes.onValue((data) => this.setState({data}));
  },

  render() {
    // ...
  },
});

There are plans to provide a mixin for components to easily declare that its state depends on one or more stores, as well as to take advantage of React.js' contexts to implicitly pass stores to child components.

What's next

This is a list of features that have not been explored or implemented yet.

• How does error handling fits with this architecture.
• Mixin for easing the access to stores/actions in components via React.js' contexts.
• Registering callbacks to handle action completion.