# @brigad/redux-rest-easy
Redux/React/React Native framework handling network requests, state management, selectors, caching and much more
[](https://circleci.com/gh/Brigad/redux-rest-easy) [](https://codecov.io/gh/Brigad/redux-rest-easy) [](https://www.npmjs.com/package/@brigad/redux-rest-easy) [](https://www.npmjs.com/package/@brigad/redux-rest-easy) [](https://github.com/Brigad/redux-rest-easy/blob/master/LICENSE.md) [](#contributors) [](http://makeapullrequest.com) [](https://github.com/Brigad/redux-rest-easy/blob/master/CODE_OF_CONDUCT.md) [](https://github.com/prettier/prettier) [](https://github.com/semantic-release/semantic-release) [](https://github.com/Brigad/redux-rest-easy/stargazers)
## [Release article](https://engineering.brigad.co/introducing-redux-rest-easy-6e9a91af4f59)
## Installation
```bash
yarn add @brigad/redux-rest-easy
```
Or, if you are using npm:
```bash
npm install --save @brigad/redux-rest-easy
```
## Problem
At Brigad, we have been extensively using redux and redux-thunk to perform network requests, and store/access the resulting data, and we always felt some pain points, or at least like there were things we could do better:
* We were often **copying/pasting a lot of code** (along with some logic regarding caching, hooks, etc) from one file to another each time we would create a new resource or action
* Our state was **not organized at all**, and accessing it was messy and error-prone
* We had a huge **caching problem**: sometimes performing unnecessary requests, sometimes not performing requests which should have been
* We had no way to know if **a given component was performing an action**, we only knew if an action was being performed on a given resource
## Solution
To solve the problems listed above, `redux-rest-easy` **generates actions, reducers, and selectors**, and also **manages the state's data and metadata** for your **network requests**. It is easy to use, and to observe via the Redux Devtools.
It also provides **sensible defaults**, allowing you to use it with **almost no configuration**, but also to **customize** anything you would like.
And the cherry on the top: it works seamlessly with [redux-offline](https://github.com/redux-offline/redux-offline) and [redux-persist](https://github.com/rt2zz/redux-persist)!
[Scroll down](#minimal-example) for a small example, or [browse the documentation](#api) to get started! To learn more about the problem and solution, you can also read the [release article](https://engineering.brigad.co/introducing-redux-rest-easy-6e9a91af4f59).
## API
```javascript
import {
createResource,
reducer,
connect,
reset,
initializeNetworkHelpers,
getPersistableState,
} from '@brigad/redux-rest-easy';
```
* [createResource](https://brigad.gitbook.io/redux-rest-easy/docs/api/createresource-1) - easily generate then export your actions and selectors from one file
* [reducer](https://brigad.gitbook.io/redux-rest-easy/docs/api/reducer) - plug a single reducer to your state, we handle the rest
* [connect](https://brigad.gitbook.io/redux-rest-easy/docs/api/connect) - connect your components to the state so the magic can happen
* [reset](https://brigad.gitbook.io/redux-rest-easy/docs/api/reset) - reset `redux-rest-easy`'s whole state (you can reset parts of the state with actions generated by `createResource`)
* [initializeNetworkHelpers](https://brigad.gitbook.io/redux-rest-easy/docs/api/initializenetworkhelpers) - provide your own network handlers (optional, fallback to included defaults)
* [getPersistableState](https://brigad.gitbook.io/redux-rest-easy/docs/api/getpersistablestate) - transform the state before storing it, in order to later persist it (using [redux-offline](https://github.com/redux-offline/redux-offline), [redux-persist](https://github.com/rt2zz/redux-persist), or friends)
## Internals
* [Actions configuration](https://brigad.gitbook.io/redux-rest-easy/docs/api/createresource/actionsconfig) - defining your actions with `createResource`
* [Actions](https://brigad.gitbook.io/redux-rest-easy/docs/api/createresource/actions) - actions generated by `createResource`
* [Selectors](https://brigad.gitbook.io/redux-rest-easy/docs/api/createresource/selectors) - selectors generated by `createResource`
## Core principles
1. [Preflight checks](https://brigad.gitbook.io/redux-rest-easy/docs/principles/preflight)
2. [Actions](https://brigad.gitbook.io/redux-rest-easy/docs/principles/actions)
3. [Reducers](https://brigad.gitbook.io/redux-rest-easy/docs/principles/reducers)
4. [Selectors](https://brigad.gitbook.io/redux-rest-easy/docs/principles/selectors)
## Minimal Example
```javascript
// users.js
import { createResource } from '@brigad/redux-rest-easy';
const users = createResource('users')({
retrieve: {
method: 'GET',
url: 'https://my-api.com/users',
afterHook: () => console.log('Users retrieved successfully'),
},
});
const {
actions: { retrieve: retrieveUsers },
selectors: {
resource: { getResource: getUsers },
retrieve: {
request: { isPerforming: isRetrievingUsers },
},
},
} = users;
export { retrieveUsers, getUsers, isRetrievingUsers };
```
```javascript
// reducers.js
import { reducer } from '@brigad/redux-rest-easy';
const reducers = combineReducers({
restEasy: reducer,
});
```
```javascript
// UsersList.js
import React, { Component } from 'react';
import { connect } from '@brigad/redux-rest-easy';
import {
retrieveUsers,
getUsers,
isRetrievingUsers,
} from './redux-rest-easy/users';
class UsersList extends Component {
state = {
error: false,
};
componentDidMount() {
this.props.retrieveUsers(this.onSuccess, this.onError);
}
onSuccess = () => {
this.setState({ error: false });
};
onError = () => {
this.setState({ error: true });
};
render() {
if (this.props.isRetrievingUsers) {
return {'Loading...'}
;
}
if (this.state.error) {
return (
{'There seems to be a problem... A network error occured.'}
);
}
return ;
}
}
const mapStateToProps = state => ({
users: getUsers(state),
isRetrievingUsers: isRetrievingUsers(state),
});
const mapDispatchToProps = dispatch => ({
retrieveUsers: (onSuccess, onError) =>
dispatch(retrieveUsers({ onSuccess, onError })),
});
export default connect(
mapStateToProps,
mapDispatchToProps,
)(ConnectedComponent);
```
## Peer dependencies
Redux-rest-easy assumes you are using [react](https://github.com/facebook/react) (or [react-native](https://github.com/facebook/react-native)) and [react-redux](https://github.com/reactjs/react-redux).
Redux-rest-easy also uses [redux-thunk](https://github.com/gaearon/redux-thunk) under the hood, to handle async actions, and therefore requires you to use redux-thunk's middleware in your store. If you are already using redux-thunk, then you have nothing more to do. Else, follow [redux-thunk's docs](https://github.com/gaearon/redux-thunk#installation) for a quick setup.
## Examples
### [Simple Example](https://codesandbox.io/s/ko7xm5wxy7)
Displays a list of users and allows to create new ones.
### Pagination (TODO, coming soon)
Displays a paginated list, with seamless query-based selectors and cache.
### Data invalidation (TODO, coming soon)
Invalidates store data after a successful POST request
### Multiple requests (e.g. S3 signed upload) (TODO, coming soon)
Performs multiple requests in beforeHook before the final one, to upload a signed file to S3.
### Cache hints (TODO, coming soon)
Makes use of cache hints to customize the built-in cache.
### Store persistence (TODO, coming soon)
Introduces store persistence in the "Pagination" example, so that data persists after the page is refreshed.
## Contributors
Thanks goes to these people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
| 
Adrien HARNAY
📝 💻 📖 🤔 🚇 👀 ⚠️
| 
Thibault Malbranche
🐛 💻 🤔 👀
| 
Grisha Ghukasyan
🤔
| 
Aymeric Beaumet
🤔
| 
Jess
🐛 📖
| 
Matt Labrum
💻
|
| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
This project follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification. Contributions of any kind welcome!