river-react v0.0.4

River

River is a reactive stream composer for React application.

Influences

River was inspired by Flux and RxJS. In River, all stores are composed by Rx Observables, where stores are mostly likely to be hot observables. When combined with stateless function components in React 0.14, React + Flux architecture can be greatly simplified. This is very similar to pure view functions in Cycle.js.

Installation

To install:

npm install --save river-react

This assumes that you’re using npm package manager with a module bundler like Webpack or Browserify to consume CommonJS modules.

You also want to install RxJS if you haven't done so.

npm install --save rx

Prerequisite

River assumes developer is familiar with the usage of RxJS. River is merely a set of utility functions to help compose data layer and bind React components to consume the data.

Hello Example

Using React 0.14-rc1, RxJS 3.x

import React from 'react';
import ReactDOM from 'react-dom';
import Rx from 'rx';
import { createAction, createStore, subscribe } from 'river-react';

//// Action
let addSubject = new Rx.Subject();
let add = createAction(addSubject);

//// Stream (a.k.a. Store in Flux)
let counterStream = createStore(() => {
  return addSubject
    .scan((count, _) => count + 1, 0)
    .startWith(0);
});

//// React Component using 0.14 function component style
let App = (props) => {
  return (
    <div>
      <h1>{props.counter}</h1>
      <button onClick={add}>+1</button>
    </div>
  );
};

let initialState = {counter: 1};
let AppContainer = subscribe(App, {counter: counterStream}, initialState);

ReactDOM.render(<AppContainer />, node);

API

Before River reach 1.0, API will change between minor version bumps.

createAction(subject)

This is a wrapper around instance of Rx Subject. It gives subject.onNext a short cut.

let addSubject = new Rx.Subject();
let add = createAction(addSubject);

add(value); // same as `addSubject.onNext(value)`;

createStore(observableFactory)

This makes a Rx Observable hot and replay last value, and connects the observable when created.

let counterStream = createStore(() => {
  return addSubject
    .scan((count, _) => count + 1, 0)
    .startWith(0);
});

Which is equivalent to:

let counterStream = addSubject
  .scan((count, _) => count + 1, 0)
  .startWith(0)
  .replay(null, 1);
});

counterStream.connect();

subscribe(Component, observableMap, [initialState])

This creates a new React Component by wrapping a provided one, and pass state into wrapped Component as props. Optionally, you can specify initialState for your Component.

let App = (props) => {
  return (
    <div>
      <h1>{props.counter}</h1>
      <button onClick={add}>+1</button>
    </div>
  );
};

let initialState = {counter: 1};
let AppContainer = subscribe(App, {counter: counterStream}, initialState);

ReactDOM.render(<AppContainer />, node);

Internally, subscribe uses combineLatestObj method to shallow convert observableMap into a new observabe. E.g. for {counter: counterStream}, when counterStream emits 123, the new observable will emit {counter: 123}. {counter: 123} will eventually be passed as props to App component.