Redux CRUD
Redux CRUD is a convention driven way of building CRUD applications using Redux. After building several Flux applications we found that we always end up creating the same action types, actions and reducers for all our resources.
Redux CRUD gives you an standard set of:
- action types: e.g.
USER_UPDATE_SUCCESS
- actions: e.g.
updateSuccess
,updateError
- reducers: for the action types above e.g.
updateSuccess
Redux CRUD uses seamless-immutable for storing data by default.
Working with resources in Redux
When building an app you might have resources like users
, posts
and comments
.
You'll probably end up with action types for them like:
USERS_FETCH_SUCCESS
POSTS_FETCH_SUCCESS
COMMENTS_FETCH_SUCCESS
And action creators like:
users.fetchSuccess
posts.fetchSuccess
comments.fetchSuccess
There's obvious repetition there. Redux CRUD aims to remove this boilerplate by providing strong conventions on naming and processing data.
API
.actionTypesFor
Creates an object with standard CRUD action types:
var reduxCrud = ;var actionTypes = reduxCrud; // actionTypes => USERS_FETCH_START: 'USERS_FETCH_START' USERS_FETCH_SUCCESS: 'USERS_FETCH_SUCCESS' USERS_FETCH_ERROR: 'USERS_FETCH_ERROR' USERS_UPDATE_START: 'USERS_UPDATE_START' USERS_UPDATE_SUCCESS: 'USERS_UPDATE_SUCCESS' USERS_UPDATE_ERROR: 'USERS_UPDATE_ERROR' USERS_CREATE_START: 'USERS_CREATE_START' USERS_CREATE_SUCCESS: 'USERS_CREATE_SUCCESS' USERS_CREATE_ERROR: 'USERS_CREATE_ERROR' USERS_DELETE_START: 'USERS_DELETE_START' USERS_DELETE_SUCCESS: 'USERS_DELETE_SUCCESS' USERS_DELETE_ERROR: 'USERS_DELETE_ERROR' // Object also contains shortcuts fetchStart: 'USERS_FETCH_START' fetchSuccess: 'USERS_FETCH_SUCCESS' fetchError: 'USERS_FETCH_ERROR' updateStart: 'USERS_UPDATE_START' updateSuccess: 'USERS_UPDATE_SUCCESS' updateError: 'USERS_UPDATE_ERROR' createStart: 'USERS_CREATE_START' createSuccess: 'USERS_CREATE_SUCCESS' createError: 'USERS_CREATE_ERROR' deleteStart: 'USERS_DELETE_START' deleteSuccess: 'USERS_DELETE_SUCCESS' deleteError: 'USERS_DELETE_ERROR'
.actionCreatorsFor
Generates the following action creators:
fetchStart
fetchSuccess
fetchError
createStart
createSuccess
createError
updateStart
updateSuccess
updateError
deleteStart
deleteSuccess
deleteError
var reduxCrud = ;var actionCreators = reduxCrud; // actionCreators => { return data: data type: 'USERS_FETCH_START' ; } { return data: data records: users type: 'USERS_FETCH_SUCCESS' ; } { return data: data error: error type: 'USERS_FETCH_ERROR' ; } /* The user record must have a client generated key so it can be inserted in the collection optimistically. */ { return data: data record: user type: 'USERS_CREATE_START' ; } { return data: data record: user type: 'USERS_CREATE_SUCCESS' ; } /* The user record must have the client generated key so it can be matched with the record inserted optimistically. */ { return data: data error: error record: user type: 'USERS_CREATE_ERROR' ; } { return data: data record: user type: 'USERS_UPDATE_START' ; } { return data: data record: user type: 'USERS_UPDATE_SUCCESS' ; } { return data: data error: error record: user type: 'USERS_UPDATE_ERROR' ; } { return data: data record: user type: 'USERS_DELETE_START' ; } { return data: data record: user type: 'USERS_DELETE_SUCCESS' ; } { return data: data error: error record: user type: 'USERS_DELETE_ERROR' ; }
data
attribute
The The data
attribute in the actions payload is optional. The reducer doesn't do anything with this. This is only provided in case you want to pass extra information in the actions.
.reducersFor
Creates a reducer function for the given resource. Redux CRUD assumes that all records will have a unique key, e.g. id
. It generates the following reducers:
fetchSuccess
createStart
createSuccess
createError
updateStart
updateSuccess
updateError
deleteStart
deleteSuccess
deleteError
Note: There are no fetchStart
and fetchError
reducers.
var reduxCrud = ;var reducers = reduxCrud; // reducers => { }
reducersFor
takes an optional config object as second argument:
reduxCrud.reducersFor('users', {key: '_id', store: reduxCrud.STORE_SI});
config.key
Key to be used for merging records. Default: 'id'.
config.store
Type of store to use. Defaults to seamless-immutable. Options:
- reduxCrud.STORE_MUTABLE (Plain mutable JS)
- reduxCrud.STORE_SI (Seamless-immutable)
- reduxCrud.STORE_IMMUTABLE (Immutable.js)
What each reducer does
fetchSuccess
Listens for an action like this (generated by actionCreatorsFor
):
records: users type: 'USERS_FETCH_SUCCESS'
Takes one record or an array of records and adds them to the current state. Uses the given key
or id
by default to merge.
createStart
Listens for an action like:
type: 'USERS_CREATE_START' record: user
Adds the record optimistically to the collection. The record must have a client generated key e.g. id
, otherwise the reducer will throw an error. This key is necessary for matching records on createSuccess
and createError
. This client generated key is just temporary, is not expected that you will use this key when saving your data in the backend, it is just there so records can be matched.
This action is optional, dispatch this only if you want optimistic creation. Read more about this.
For generating keys see cuid.
Also adds busy
and pendingCreate
to the record so you can display proper indicators in your UI.
createSuccess
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_CREATE_SUCCESS' record: user cid: clientGeneratedId
Takes one record and adds it to the current state. Uses the given key
(id
by default) to merge.
The cid
attribute is optional but it should be used when dispatching createStart
. This cid
will be used for matching the record and replacing it with the saved one.
createError
Listens for an action like:
type: 'USERS_CREATE_ERROR' record: user
This reducer removes the record from the collection. The record key is used for matching the records. So if a record was added optimistically using createStart
then the keys must match.
updateStart
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_UPDATE_START' record: user
Takes one record and merges it to the current state. Uses the given key
or id
by default to merge.
It also add these two properties to the record:
busy
pendingUpdate
You can use this to display relevant information in the UI e.g. a spinner.
updateSuccess
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_UPDATE_SUCCESS' record: user
Takes one record and merges it to the current state. Uses the given key
or id
by default to merge.
updateError
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_UPDATE_ERROR' record: user error: error
This reducer will remove busy
from the given record. It will not rollback the record to their previous state as we don't want users to lose their changes. The record will keep the pendingUpdate
attribute set to true.
deleteStart
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_DELETE_START' record: user
Marks the given record as deleted
and busy
. This reducer doesn't actually remove it. In your UI you can filter out records with deleted
to hide them.
deleteSuccess
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_DELETE_SUCCESS' record: user
This reducer removes the given record from the store.
deleteError
Listens for an action like this (generated by actionCreatorsFor
):
type: 'USERS_DELETE_ERROR' record: user error: error
Removes deleted
and busy
from the given record.
Using with Redux
Action creators
Create your action creators by extending the standard actions:
;; const standardActionCreators = reduxCrud; let actionCreators = { ... } actionCreators = _; ;
Async action creators
Redux CRUD only generates sync action creators. Async action creators still need to be added:
const standardActionCreators = reduxCrud; let actionCreators = { return { // dispatch a `updateStart` for optimistic updates const action = standardActionCreators; ; // send the request const url = `/users/`; const promise = ; promise; return promise; } } ...
Reducers
Redux CRUD generates standard reducers for fetch
, create
, update
and delete
.
Create your Redux application:
;;;;; const createStoreWithMiddleware = createStore; const allReducers = ; const store = ;
Extending reducers
There are many cases when the generated reducers are not enough. For example you might want to delete relevant comments
when a post
is deleted. You can extend a reducer function like this:
// comments/reducers.js ;; const standardReducers = reduxCrud; { } ;
Then you can use this reducer:
; const allReducers = ;
Notes
Getting data to your components
With React use React-Redux.
Avoid nesting
Don't atttempt to store nested resources. e.g. {id: 1, posts: [{...}]}
. This makes harder to keep the information in sync with the UI. Instead always normalize the resources when they arrive from the server and store them in collections of their own.
Normalizing records
Your API might return something like:
id: 1 label: 'Some post' comments: id: 1 body: '...' id: 2 body: '...'
Instead of trying to work with nested records in your views, you should normalize them in your async action creator:
const baseActionCreators = reduxCrud;const baseCommentsActionCreators = reduxCrud; { return { const action = baseActionCreators; ; const url = `/posts/`; const promise = ; promise; return promise; }}
Use plural resources
Use a collection of resources and name them using the plural form e.g. users
instead of user
.
About optimistic changes
Dispatching createStart
, updateStart
and deleteStart
will result in optimistic changes to your store. See the description of what each reducer does above. updateStart
and deleteStart
will just work out of the box. createStart
needs additional code from you.
This is an example async action creator with optimistic creation:
{ return { // Generate a cid so we can match the records var cid = ; // Add the cid as the primary key user = user; // Optimistic creation // This action creator will throw if user doesn't have a primary key const action = baseActionCreators; ; // send the request const url = `/users/`; const promise = ; promise; return promise; } }
Note how we need to pass the cid
as the second argument to createSuccess
. If we don't the reducer will not be able to match the records and you will end up with duplicates.
Adding a client generated id
to a record doesn't mean that you need to use that id
for saving it in the backend. You can still generate ids as usual in your DB.
When the record comes back saved from the server the reducer will try to match id
on the optimistically inserted record with cid
on the createSuccess
action. If it finds a match it will replace the optimistically inserted record with the given one. That record will now have the normal id
given by the backend (The client generated id is thrown away at this point).
Pending attributes
createStart
and updateStart
will add the following attributes:
- createStart: Adds
busy
andpendingCreate
- updateStart: Adds
busy
andpendingUpdate
- updateError: Removes
busy
but leavespendingUpdate
You can use these special attributes for showing indicators and preventing navigation:
- Show a busy indicator when
busy
is true. - Do not allow navigation to a resource when
pendingCreate
is true. - Show a retry button when an update fails:
busy
is false butpendingUpdate
is true.
Mapping over records in components
Most likely you will get a seamless-immutable
collection in you components. Don't map over it to create a list because then seamless-immutable
will attempt to make the react components immutable, which doesn't work.
Don't do this:
var lis = records;
Instead, use lodash to map or convert to mutable first:
var lis = _;
or:
var lis = records.asMutable().map(function(record) {
return <li key={record.id}>{record.name}</li>;
});
seamless-immutable
Why Immutable.js is nice but we prefer seamless-immutable's stronger immutable guarantees.
Development
Testing
npm test
Example
You can see a basic example here
Changelog
1.0 added Immutable.js store
0.10.1 upgrade action-names
dep, remove left over ES6
0.10.0 .reducersFor
does not mutate the config object
0.9.0 Added mutable store (config.store: reduxCrud.STORE_MUTABLE)
0.8.0 Add data
attribute to actions payload.
0.7.0 Replaced unsaved
in createStart and updateStart with pendingCreate
and pendingUpdate
.