READ ME

redux-io

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

Motivation

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.

Documentation

• API Reference

Getting started

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 [redux-api-middleware@2.0.0-beta.1] (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.

Usage

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

1. Dispatch REQUEST action
2. Make GET request on http://api.test.com/items?sort=relevance
3. 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:

1. Validate SUCCESS action
2. Unpack payload
3. For each item in data will dispatch OBJECT_FETCHED
4. Storage reducer will listen for OBJECT_FETCH and add it into map in state
5. Dispatch COLLECTION_FETCHED
6. Collection reducer will listen for COLLECTION_FETCHED and add items id into list
7. 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, ... ],
}

Tests

$ npm install && npm test

Acknowledgements

The package is based on concepts from Željko Rumenjak.