# @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) [](/redux-rest-easy/master.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](/redux-rest-easy/master.md#minimal-example) for a small example, or [browse the documentation](/redux-rest-easy/master.md#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](/redux-rest-easy/docs/api/createresource-1.md) - easily generate then export your actions and selectors from one file
* [reducer](/redux-rest-easy/docs/api/reducer.md) - plug a single reducer to your state, we handle the rest
* [connect](/redux-rest-easy/docs/api/connect.md) - connect your components to the state so the magic can happen
* [reset](/redux-rest-easy/docs/api/reset.md) - reset `redux-rest-easy`'s whole state (you can reset parts of the state with actions generated by `createResource`)
* [initializeNetworkHelpers](/redux-rest-easy/docs/api/initializenetworkhelpers.md) - provide your own network handlers (optional, fallback to included defaults)
* [getPersistableState](/redux-rest-easy/docs/api/getpersistablestate.md) - 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](/redux-rest-easy/docs/api/createresource/actionsconfig.md) - defining your actions with `createResource`
* [Actions](/redux-rest-easy/docs/api/createresource/actions.md) - actions generated by `createResource`
* [Selectors](/redux-rest-easy/docs/api/createresource/selectors.md) - selectors generated by `createResource`
## Core principles
1. [Preflight checks](/redux-rest-easy/docs/principles/preflight.md)
2. [Actions](/redux-rest-easy/docs/principles/actions.md)
3. [Reducers](/redux-rest-easy/docs/principles/reducers.md)
4. [Selectors](/redux-rest-easy/docs/principles/selectors.md)
## 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!
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://brigad.gitbook.io/redux-rest-easy/master.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.