389 lines
8.6 KiB
Markdown
389 lines
8.6 KiB
Markdown
|
|
# What's Updux?
|
|
|
|
So, I'm a fan of [Redux][]. Two days ago I discovered
|
|
[rematch](https://rematch.github.io/rematch) alonside a few other frameworks built atop Redux.
|
|
|
|
It has a couple of pretty good ideas that removes some of the
|
|
boilerplate. Keeping mutations and asynchronous effects close to the
|
|
reducer definition, à la [VueX][]? Nice. Automatically infering the
|
|
actions from the said mutations and effects? Genius!
|
|
|
|
But it also enforces a flat hierarchy of reducers -- where
|
|
is the fun in that? And I'm also having a strong love for
|
|
[Updeep][], so I want reducer state updates to leverage the heck out of it.
|
|
|
|
All that to say, I had some fun yesterday and hacked a proto-lovechild
|
|
of `Rematch` and `Updeep`, with a dash of [VueX][] inspiration.
|
|
I call it... `Updux`.
|
|
|
|
# Synopsis
|
|
```
|
|
import updux from 'updux';
|
|
|
|
import otherUpdux from './otherUpdux';
|
|
|
|
const {
|
|
initial,
|
|
reducer,
|
|
actions,
|
|
middleware,
|
|
createStore,
|
|
} = updux({
|
|
initial: {
|
|
counter: 0,
|
|
},
|
|
subduxes: {
|
|
otherUpdux,
|
|
},
|
|
mutations: {
|
|
inc: ( increment = 1 ) => u({counter: s => s + increment })
|
|
},
|
|
effects: {
|
|
'*' => api => next => action => {
|
|
console.log( "hey, look, an action zoomed by!", action );
|
|
next(action);
|
|
};
|
|
},
|
|
actions: {
|
|
customAction: ( someArg ) => ({ someProp: someArg }),
|
|
},
|
|
|
|
});
|
|
|
|
const store = createStore();
|
|
|
|
store.dispatch.inc(3);
|
|
```
|
|
|
|
# Description
|
|
|
|
`Updux` exports one function, `updux`, both as a named export and as
|
|
its default export.
|
|
|
|
## helpers = updux(config);
|
|
|
|
`updux` is a way to minimize and simplify the boilerplate associated with the
|
|
creation of a `Redux` store. It takes a shorthand configuration
|
|
object, and generates the appropriate reducer, actions, middleware, etc.
|
|
In true `Redux`-like fashion, just like reducers can be composed
|
|
of sub-reducers, upduxs can be made of sub-upduxs.
|
|
|
|
### config
|
|
|
|
The config object recognize following properties.
|
|
|
|
#### initial
|
|
|
|
The default initial state of the reducer. Can be anything your
|
|
heart desires.
|
|
|
|
#### subduxes
|
|
|
|
Object mapping slices of the state to sub-upduxs.
|
|
|
|
For example, if in plain Redux you would do
|
|
|
|
```
|
|
import { combineReducers } from 'redux';
|
|
import todosReducer from './todos';
|
|
import statisticsReducer from './statistics';
|
|
|
|
const rootReducer = combineReducers({
|
|
todos: todosReducer,
|
|
stats: statisticsReducer,
|
|
});
|
|
```
|
|
|
|
then with Updux you'd do
|
|
|
|
```
|
|
import { updux } from 'updux';
|
|
import todos from './todos';
|
|
import statistics from './statistics';
|
|
|
|
const rootUpdux = updux({
|
|
subduxes: {
|
|
todos, statistics
|
|
}
|
|
});
|
|
|
|
#### mutations
|
|
|
|
Object mapping actions to the associated state mutation.
|
|
|
|
For example, in `Redux` you'd do
|
|
|
|
```
|
|
function todosReducer(state=[],action) {
|
|
|
|
switch(action.type) {
|
|
case 'ADD': return [ ...state, action.payload ];
|
|
|
|
case 'DONE': return state.map( todo => todo.id === action.payload
|
|
? { ...todo, done: true } : todo )
|
|
|
|
default: return state;
|
|
}
|
|
}
|
|
```
|
|
|
|
With Updux:
|
|
|
|
```
|
|
const todosUpdux = updux({
|
|
mutations: {
|
|
add: todo => state => [ ...state, todo ],
|
|
done: done_id => u.map( u.if( ({id} => id === done_id), {done: true} ) )
|
|
}
|
|
});
|
|
```
|
|
|
|
The signature of the mutations is `(payload,action) => state => newState`.
|
|
It is designed to play well with `Updeep`. This way, instead of doing
|
|
|
|
```
|
|
mutation: {
|
|
renameTodo: newName => state => { ...state, name: newName }
|
|
}
|
|
```
|
|
|
|
we can do
|
|
|
|
```
|
|
mutation: {
|
|
renameTodo: newName => u({ name: newName })
|
|
}
|
|
```
|
|
|
|
Also, the special key `*` can be used to match any
|
|
action not explicitly matched by other mutations.
|
|
|
|
```
|
|
const todosUpdux = updux({
|
|
mutations: {
|
|
add: todo => state => [ ...state, todo ],
|
|
done: done_id => u.map( u.if( ({id} => id === done_id), {done: true} ) ),
|
|
'*' (payload,action) => state => {
|
|
console.warn( "unexpected action ", action.type );
|
|
return state;
|
|
},
|
|
}
|
|
});
|
|
```
|
|
|
|
#### effects
|
|
|
|
Plain object defining asynchronous actions and side-effects triggered by actions.
|
|
The effects themselves are Redux middleware, expect with the `dispatch`
|
|
property of the first argument augmented with all the available actions.
|
|
|
|
```
|
|
updux({
|
|
effects: {
|
|
fetch: ({dispatch}) => next => async (action) => {
|
|
next(action);
|
|
|
|
let result = await fetch(action.payload.url).then( result => result.json() );
|
|
dispatch.fetchSuccess(result);
|
|
}
|
|
}
|
|
});
|
|
|
|
### actions
|
|
|
|
Generic action creations are automatically created from the mutations and effects, but you can
|
|
also define custom action creator here. The object's values are function that
|
|
transform the arguments of the creator to the action's payload.
|
|
|
|
```
|
|
const { actions } = updox({
|
|
mutations: {
|
|
foo: () => state => state,
|
|
}
|
|
actions: {
|
|
bar: (x,y) => ({x,y})
|
|
}
|
|
});
|
|
|
|
actions.foo({ x: 1, y: 2 }); // => { type: foo, payload: { x:1, y:2 } }
|
|
actions.bar(1,2); // => { type: bar, payload: { x:1, y:2 } }
|
|
|
|
|
|
## return value
|
|
|
|
`updux` returns an object with the following properties:
|
|
|
|
### initial
|
|
|
|
Default initial state of the reducer. If applicable, merge
|
|
the initial states of `config` and `subduxes`, with
|
|
`config` having precedence over `subduxes`.
|
|
|
|
If nothing was given, defaults to an empty object.
|
|
|
|
### reducer
|
|
|
|
A Redux reducer generated using the computed initial state and
|
|
mutations.
|
|
|
|
### mutations
|
|
|
|
Merge of the config and subduxes mutations. If an action trigger
|
|
mutations in both the main updux and its subduxes, the subduxes
|
|
mutations will be performed first.
|
|
|
|
### actions
|
|
|
|
Action creators for all actions defined or used in the actions, mutations, effects and subduxes
|
|
of the updox config.
|
|
|
|
Non-custom action creators defined in `actions` have the signature `(payload={},meta={}) => ({type,
|
|
payload,meta})` (with the extra sugar that if `meta` or `payload` are not
|
|
specified, the key is not present in the produced action).
|
|
|
|
If the same action appears in multiple locations, the precedence order
|
|
determining which one will prevail is
|
|
|
|
actions generated from mutations/effects < non-custom subduxes actions <
|
|
custom subduxes actions < custom actions
|
|
|
|
### middleware
|
|
|
|
A middleware aggregating all the effects defined in the
|
|
updox and its subduxes. Effects of the updox itself are
|
|
done before the subdoxes effects.
|
|
|
|
### createStore
|
|
|
|
Same as doing
|
|
|
|
```
|
|
import { createStore, applyMiddleware } from 'redux';
|
|
|
|
const { initial, reducer, middleware, actions } = updox(...);
|
|
|
|
const store = createStore( initial, reducer, applyMiddleware(middleware) );
|
|
|
|
for ( let type in actions ) {
|
|
store.dispatch[type] = (...args) => {
|
|
store.dispatch(actions[type](...args))
|
|
};
|
|
}
|
|
```
|
|
|
|
So that later on you can do
|
|
|
|
```
|
|
store.dispatch.addTodo(...);
|
|
|
|
// still work
|
|
store.dispatch( actions.addTodo(...) );
|
|
```
|
|
|
|
# Example
|
|
|
|
#### battle.js
|
|
|
|
```
|
|
import { updux } from 'updux';
|
|
|
|
import game from './game';
|
|
import log from './log';
|
|
import bogeys from './bogeys';
|
|
|
|
const { createStore } = updux({
|
|
subduxes: { game, log, bogeys }
|
|
})
|
|
|
|
export default createStore;
|
|
```
|
|
|
|
#### game.js
|
|
|
|
|
|
```
|
|
import { updux } from 'updux';
|
|
import _ from 'lodash';
|
|
import u from 'updeep';
|
|
|
|
import { calculateMovement } from 'game/rules';
|
|
|
|
export default updux({
|
|
initial: { game: "", players: [], turn: 0, },
|
|
mutations: {
|
|
init_game: ({game: { name, players }}) => {name, players},
|
|
play_turn: () => u({ turn: x => x+1 }),
|
|
},
|
|
effects: {
|
|
play_turn: ({getState,dispatch}) => next => action => {
|
|
|
|
const bogeys = api.getState().bogeys;
|
|
|
|
// only allow the turn to be played if
|
|
// all ships have their orders in
|
|
if( bogeys.any( bogey => ! bogey.orders ) ) return;
|
|
|
|
bogeys.forEach( bogey => {
|
|
dispatch.move( calculateMovement(bogey) )
|
|
} );
|
|
|
|
next(action);
|
|
},
|
|
}
|
|
});
|
|
```
|
|
|
|
|
|
#### log.js
|
|
|
|
```
|
|
import { updux } from 'updux';
|
|
|
|
export default updux({
|
|
initial: [],
|
|
mutations: {
|
|
'*': (payload,action) => state => [ ...state, action ],
|
|
},
|
|
});
|
|
```
|
|
|
|
#### bogeys.js
|
|
|
|
```
|
|
import { updux } from 'updux';
|
|
import _ from 'lodash';
|
|
|
|
export default updux({
|
|
initial: [],
|
|
mutations: {
|
|
init_game: ({bogeys}) => () => _.keyBy( bogeys, 'id' ),
|
|
move: ({position}) => u({ position }),
|
|
},
|
|
});
|
|
```
|
|
|
|
|
|
#### myGame.js
|
|
|
|
```
|
|
import Battle from './battle';
|
|
|
|
const battle = Battle();
|
|
|
|
battle.dispatch.init_game({
|
|
name: 'Gemini Prime',
|
|
players: [ 'yenzie' ],
|
|
bogeys: [ { id: 'Enkidu' } ]
|
|
});
|
|
|
|
battle.dispatch.play_game();
|
|
|
|
....
|
|
```
|
|
|
|
|
|
[Redux]: https://redux.js.org
|
|
[Updeep]: https://github.com/substantial/updeep
|
|
[VueX]: https://vuex.vuejs.org/
|