updux/docs/README.md

## What's Updux?

So, I'm a fan of [Redux](https://redux.js.org). 

As I was looking into tools to help cut on its boilerplate,
I came across [rematch](https://rematch.github.io/rematch). 
It has some pretty darn good ideas.
But it also enforces a flat hierarchy of reducers -- where
is the fun in that? 

I'm also having a strong love for
[Updeep](https://github.com/substantial/updeep), so I wanted a framework where
I could use it to define reducer state updates.

Hence: `Updux`. Heavily inspired by `rematch`, but twisted
to work with `updeep` and to fit my peculiar needs. It offers features such as

* Mimic the way VueX has mutations (per-action reducer logic) and
    effects (middleware reacting to actions that can be asynchronous and/or
    have side-effects), so all things pertaining to a store are defined
    in the space place.
* Automatically gather all actions used by the updux's effects and mutations,
    and makes then accessible as attributes to the `dispatch` object of the
    store.
* Mutations have a signature that is friendly to Updux and Immer.
* Mutations auto-unwrapping the payload of actions for you.
* TypeScript support.

**Fair warning**: this package is still very new, likely to go through
big changes before I find the perfect balance between ease of use and sanity.
Caveat Emptor.

# Synopsis

```js
import { Updux } from 'updux';
import u from 'updeep';
import add from 'lodash/fp/add.js';

import otherDux from './otherUpdux';

const dux = new Updux({
    initial: {
        counter: 0,
    },
    actions: {
        inc: null
    },
    subduxes: {
        otherDux,
    }
});

dux.setMutation('inc', (increment) => u({ counter: add(increment) }));

dux.addEffect( '*', api => next => action => {
    console.log( "hey, look, an action zoomed by!", action );
    next(action);
} );

const store = dux.createStore();

store.dispatch.inc(1);

console.log( store.getState().counter ); // prints 1
```