Redux Resource

A tiny but powerful system for managing 'resources': data that is persisted to remote servers.

✓ Removes nearly all "boilerplate" code for remotely-stored data
✓ Tracks the status (pending, failed, success, etc.) of every request
✓ Encourages normalized state
✓ Works well with APIs that adhere to standardized formats, such as JSON API
✓ Works well with APIs that don't adhere to standardized formats, too
✓ Integrates well with lots of technologies: HTTP, GRPC, streams, redux-observable, redux-saga, and more
✓ Microscopic file size (2kb gzipped!)

Installation

To install the latest version:

npm install --save redux-resource@2.0.0-beta1

Documentation

View the documentation at redux-resource.js.org ⇗.

Quick Start

Follow this guide to get a taste of what it's like to work with Redux Resource.

First, we set up our store with a "resource reducer," which is a reducer that manages the state for one type of resource. In this guide, our reducer will handle the data for our "books" resource.

import { store, combineReducers } from 'redux';
import { resourceReducer } from 'redux-resource';

const reducer = combineReducers({
  books: resourceReducer('books')
});

const store = createStore(reducer);

Once we have a store, we can start dispatching actions to it. In this example, we initiate a request to read a book with an ID of 24, then follow it up with an action representing success. There are two actions, because requests usually occur over a network, and therefore take time to complete.

import { actionTypes } from 'redux-resource';
import store from './store';

// This action represents beginning the request to read a book with ID of 24. This
// may could represent the start of an HTTP request, for instance.
store.dispatch({
  type: actionTypes.READ_RESOURCES_PENDING,
  resourceName: 'books',
  resources: [24]
});

// Later, when the request succeeds, we dispatch the success action.
store.dispatch({
  type: actionTypes.READ_RESOURCES_SUCCEEDED,
  resourceName: 'books',
  // The `resources` list here is usually the response from an API call
  resources: [{
    id: 24,
    title: 'My Name is Red',
    releaseYear: 1998,
    author: 'Orhan Pamuk'
  }]
});

Later, in your view layer, you can access information about the status of this request. When it succeeds, accessing the returned book is straightforward.

import { getStatus } from 'redux-resource';
import store from './my-store';

const state = store.getState();
// The second argument to this method is a path into the state. This method
// protects you from needing to check for undefined values.
const readStatus = getStatus(store, 'books.meta.24.readStatus');

if (readStatus.pending) {
  console.log('The request is in flight.');
}

else if (readStatus.failed) {
  console.log('The request failed.');
}

else if (readStatus.succeeded) {
  const book = state.books.resources[24];

  console.log('The book was retrieved successfully, and here is the data:', book);
}

This is just a small sample of what it's like working with Redux Resource.

For a real-life webapp example that uses many more CRUD operations, check out the zero-boilerplate-redux webapp ⇗. This example project uses React, although Redux Resource works well with any view layer.

Repository Structure

This repository is a Lerna project. That means it's a single repository that allows us to control the publishing of a number of packages:

Package	Version	Size	Description
`redux-resource`			The main library
`redux-resource-xhr`			A library that includes basic CRUD action creators
`redux-resource-plugins`			A collection of common plugins
`redux-resource-prop-types`			Handy Prop Types to use with Redux Resource