Rest-react-redux NPM

Rest React Redux

A higher order component for RestAPI abstraction. Reduces boilerplate and encourages clean code.

By decorating your component with queriedEntity/detailedEntity and initializing the first network call, you can have access to a managed data entity named according to the "entity name" you passed as argument.

Installation

npm:

npm install rest-react-redux --save

What you need to do:

Create the proper reducer structure
Annotate your component/container with the proper HOC
Enjoy the props introduced to your component and not ever worry about writing actions and reducers

This library is supposed to be used only on a restful endpoint. here is an example:

GET: http://www.url.com/contacts?page=1&page-size=10 returns a list of contacts and metadata about the query
POST: http://www.url.com/contacts creates a contact
GET, PUT, PATCH and DELETE: http://www.url.com/contacts/contactId gets, updates or patches the specific contact respectively

Restrictions in the current version

JSON endpoints: network request and response body must be of application/json content type
Redux-thunk: your application redux store must contain redux-thunk as middleware

import {createStore, compose, applyMiddleware} from 'redux';
import thunk from 'redux-thunk';
export const store = createStore(rootReducer, compose(applyMiddleware(thunk)));

Axios: your application must use axios as the network call library. BaseUrl and headers must be set in your application scope

import axios from 'axios';
axios.defaults.baseURL = 'http://www.url.com';

reducer: using queriedEntityReducer or detailedEntityReducer you must create a field in the root reducer matching the name of the entity you create. This is where the library manages the data

import { queriedEntityReducer, detailedEntityReducer } from 'rest-react-redux';
const reducers = {
    contacts: queriedEntityReducer('contact'),
    contact: detailedEntityReducer('contact'),
}

Higher Order Components

queriedEntity

if you intend to work with an endpoint that returns a list use queriedEntity to decorate your components:

import { queriedEntity } from 'rest-react-redux';

@queriedEntity('contact')
class ContactsPage extends React.Component {
    ...
}

NOTE: For those of you who do not enjoy decorating as much as I do, use the standard way!

queriedEntity(entityName, configoptional)

Config field	Explanation	Default Value
resultField	the result field name in response body that matches the list of items	`content`
retain_number	maximum number of queries to cache	`10`
hideLoadIfDataFound	if set to `false`, will trigger loading UI even if data had been cached	`true`
reducerName	The reducer name used for the entity. Default is the plural form of the entityName	`[entityName]s`
preloadValidTime	The time (milliseconds) that a preloaded query is valid and should not be re-fetched	`10000`
smartPreload	If set to `true` the library times the network calls specific to the defined entity. If the average is greater than 0.3 seconds, preloading will be cancelled. Overwrite this time with the next field	`false`
smartThresholdTime	The acceptable average time (milliseconds) for network calls to continue preloading in `smartPreload` mode	`300`

Properties injected to the wrapped component

property (props)	Explanation	Example	Sample value
entityNames	The query result	`contacts`	`[{id: 1, name: 'John Doe'}]`
entityNamesQueryParams	The last successful parameters with which query was performed	`contactsQueryParams`	`{page: 1}`
entityNamesMetadata	The metadata that is received from the endpoint	`contactsMetadata`	`{totalPages: 10}`
initialQueryEntityNames	A must-be-called function that initializes the query. Receives url and parameters (object)	`initialQueryContacts('/contacts/', {page: 1})`
queryEntityNames	Any query after initial query call. It will append the new partial params on top of the previous ones	`queryContacts({pageSize: 1})`
createEntityName	Creates an object and performs the latest query again	`createContact({name: 'Foo Bar'})`
updateEntityName	Updates/replaces an entity. After success, will update the store and queries again	`updateContact({id: 1, name: 'Foo Bar'})`
patchEntityName	Patches an entity. After success, will update the store and queries again	`patchContact({id: 1, name: 'Foo Bar'})`
deleteEntityName	Removes an entity. After success, will update the store and queries again	`deleteContact({id: 1, name: 'Foo Bar'})`
setEntityNamesPreloader	Sets a function for pre-loading data for a smooth UX	`setContactsPreloader(customPreloader)`*
loadingEntityNames	Network loading status	`loadingContacts`	`true`

*Note: the preloader function will receive (partialParams, params, queryMetadata) as arguments. The function should return an array of partialParams. See the preloading section for more information

detailedEntity

if you intend to work with an endpoint that returns a detailed entity use detailedEntity to decorate your components:

import { detailedEntity } from 'rest-react-redux';

@detailedEntity('contact')
class ContactsPage extends React.Component {
    ...
}

detailedEntity(entityName, configoptional)

Config field	Explanation	Default Value
retain_number	maximum number of queries to cache	`10`
hideLoadIfDataFound	if set to `false`, will trigger loading UI even if data had been cached	`true`
reducerName	The reducer name used for the entity. Default is the entityName	`[entityName]`

Properties injected to the wrapped component

property (props)	Explanation	Example	Sample value
entityName	The result	`contact`	`{id: 1, name: 'John Doe'}`
initialGetEntityNames	A must-be-called function that initializes the entity. Receives url and object id	`initialGetContacts('/contacts/12', 12)`
getEntityName	Any get call after the initial get call. This is usually used for receiving updates if any	`getContact()`
updateEntityName	Updates/replaces the entity. After success, will update the store and gets again	`updateContact({id: 1, name: 'Foo Bar'})`
patchEntityName	Patches the entity. After success, will update the store and gets again	`patchContact({id: 1, name: 'Foo Bar'})`
deleteEntityName	Removes the entity. After success, will update the store	`deleteContact({id: 1, name: 'Foo Bar'})`
loadingEntityName	Network loading status	`loadingContact`	`true`

Preloading

For a better user experience, you may pre-load the data that have a good chance of being loaded later. There are two main methods of preloading data:

Entity specific preloading

If you are dealing with a queried entity like calendar events, table data, chat messages etc. it might be a good idea to dynamically preload data based on what the user queries. For instance, loading the previous and the next pages of a table sounds like a good investment! To do that you simply need to set a function via property set[EntityName]sPreloader:

import { queriedEntity } from 'rest-react-redux';

@queriedEntity('contact')
class ContactsPage extends React.Component {
    
    componentDidMound() {
        this.props.initialQueryContacts('/contacts/', {page: 1, size: 20});
        this.props.setContactsPreloader((partialParams) => {
            
            const page = partialParams.page;
            
            // If the query does not contain a new page do not preload
            if (!partialParams.page) return [];
            
            // Preload previous and next pages
            return [{page: page - 1}, {page: page + 1}];
        })
    }
}

Generic preloading

You may need to preload entities that are not related to the component you are focusing at. For instance, if a user gets to the main dashboard, you want to preload all the contacts before the user goes to the contacts page. To achieve that you can use the exposed queryEntities or getEntity action generators:

queryEntities(entityName, url, params)
getEntity(entityName, url)

Usage example:

import { queryEntities, getEntity } from 'rest-react-redux';
import store from '../store';

class Dashboard extends React.Component {
    
    componentDidMound() {
        // Preload a contact list query
        store.dispatch(queryEntities('contact', '/contacts/', {page: 1}));
        
        // Preload a detailed contact
        store.dispatch(getEntity('contact', '/contacts/1'));
    }
}