rstore

a straightforward, explicit, declarative and composable reactive store/model

Introduction

RStore is an observable (reactive) model.

Reactive?

| Active | Reactive | |---|---| | direct query at some point in time | a subscription to all updates | | console.log(state.getValue()) | state.subscribe(value => console.log(value)) |

In the reactive world of observables you don't have to think if something has happened by the time something else happens. So you can concentrate on a single thing - defining a way the changes combine and map to the result.

What are the benefits?

• a state is defined in one place

store(0)

• every observer immediately receives a notification on a state update (including the initial state)

store(0)
  .subscribe(value => console.log(value))

• the state can only be updated by other observables, so it changes whenever source stream produce updates
• the way updates modify the state is defined in terms of (widely adopted redux) reducers (see the interoperability section)

store(0)
  .plug(Rx.Observable.of(1), (x, y) => x + y)
  .subscribe(value => console.log(value))

• observables (sources of updates) can be defined in many ways
  • RxJS 5
  • Bacon.js
  • Most.js
  • built-in factories:
    • fromEvent(element: HTMLElement, EventName: String) => Observable of events
    • interval(n: number, ...values) => Observable that emits values every n milliseconds
    • address() => Observable that acts like an Event Bus (see counters example)
  • custom observer that implements observable interface
• RStore stores can be combined

const s1 = store(1);
const s2 = store(2);
s1.plug(s2, (x, y) => x + y)
  .subscribe(value => console.log(value)); // 3

• RStore stores can be converted to RxJS Observables

store(1)
  .toRx()
  .map(x => x* 2)
  .subscribe(state => console.log(state));

Example:

1 ) describe a model (properties, initial state):

const {store} = require('rstore'); 
const myStore = store(0);

2 ) define sources of changes (using fromEvent helper or Rx, Bacon, Most.js streams, see defining inputs)

const inc$ = fromEvent(document.getElementById('inc'), 'click');
const dec$ = fromEvent(document.getElementById('dec'), 'click');

3 ) define how these changes affect the model:

myStore
    .plug(inc$, (state, _update) => state + 1)
    .plug(dec$, (state, _update) => state - 1);

4 ) subscribe to the store and get an updated model on every change:

myStore.subscribe(model => console.log(model));

See more examples

API

Creating stores

As RStore supports multiple kinds of observables (APIs), it exports 5 store constructors:

| constructor | description | |---|---| | store | general, with an autodetect of the observable API | | storeR | RStore observables | | storeBacon | Bacon.js | | storeMost | Most.js | | storeRx | RxJS5 |

A constructor is a function that expects a single argument - an initial model value: It could be a primitive value

store(0);

or an object

store({
    todos: []
});

RStore methods

| method | description | |---|---| | .plug(oObservable, fnReducer) | subscribes RStore to the oObservable and for every value calls the fnReducer | | .unplug(oObservable, fnReducer) | given oObservable and optionally fnReducer unsubscribes RStore from an external observer | | .subscribe(fnObserver) | subscribes to RStore - calls fnObserver for every state update, including an initial value | | .reset() | unsubscribes everything| | .toRx(Rx) | converts a store to an Rx Observable |

Interoperability

###RxJS5 Observables are sources of changes

store({
    c1 : 0,
    c2 : 0
}).plug(
    Rx.Observable.of(1), (s, u) => Object.assign({}, s, {c1: u}),
    Rx.Observable.of(2), (s, u) => Object.assign({}, s, {c2: u})
).subscribe(model => console.log(model.c1 + model.c2));

A store can be converted to an observable

store(2)
  .toRx(Rx) // Rx object, optional if Rx is global
  .map(x => x * 2)
  .subscribe(v => console.log(v)); // 4

###Redux Reducers can be reused

const observableOfChanges = Rx.Observable.from([
      {type: 'INCREMENT'},
      {type: 'INCREMENT'},
      {type: 'DECREMENT'},
      {type: 'INCREMENT'},
]);

const reduxReducer = (state, action) => {
      switch (action.type) {
        case 'INCREMENT':
          return state + 1
        case 'DECREMENT':
          return state - 1
        default:
          return state;
      }
};

store(0)
  .plug(observableOfChanges, reduxReducer)
  .subscribe(state => console.log(state)); // 2

Redux store as a source of updates

const changes = [
    {type: 'INCREMENT'},
    {type: 'INCREMENT'},
    {type: 'DECREMENT'},
    {type: 'INCREMENT'}
];

function reduxReducer (state = 0, action) {
    switch (action.type) {
        case 'INCREMENT':
            return state + 1;
        case 'DECREMENT':
            return state - 1;
        default:
            return state;
    }
}

const reduxStore = Redux.createStore(reduxReducer);

changes.forEach(m => reduxStore.dispatch(m));

rstore.store(0)
    .plug(reduxStore[Symbol.observable](), (s, u) => u)
    .subscribe(state => console.log(state)); // 4

changes.forEach(m => reduxStore.dispatch(m));

Composability

As stores are Observables, they can be used as sources of changes:

// store 1 (counter from the previous example)
const counter1 = store(0);
const inc1$ = fromEvent(document.getElementById('inc1'), 'click');
const dec1$ = fromEvent(document.getElementById('dec1'), 'click');
counter1
    .plug(inc1$, (state, _update) => state + 1)
    .plug(dec1$, (state, _update) => state - 1);

counter1.subscribe(model => document.getElementById('res1').textContent = model);

// store 2 (a second counter, similar to counter 1)
const counter2 = store(0);
const inc2$ = fromEvent(document.getElementById('inc2'), 'click');
const dec2$ = fromEvent(document.getElementById('dec2'), 'click');
counter2
    .plug(inc2$, (state, _update) => state + 1)
    .plug(dec2$, (state, _update) => state - 1);

counter2.subscribe(model => document.getElementById('res2').textContent = model);

// a combining store, stores current states from both counters 
// notifies subscribers if any of the counter values changes 
store({
    c1 : 0,
    c2 : 0
}).plug(
    counter1, (s, u) => Object.assign({}, s, {c1: u}),
    counter2, (s, u) => Object.assign({}, s, {c2: u})
).subscribe(model => document.getElementById('total').textContent = model.c1 + model.c2);

more on composability

Redux DevTools Extension

STK works with Redux Devtools Extension:

• Install the tools
• Connect one of the stores to the DevTools:

const initial = 0;
const store = rstore.store(initial);
rstore.devtools.addStore(store, initial);

easy access to model fields

In many cases model modification functions are just setters that take the current state and a new value as inputs and produce a new model. It might be hard to access\update deeply nested fields as it is desirable that functions stay pure and data stays immutable.

rstore has a lens function that is a pair of a setter and a getter for the given field:

const lens = require('rstore').lens;
const l = lens('a');
const o1 = {a: 11};
const o2 = {a: 22};

// returns a value of the field 'a' in the object 'o1' (11)
console.log( l.get(o1) ) 
// returns a value of the field 'a' in the object 'o2' (22)
console.log( l.get(o2) ) 

// returns a new object like 'o1', but the field 'a' is set to '33' 
// ({a: 33}), object 'o1' stays the same
console.log( l.set(o1, 33) ) 
// returns a new object like 'o2', but the field 'a' is set to '44' 
// ({a: 44}), object 'o2' stays the same
console.log( l.set(o2, 44) ) 

more on lenses