408 lines
8.9 KiB
Markdown
408 lines
8.9 KiB
Markdown
# Tutorial
|
|
|
|
This tutorial walks you through the features of `Updux` using the
|
|
time-honored example of the implementation of Todo list store.
|
|
|
|
We'll be using
|
|
[updeep](https://www.npmjs.com/package/updeep) to
|
|
help with immutability and deep merging,
|
|
but that's totally optional. If `updeep` is not your bag,
|
|
it can easily be substitued with, say, [immer][], [lodash][], or even
|
|
plain JavaScript.
|
|
|
|
## Definition of the state
|
|
|
|
To begin with, let's define that has nothing but an initial state.
|
|
|
|
```js
|
|
import { Updux } from 'updux';
|
|
|
|
const todosDux = new Updux({
|
|
initial: {
|
|
next_id: 1,
|
|
todos: [],
|
|
}
|
|
});
|
|
```
|
|
|
|
Congrats! You have written your first Updux object. It
|
|
doesn't do a lot, but you can already create a store out of it, and its
|
|
initial state will be automatically set:
|
|
|
|
```js
|
|
const store = todosDux.createStore();
|
|
|
|
console.log(store.getState()); // prints { next_id: 1, todos: [] }
|
|
```
|
|
|
|
## Add actions
|
|
|
|
This is all good, but a little static. Let's add actions!
|
|
|
|
```js
|
|
const todosDux = new Updux({
|
|
initial: {
|
|
next_id: 1,
|
|
todos: [],
|
|
},
|
|
{
|
|
addTodo: null,
|
|
todoDone: null,
|
|
}
|
|
});
|
|
```
|
|
|
|
### Accessing actions
|
|
|
|
Once an action is defined, its creator is accessible via the `actions` accessor.
|
|
|
|
```js
|
|
console.log( todosDux.actions.addTodo('write tutorial') );
|
|
// prints { type: 'addTodo', payload: 'write tutorial' }
|
|
```
|
|
### Adding a mutation
|
|
|
|
Mutations are the reducing functions associated to actions. They
|
|
are defined via the `setMutation` method:
|
|
|
|
|
|
```js
|
|
todosDux.setMutation( 'addTodo', description => ({next_id: id, todos}) => ({
|
|
next_id: 1 + id,
|
|
todos: [...todos, { description, id, done: false }]
|
|
}));
|
|
```
|
|
## Effects
|
|
|
|
In addition to mutations, Updux also provides action-specific middleware, here
|
|
called effects.
|
|
|
|
Effects use the usual Redux middleware signature, plus a few goodies.
|
|
The `getState` and `dispatch` functions are augmented with the dux selectors,
|
|
and actions, respectively. The selectors and actions are also available
|
|
from the api object.
|
|
|
|
```js
|
|
import u from 'updeep';
|
|
import { action, Updux } from 'updux';
|
|
|
|
// we want to decouple the increment of next_id and the creation of
|
|
// a new todo. So let's use a new version of the action 'addTodo'.
|
|
|
|
const addTodoWithId = action('addTodoWithId');
|
|
const incNextId = action('incNextId');
|
|
const addTodo = action('addTodo');
|
|
|
|
const addTodoEffect = ({ getState, dispatch }) => next => action => {
|
|
const id = getState.nextId();
|
|
|
|
dispatch.incNextId();
|
|
|
|
next(action);
|
|
|
|
dispatch.addTodoWithId({ description: action.payload, id });
|
|
}
|
|
|
|
const todosDux = new Updux({
|
|
initial: { nextId: 1, todos: [] },
|
|
actions: { addTodo, incNextId, addTodoWithId },
|
|
selectors: {
|
|
nextId: ({nextId}) => nextId,
|
|
},
|
|
mutations: {
|
|
addTodoWithId: (todo) => u({ todos: (todos) => [...todos, todo] }),
|
|
incNextId: () => u({ nextId: id => id+1 }),
|
|
},
|
|
effects: {
|
|
'addTodo': addTodoEffect
|
|
}
|
|
});
|
|
|
|
const store = todosDux.createStore();
|
|
|
|
store.dispatch.addTodo('Do the thing');
|
|
```
|
|
|
|
### Catch-all effect
|
|
|
|
It is possible to have an effect match all actions via the special `*` token.
|
|
|
|
```
|
|
todosUpdux.addEffect('*', () => next => action => {
|
|
console.log( 'seeing action fly by:', action );
|
|
next(action);
|
|
});
|
|
```
|
|
|
|
## Adding selectors
|
|
|
|
Selectors can be defined to get data derived from the state.
|
|
From now you should know the drill: selectors can be defined at construction
|
|
time or via `setSelector`.
|
|
|
|
```
|
|
const getTodoById = ({todos}) => targetId => todos.find(({id}) => id === targetId);
|
|
|
|
const todosUpdux = new Updux({
|
|
selectors: {
|
|
getTodoById
|
|
}
|
|
})
|
|
```
|
|
|
|
or
|
|
|
|
```
|
|
todosDux.setSelector('getTodoById', getTodoById);
|
|
```
|
|
|
|
### Accessing selectors
|
|
|
|
The `getState` method of a dux store is augmented
|
|
with its selectors, with the first call for the state already
|
|
called in for you.
|
|
|
|
```js
|
|
const store = todosDux.createStore();
|
|
|
|
console.log(
|
|
todosUpdux.getState.getTodoById(1)
|
|
);
|
|
```
|
|
|
|
## Subduxes
|
|
|
|
Now that we have all the building blocks, we can embark on the last and
|
|
funkiest part of Updux: its recursive nature.
|
|
|
|
### Recap: the Todos dux, undivided
|
|
|
|
Upduxes can be divided into sub-upduxes that deal with the various parts of
|
|
the global state. This is better understood by working out an example, so
|
|
let's recap on the Todos dux we have so far:
|
|
|
|
```js
|
|
import Updux from 'updux';
|
|
import u from 'updeep';
|
|
import fp from 'lodash/fp';
|
|
|
|
const todosDux = new Updux({
|
|
initial: {
|
|
nextId: 1,
|
|
todos: [],
|
|
},
|
|
actions: {
|
|
addTodo: null,
|
|
addTodoWithId: (description, id) => ({description, id, done: false}),
|
|
todoDone: null,
|
|
incNextId: null,
|
|
},
|
|
selectors: {
|
|
getTodoById: ({todos}) => id => fp.find({id},todos)
|
|
},
|
|
mutations: {
|
|
addTodoWithId: todo =>
|
|
u.updateIn( 'todos', todos => [ ...todos, todo] ),
|
|
incrementNextId: () => u({ nextId: fp.add(1) }),
|
|
todoDone: (id) => u.updateIn('todos',
|
|
u.map( u.if( fp.matches({id}), todo => u({done: true}, todo) ) )
|
|
),
|
|
},
|
|
effects: {
|
|
addTodo: ({ getState, dispatch }) => next => action => {
|
|
const { nextId: id } = getState();
|
|
|
|
dispatch.incNextId();
|
|
|
|
next(action);
|
|
|
|
dispatch.addTodoWithId(action.payload, id);
|
|
}
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
This store has two main components: the `nextId`, and the `todos` collection.
|
|
The `todos` collection is itself composed of the individual `todo`s. Let's
|
|
create upduxes for each of those.
|
|
|
|
### NextId dux
|
|
|
|
```
|
|
// dux/nextId.js
|
|
|
|
import { Updux } from 'updux';
|
|
import u from 'updeep';
|
|
|
|
export default new Updux({
|
|
initial: 1,
|
|
actions: {
|
|
incrementNextId: null,
|
|
},
|
|
selectors: {
|
|
getNextId: state => state
|
|
},
|
|
mutations: {
|
|
incrementNextId: () => state => state + 1,
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
### Todo updux
|
|
|
|
```
|
|
// dux/todos/todo/index.ts
|
|
|
|
import { Updux } from 'updux';
|
|
import u from 'updeep';
|
|
import fp from 'lodash/fp';
|
|
|
|
export default new Updux({
|
|
initial: {
|
|
id: 0,
|
|
description: "",
|
|
done: false,
|
|
},
|
|
actions: {
|
|
todoDone: null,
|
|
},
|
|
mutations: {
|
|
todoDone: id => u.if( fp.matches({id}), { done: true }) )
|
|
},
|
|
selectors: {
|
|
desc: ({description}) => description,
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
### Todos updux
|
|
|
|
```
|
|
// dux/todos/index.js
|
|
|
|
import { Updux } from 'updux';
|
|
import u from 'updeep';
|
|
import fp from 'lodash/fp';
|
|
|
|
import todo from './todo/index.js';
|
|
|
|
export default new Updux({
|
|
initial: [],
|
|
subduxes: {
|
|
'*': todoDux
|
|
},
|
|
actions: {
|
|
addTodoWithId: (description, id) => ({description, id} )
|
|
},
|
|
findSelectors: {
|
|
getTodoById: state => id => fp.find({id},state)
|
|
},
|
|
mutations: {
|
|
addTodoWithId: todo =>
|
|
todos => [ ...todos, todo ]
|
|
}
|
|
});
|
|
```
|
|
|
|
Note the special '\*' subdux key used here. This
|
|
allows the updux to map every item present in its
|
|
state to a `todo` updux. See [this recipe](/recipes?id=mapping-a-mutation-to-all-values-of-a-state) for details.
|
|
|
|
### Main store
|
|
|
|
```
|
|
// dux/index.js
|
|
|
|
import Updux from 'updux';
|
|
|
|
import todos from './todos';
|
|
import nextId from './next_id';
|
|
|
|
export new Updux({
|
|
subduxes: {
|
|
nextId,
|
|
todos,
|
|
},
|
|
actions: {
|
|
addTodo: null
|
|
},
|
|
effects: {
|
|
addTodo: ({ getState, dispatch }) => next => action => {
|
|
const id = getState.getNextId();
|
|
|
|
dispatch.incrementNextId()
|
|
|
|
next(action);
|
|
|
|
dispatch.addTodoWithId( action.payload, id );
|
|
}
|
|
}
|
|
});
|
|
|
|
```
|
|
|
|
Tadah! We had to define the `addTodo` effect at the top level as it needs to
|
|
access the `getNextId` selector from `nextId` and the `addTodoWithId`
|
|
action from the `todos`.
|
|
|
|
Note that the `getNextId` selector still gets the
|
|
right value; when aggregating subduxes selectors Updux auto-wraps them to
|
|
access the right slice of the top object. ```
|
|
|
|
## Reactions
|
|
|
|
Reactions -- aka Redux's subscriptions -- can be added to a updux store via the initial config
|
|
or the method `addSubscription`. The signature of a reaction is:
|
|
|
|
```
|
|
(storeApi) => (state, previousState, unsubscribe) => {
|
|
...
|
|
}
|
|
```
|
|
|
|
Subscriptions registered for an updux and its subduxes are automatically
|
|
subscribed to the store when calling `createStore`.
|
|
|
|
The `state` passed to the subscriptions of the subduxes is the local state.
|
|
|
|
Also, all subscriptions are wrapped such that they are called only if the
|
|
local `state` changed since their last invocation.
|
|
|
|
Example:
|
|
|
|
```
|
|
const todos = new Updux({
|
|
initial: [],
|
|
actions: {
|
|
setNbrTodos: null,
|
|
addTodo: null,
|
|
},
|
|
mutations: {
|
|
addTodo: todo => todos => [ ...todos, todo ],
|
|
},
|
|
reactions: [
|
|
({dispatch}) => todos => dispatch.setNbrTodos(todos.length)
|
|
],
|
|
});
|
|
|
|
const myDux = new Updux({
|
|
initial: {
|
|
nbrTodos: 0
|
|
},
|
|
subduxes: {
|
|
todos,
|
|
},
|
|
mutations: {
|
|
setNbrTodos: nbrTodos => u({ nbrTodos })
|
|
}
|
|
});
|
|
```
|
|
|
|
[immer]: https://www.npmjs.com/package/immer
|
|
[lodash]: https://www.npmjs.com/package/lodash
|
|
[ts-action]: https://www.npmjs.com/package/ts-action
|
|
|