126 lines
3.0 KiB
Markdown
126 lines
3.0 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');
|
|
```
|
|
|