@promotively/react-redux-data NPM

@promotively/react-redux-data

Universal/isomorphic react.js/redux.js javascript/typescript library for data fetching.

Why?

You are already using redux.js in your app.
You want an easy way to handle data fetching.
You are building a new app and want to use redux.js to handle your data state.
You have a bunch of repetitive data related react.js/redux.js boilerplate you wish didn't exist.
You want a proper data abstraction layer but don't have the time to build one.
You want to be able to debug your data through redux dev tools.
You want to avoid an architecture that depends on some kind of global data fetching layer (ie: react-router-config).
You need a library that is compatible with server side rendering.
You need to interact with APIs that are not HTTP and/or JSON based.
You want to refresh your data periodically through timers or events.
You need access to your component props when fetching data for things like access tokens or configs.
You need to share your data with external applications and/or tools.

Installation

Requires React 16.8.3 or later and Redux 7.0.0 or later.

With Yarn

yarn add @promotively/react-redux-data

With NPM

npm install @promotively/react-redux-data

Example

Advanced examples using higher order components and hooks rendered with nodejs and web browsers are available inside the /example folder.

Once you have executed yarn build go to the dist/example folder and from there you can run node server.js to see server side rendering from localhost:3000 or open the index.html file to see client side rendering.

An example is also available online.

Documentation

The source code is documented using JSDoc syntax and documentation is generated using jsdoc.

Once you have executed yarn docs documentation is available inside the dist/docs folder.

Documentation for the most recent release is also available online.

Setup

Add dataReducer to your redux.js store and make sure that redux-thunk is also added to your store middleware.

// store.js

import { applyMiddleware, combineReducers, createStore } from 'redux';
import { dataReducer } from '@promotively/react-redux-data';
import thunk from 'redux-thunk';

const store = createStore(combineReducers({ data: dataReducer }), applyMiddleware(...[thunk]));

export default store;

Usage

Wrap your component using withData and specify an id for your data and a function that returns a promise.

// containers/users.js

import { withData } from '@promotively/react-redux-data';
import axios from 'axios';
import Users from '../components/users';

const fetchUsers = props => axios.get('http://localhost:3000/api/v1/users').then(response => response.data);

const UsersContainer = withData({
  id: 'users',
  action: fetchUsers
})(Users);

export default UsersContainer;

// components/users.js

import React from 'react';

const Users = props => (
  <ul>
    {props.error ? <span>Error: {props.error}</span> : null}
    {props.loading ? <span>Loading, Please Wait...</span> : null}
    {props.users ? props.users.map(user => <li key={user.id}>{user.name}</li>) : null}
  </ul>
);

export default Users;

// components/app.js

import React from 'react';

const App = props => <UsersContainer />;

export default App;

If you need to do server side rendering use hydrateStore with <DataProvider /> to pre-fetch data before your app is rendered.

// server.js

import App from './components/app';
import UsersContainer from './containers/users';
import express from 'express';
import { hydrateStore } from '@promotively/react-redux-data';
import { Provider } from 'react-redux';
import React from 'react';
import { renderToString } from 'react-dom/server';
import store from './store';

const server = express();
const data = [];
const app = (
  <Provider store={store}>
    <DataProvider context={data}>
      <App />
    </DataProvider>
  </Provider>
);

server.get('/', async (req, res, next) => {
  try {
    await hydrateStore(app, store, data);
    res.send(renderToString(app));
  } catch (error) {
    next(error);
  }
});

server.listen(3000);

API

Redux Action Creators

Function	Arguments	Description
`completeData`	(id, query, data)	Insert data into the store directly (good for caching!).
`loadingData`	(id)	Set the data loading state.
`errorData`	(id, error)	Set the data error state.
`destroyData`	(id)	Remove data from the store.
`fetchData`	(id, promise)	Resolve a promise and add the result to the store.

React Container Component

Function	Description	Props
`DataProvider`	Container component primarily used with the hydrateStore function for pre-fetching data with server side rendering.	{ completeData, data, error, errorData, fetchData, loading, loadingData, destroyData }

React Higher Order Component

Function	Arguments	Description	Props
`withData`	(options)	An object containing configuration options.	{ id, action, data, destroy, error, fetchData, loading }

React Hook

Function	Arguments	Description	Props
`useData`	(id, options)	An object containing configuration options.	{ id, action, data, destroy, error, fetchData, loading }

Redux Reducers

Function	Description
`dataReducer`	A redux.js reducer function to handle the state mutations during the data fetching lifecycle.

React Redux Selectors

Function	Arguments	Description
`createDataSelector`	(id)	Create a reselect.js selector function to get the current data.
`createDataErrorSelector`	(id)	Create a reselect.js selector function to get the error state.
`createDataLoadingSelector`	(id)	Create a reselect.js selector function to get the loading state.