redux-io
is library for data management of network data in redux
and ease of data use in react
. Consists of middleware, reducers, action creators and helpers that provide:
- JSON-API
- normalized data in
redux
- async CRUD operations with
redux
actions - optimistic updates of redux
- denormalizing data for easier use in
react
- data caching and supported compatibility with
reselect
- simple and expandable network resource configuration
- data status, error handling and monitoring operations
- [SOON] JSON payloads with normalizr schemas
Redux is a great library, but it’s not a framework. It’s based on simple concepts that enable the freedom to build, but without clear patterns. But how are you going to manage network data and organize it in store, make async requests, normalize data, handle errors, cache data, monitor data statuses? At Shoutem we developed platform based on react
ecosystem in which we use redux
for managing data. We learned a lot about problems and discovered practices that give answers to above questions. All that is used in development of redux-io
library that we use everyday and enables us powerful data management.
Install redux-io
:
$ npm install --save @shoutem/redux-io
Import middlewares apiMiddleware
, apiStateMiddleware
and add them to your createStore
in applyMiddleware
function from redux
. We are internally using [[email protected]
] (https://github.com/agraboso/redux-api-middleware/tree/next) as library for async network requests, so that is the reason you need to add both middlewares respectively.
Example:
import { applyMiddleware, compose, createStore } from 'redux';
import { apiMiddleware } from 'redux-api-middleware';
import { apiStateMiddleware } from '@shoutem/redux-io';
import createLogger from 'redux-logger';
import thunk from 'redux-thunk';
import reducer from './reducers'
const logger = createLogger();
const store = createStore(
reducer,
applyMiddleware(thunk, apiMiddleware, apiStateMiddleware, logger)
);
And you are ready to start organizing state, configuring network resources, manage data with actions and use them in react components. Next section gives short intro in usage of redux-io in most common use cases.
For example, you have json-api API endpoint that enables you to fetch items of type acme.items
. You want to get most popular items, so endpoint http://api.test.com/items?sort=relevance
returns you list of items sorted by popularity:
{
"data": [
{
"type": "acme.items",
"id": "1",
"attributes": {
"name": "Rocket",
}
},
{
"type": "acme.items",
"id": "2",
"attributes": {
"name": "Helmet",
}
},
...
]
}
First you want to configure where fetched data will be placed in your state. Use storage
as a normal reducer to define where in your state are instances of objects, and collection
reducer to set place in the state for list holding ids of items that are popular. You are probably asking why do you need those two reducers, but idea is to keep data in redux state normalized. Normalization instances needs to be in one place in the state. However, you can reference it from mutliple parts in the state.
import { storage, collection } from `redux-api-state`;
combineReducers({
items: storage('acme.items'),
popularItems: collection('acme.items', 'popularItems'),
})
After that, you only need to dispatch find
action to fetch popular items from API. Find action is based on redux-api-middleware, and only needs to additional params schema
, and tag
. Schema defines in which storage
will fetched data end up, and tag
defines which collection
will fetch ids of objects.
import { find } from `redux-api-state`;
const config = {
endpoint: 'http://api.test.com/items?sort=relevance',
headers: {
'Content-Type': 'application/vnd.api+json',
},
};
dispatch(find(config, 'acme.items', 'popularItems'));
Upon dispatch, find
will configure action by redux-api-middleware specification, and redux-api-middleware will
- Dispatch REQUEST action
- Make GET request on http://api.test.com/items?sort=relevance
- If request is successful dispatch SUCCESS action
You can see that it is by redux-api-middleware
lifecycle. After which redux-api-state will listen on SUCCESS action and will act as:
- Validate SUCCESS action
- Unpack payload
- For each item in data will dispatch OBJECT_FETCHED
- Storage reducer will listen for OBJECT_FETCH and add it into map in state
- Dispatch COLLECTION_FETCHED
- Collection reducer will listen for COLLECTION_FETCHED and add items id into list
- Call next(action) for success action from redux-api-middleware
Storage reducer only adds an item if action is valid and schema value is equal to the action's schema. Collection reducer performs the same, but checks also tag
value. That enable us to have multiple collections of objects, but only one storage with instances of objects. Here is the state after app finished fetching:
state: {
items: {
1: {
"type": "acme.items",
"id": "1",
"attributes": {
"name": "Rocket",
}
},
2: {
"type": "acme.items",
"id": "2",
"attributes": {
"name": "Helmet",
}
},
},
popularItems: [1, 2, 3, ... ],
}
$ npm install && npm test
The package is based on concepts from Željko Rumenjak.