Keflux is a small javascript library I’ve been developing during the last few days. Its purpose is to allow 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. It also embraces the use of immutable data structures, as an integral part of how it is designed, and how it works.

Keflux 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 at this todo-list app built as an example.

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 component

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

There are still many features and use cases that haven’t been explored or implemented yet. The following is a list of some of these:

• Automated tests.
• 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.

This project is still in its conception stage, not even considered infancy. It’s actually more a proof-of-concept at this time, to validate its actual applicability in real-world scenarios. Therefore its actual form and API may vary heavily over time, or it may even be abandoned if it does not prooves itself useful for real use cases.