redux-tree
An alternative way to compose Redux reducers.
Interactions pattern
redux-tree
is a part of the interactions
pattern. Check it out to get more context.
Table of Contents
State as a Tree
Application state can be represented as a tree
, which is a combination of branches
and leaves
. A branch doesn’t hold any state itself but is a grouping of leaves that each hold chunks of the application state. If state is flat, then tree
consists only of leaves
.
state:
entities:
posts: { index, entities }
comments: { entities }
ui:
postsList: { processingPosts }
...
For example, the branch state.entities
groups the states of the posts
leaf, comments
leaf, etc.
Let’s say a user manages his posts and removes one of them by clicking the “Delete” button. What’s happening under the hood? The state of this UI part is stored in the state.ui.postsList
leaf. Clicking on the button, a user triggers an action creator and the app starts a request to the server. In response to this action, postId
is added to the processingPosts
set to show the spinner in the UI. It requires a change of the single ui.postsList
leaf. Let’s describe it in the interaction module:
// Action creator: returns request actionconst requestAction = type: 'POST_DELETE_REQUESTED' postId; // Action handler: reduces the state of the single leafconst onRequest = POST_DELETE_REQUESTED: state;
When a server responds with a success:
postId
must be removed from theprocessingPosts
post
entity must be removed from theentities.posts
leaf.
This action entails changing 2 different leaves:
// Action creator: returns success actionconst successAction = type: 'POST_DELETE_SUCCEEDED' postId; // Action handlers: passing array of the reducers for this action type// to apply sequence of the changes to the state treeconst onSuccess = POST_DELETE_SUCCEEDED: // 1. hide spinner state // 2. remove post entity leaf: 'entities' 'posts' // <= keypath to the leaf of the state reduce: postsEntitiesState ;
To make this code work, few internal changes are required in how Redux iterates over the reducers. Under the hood, redux-tree
is an alternative version of Redux’s combineReducers
, which makes it possible to represent changes to the state as a sequence of functions. This allows describing interactions in a very concise and consistent manner.
It’s super easy to integrate redux-tree
into existing codebases as it supports classic reducers (so incremental adoption is absolutely possible, see Migration) and it should be compatible with the most of the packages from Redux ecosystem. The main change it introduces is how Redux internally iterates over the reducers.
In the initial release of redux-tree
, state is represented as an Immutable Record
. We use Immutable a lot in our apps; it makes it easier to handle deep updates and prevent state mutations, Record allows access to properties using dot notation (as opposed to getters), and it’s possible to strongly type the state tree with flow
. So, immutable-js
is required (at least for now).
Installation
# yarn / npm yarn add redux-treenpm install --save redux-tree # don't forget to install redux & immutable yarn add redux immutablenpm install --save redux immutable
Examples
- Counter
;; const tree = ; const store = ; store; store; // => { counter: 1 }store; // => { counter: 2 }store; // => { counter: 1 }
- Advanced [ live · source ]
- See more advanced examples (incl. usage w/
flow
) inredux-interactions
repo.
API
redux-tree
exposes 3 modules:
createTree
createTree
receives 1 argument: object with branches and/or leaves. Returns a tree
, in fact this is a root reducer.
; const tree = ; type State;type Tree; // Then pass it to redux's `createStore` instead of reducerconst store = ;
createBranch
createBranch
also receives 1 argument: object with branches and/or leaves. You don't need this method if your state tree is 1 level deep. Returns a branch
.
; const branch = type Branch;
createLeaf
You can pass 2 types of arguments to createLeaf
:
- Single argument: classic reducer function, which takes state of the leaf and action and returns next leaf state.
- Two arguments: initial state of the leaf and object with action handlers.
; const leaf = ;const leaf = ; type CreateLeaf = | Leaf | Leaf;
Action handlers
Action handlers are stored in an object. Its keys are action types, and values are action handlers (reducers). You can define reducers in the following ways:
As a function. It receives the state of the leaf to which it was initially passed and dispatched action. Must return a state of the leaf.
state
As an object with:
leaf
: keypath to the leaf in the statereduce
: reducer, which receives state of the leaf at provided keypath and dispatched action. Must return a state of the leaf.
ACTION_TYPE: leaf: 'path' 'to' 'leaf' state
As an array of the previous two. Useful when you need to change the state of the multiple leaves in response to single action.
ACTION_TYPE: state // function receives state of the local leaf leaf: 'path' 'to' 'leaf' state // receives the state of the leaf at the keypath
Migration
To integrate redux-tree
into existing codebase, no need to refactor all the reducers at once. You can pass existing ones to the createLeaf
and refactor them incrementally:
; { } counterReducer;
combineReducers
Usage with It is possible to define tree
as a child of vanilla reducer, created with combineReducers
.
const rootReducer = ;
Keep in mind that tree
doesn't know anything about parents, and in action handler you can't change a state of an external leaf at keypath outside of the tree. All keypaths must be provided relative to the tree's root node. Basically, keypaths must be the same as if child tree would be a root reducer. But you still can respond to any action in any reducer in case you need this.
Thanks
To Alberto Leal for handing over the redux-tree
NPM package name.
License
It's MIT.