redux-and-the-rest v6.1.6

Declarative, flexible Redux integration with RESTful APIs.

Feature overview

• DRY: All of the boilerplate code usually required to use Redux is abstracted away into a succinct DSL inspired by the Ruby on Rails framework.
• Convention over configuration: A sensible set of configurations are used by default, but you can override them with custom behaviour whenever you need.
• Flexible: All RESTful conventions can be overridden and extended when you need to deviate or add to the standard CRUD functionality.
• Minimal: You can choose which features to enable, when you want to use them, so there is no unnecessary overhead or bloat.
• Quick to get started: It's quick to get up-and-running and easy to define new resources and actions in a few lines.
• Plays well with others: redux-and-the-rest does not care what version of Redux you use or how you have architected your app, and it allows you to gradually introduce it to your project alongside other Redux solutions.
• Documented: The API is minimal and expressive, and all options and common use cases are documented in full.
• Tested: redux-and-the-rest comes with an extensive test suite.

Design philosophy

redux-and-the-rest loosely takes its lead from Reduced Instruction Set Computing (RISC) and the standard Create, Read, Update, Delete (CRUD) paradigm and offers as few low-level reducers and actions as possible. In doing so, it allows more re-use and sharing of code, and reduces the overhead of scaling out a store for large applications.

You are encouraged to write your own helper functions on top of the action creators redux-and-the-rest provides for more nuanced updates, where needed (details and examples follow).

Basic usage

import { resources } from 'redux-and-the-rest';
import { createStore, applyMiddleware, combineReducers } from 'redux';
import Thunk from 'redux-thunk';

/**
 * Define a users resource
 */
const { reducers: usersReducers, actionCreators: { fetchList: fetchUsers }, getList } = resources(
    {
        name: 'users',
        url: 'http://test.com/users/:id?'.
        keyBy: 'id'
    },
    {
        fetchList: true
    }
);

/**
 * Pass the reducers to your store (the reducers for only one resource is used -
 * normally you would have many)
 */
const store = createStore(combineReducers({ users: usersReducers }), {}, applyMiddleware(Thunk));

/**
 * Action to fetch the users from http://test.com/users and make them available in your store
 */
fetchUsers();

/**
 * Retrieve the users from the store
 */
users = getList(store.getState().users);

Quick Reference

You can find more examples and a walk-through style introduction of how to make the most of redux-and-the-rest in the Quick Reference.

Contents

• Install & Setup
  • Peer Dependencies
• Defining resources
  • Configuring individual actions
    • Using the default RESTful action configuration
    • Providing custom action configuration
  • Actions and their action creators
    • CRUD actions
      • Local CRUD actions
      • Remote API CRUD actions
    • Clearing actions
    • Selection actions
  • Dispatchers
• Defining associations
  • One-to-One and One-to-Many relationships
  • Many-to-Many relationships
• Connecting to React
  • Usage with react-redux
• API Reference
  • Levels of configuration
  • Global Options API
    • Usage
    • Options
  • Resource Options API
    • Usage
    • Options
      • Naming and indexing
      • Synchronising with a remote API
      • Reducers
  • Action Options API
    • Usage
    • Options
      • Naming and indexing
      • Synchronising with a remote API
      • Reducers
• Store data
  • Getting items from the store
  • Automatically fetching items not in the store
  • Automatically instantiating new items not in the store
  • Getting lists from the store
    • Automatically fetching lists that are not in the store
  • Store data schemas
    • Nomenclature
    • Use helper methods where possible
    • Resource schema
      • Top level schema
      • Item schema
      • List schema
  • Data lifecycle
    • Client statuses
    • Pending statuses
    • Response statuses
• Setting initial state
• RESTful (asynchronous) actions
  • RESTful behaviour overview
    • Preventing duplicate requests
    • Dealing with failed requests
    • Dealing with slow requests
    • Detecting old data
  • Fetch a list from the server
    • fetchList action creator options
  • Fetch an individual item from the server
    • Fetch action creator options
  • Create a new item on the server
    • Adding a created item to a list
  • Update a item on the server
    • Update action creator options
  • Destroy a item on the server
    • DestroyItem action creator options
• Local (synchronous) actions
  • Add a new item to the store
    • NewItem action creator options
  • Clear the new item from the store
  • Edit the new item in the store
  • Edit an existing item in the store
  • Edit an item without worrying whether it's new or not
  • Detecting if a item has been edited
  • Accessing values before they were edited
  • Clear local edits
  • Select a item in the store
  • Select another item in the store
  • Deselect a item in the store
  • Clear all the selected items in the store
  • Clearing a resource when a user signs out or other event
• Configuring requests
  • Configuring the URLs used for a request
    • URL Parameters
      • Using string values
      • Using object values
      • Specifying query parameters
    • Adapting request bodies
    • Pagination
  • Working with Authenticated APIs
    • Auth tokens as headers
    • Auth tokens as query parameters
    • Session cookies
  • Configuring other request properties
• Adapting responses
  • Adapting success responses

  • Handling error responses

Install & Setup

redux-and-the-rest can be installed as a CommonJS module:

npm install redux-and-the-rest --save
# OR
yarn add redux-and-the-rest

Peer Dependencies

If you have already installed redux; redux-thunk; some form of fetch polyfill (suggested: isomorphic-fetch); and (optionally) react-redux, then you can skip to the next section.

If you have not already done so, you must also install redux (full installation):

npm install redux --save
# OR
yarn add redux

redux-and-the-rest also requires the redux-thunk middleware to function:

npm install redux-thunk --save
# OR
yarn add redux-thunk

You must then pass the redux-thunk middleware in as a parameter when you create your Redux store (full instructions):

import { createStore, applyMiddleware, combineReducers } from 'redux';
import Thunk from 'redux-thunk';

function buildStore(initialState, reducers) {
  return createStore(combineReducers(reducers), initialState, applyMiddleware(Thunk));
}

export default buildStore;

If you are using React, it's also recommended to use the react-redux bindings (full instructions):

npm install react-redux --save
# OR
yarn add react-redux

Finally, you will also need to ensure global calls to the fetch method work in all your environments (node.js and browser). The simplest way to do this is to install isomorphic-fetch (full instructions):

npm install --save isomorphic-fetch es6-promise
# OR
yarn add isomorphic-fetch es6-promise

Defining resources

Resources are defined with one of two functions:

• resources - For when there are many resources, each referenced with one or more ids or keys, or
• resource - For singular resources; cases where there is only one like the current user's profile

They both accept two options hashes as arguments:

• resourceOptions - options that apply to all of a resource's actions
• actionOptions - options that configure individual actions (RESTful or not)

The functions return an object containing Redux components necessary to use the resource you have just defined:

• reducers - an object of reducers that you can pass to Redux's combineReducers function.
• actions - an object of action constants where the keys are the generic action names and the values are the specific action constants (e.g. { fetchList: 'FETCH_USERS' })
• actionCreators - an object of functions (action creators) you call to interact with the resource which match the actions you specify in actionOptions and are passed to Redux's dispatch function.

Also returned are 3 helper functions that are always available:

• getList - for retrieving a list based on its key parameters
• getItem - for retrieving an item based on its key parameters
• getNewItem - for retrieving the item currently being created
• getNewOrExistingItem - for first attempting to retrieve and existing item and then falling back to returning the new item currently being created

In addition to these, if you enable the underlying actions, the following helper functions are also exported:

• getOrFetchItem - Retrieves an item from the Redux store, or makes a fetch request for it, if it's not available
• getOrFetchList - Retrieves a list from the Redux store, or makes a fetch request for it, if it's not available
• getOrInitializeItem - Retrieves the new item from the Redux store, or instantiates it with the provided values, if it's not available
• saveItem - Creates an item (by sending a POST request) if it's not already in the store, or has a status of NEW, otherwise sends and UPDATE request with the values provided.

Each of these can be thought of as helpers that contain common logic to determine which underlying action creator to invoke. They require the store option to be used with configure(), so they can manually call dispatch as appropriate (consequently, these are not action creators and should not have their return values passed to dispatch).

Their first argument must be the current resource's state in the Redux store, and all others are passed to the action creators they wrap.

These methods are asynchronous (they return a value immediately but do not dispatch any actions synchronously to avoid React warnings about updating other component's state during a render cycle when used with react-redux) and throttled (so if multiple components on the same React tree call them in the same render cycle, only one action is dispatched), so they are safe to use in component's render functions.

import { resources } from 'redux-and-the-rest';

const { reducers, actionCreators: { fetchList: fetchUsers } } = resources(
    {
        name: 'users',
        url: 'http://test.com/users/:id?',
        keyBy: 'id'
    },
    {
        fetchList: true
    }
);

Configuring individual actions

actionOptions specifies the actions defined for a particular resource and allow you to expand upon, or override, the configuration made in resourceOptions.

actionOptions should be an either one of two formats:

An array of action names as strings:

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // ...
    },
    [ 'fetchList' ]
);

This format is shorter, and recommended unless you need the second format.

The other format is an object with action names as keys and configuration objects as values.

Using the default RESTful action configuration

If you want to use the default configuration for a particular action, you just need to pass a value of true, for example:

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // ...
    },
    { fetchList: true }
);

Providing custom action configuration

You can override or extend the default configuration for an action using an options hash instead of true when defining your actions:

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // ...
    },
    {
        fetchList:  {
            // action options
        }
    }
);

See Action Options API for a full list of supported options.

Actions and their action creators

CRUD actions

It's common to think about interacting with resources in terms of 4 primary operations: create, read, update, delete (CRUD). redux-and-the-rest provides local (client-side) actions to refine the input state of each of these operations, and the remote API actions to persist or submit them.

Local CRUD actions

Generally your application will need to perform actions on resources locally, until a point is reached where those changes should be synchronised with a remote API. None of them make any requests to a remote API and are client-side operations that happen only in your Redux store.

These actions are generally accumulative and reversible, so you can call them successively over multiple screens or stages of a workflow and provide a cancel feature if the user wishes to abort.

Remote API CRUD actions

When the your application is done with local manipulation of a resource, you can use the following to persist those changes to a remote API.

resources() accepts a localOnly option, that allows you to maintain resources without a remote API and will turn the asynchronous remote API actions into synchronous updates that label your resources as being in a "saved" state.

Clearing actions

It's generally not recommended to use any of the following directly, as there is usually a better way of achieving what you need, but they are available:

Some common situations where you may be tempted to use the above, are:

• Refreshing an item or list from a remote API: fetchItem() or fetchList() should handle transitioning between the stale and new records more cleanly.
• Cancelling an edit to an item: Use clearItemEdit() to roll back the changes without the need to re-fetch from the remote API.
• Clearing a resource when an event occurs, such as when user logs out: use the clearOn option to achieve this more efficiently (discussed below).

Selection actions

In addition to the CRUD functionality, redux-and-the-rest provides a number of actions for selecting one or more items to perform actions on. This is useful if your application needs to selectItem resources on one screen or area and persist that selection to another area, or allow it to be retrieved at a later time.

Dispatchers

redux-and-the-rest exports action creators in the actionCreators object of every resource definition, which return objects (actions) that are ready to be passed to redux's dispatch function (as users of redux are accustom to doing).

However, for convenience, redux-and-the-rest also exports dispatchers, which are functions that call dispatch for you, and are useful in circumstances where the dispatch function is not readily available. They have the same name as their action creator counterparts, accept the same arguments, and are enabled with the same configuration when defining your resource or resources.

They are available directly off the exported object:

const { actionCreators: { fetchList: fetchUsersActionCreator }, fetchList: fetchUsersDispatcher } = resources(
    {
        // ...
    },
    {
        fetchList:  {
            // action options
        }
    }
);

Defining associations

You can define associations between resources so that their foreign keys are properly maintained as you add, update and remove related resources.

Once associated, if the associated resource is deleted, it will be removed from the foreign keys of any related items of the current resource.

If a new item of the associated resource is created with a foreign key pointing at an item of the current resource, it's key will be added to the list of foreign keys.

If an existing associated item is updated and the current resource items are swapped, this will also be handled.

You define associations on the resources you want to be updated when the associated resource changes. If you need the updates to work both ways, you'll need to define both sides of the association.

Association configuration come in two forms: belongsTo and hasAndBelongsTo. Each expects an array of resource names (values that you provide to the name attribute when defining those resources), or an object, where the keys are the names of the associated resources, and the values are a configuration object containing the following options:

• foreignKey - (string) Name of the attribute that stores the id or ids of the current resource on the associated one. If unspecified, the as attribute (or the resource's name value) are appended with the suffix of id.

• as - (string) If a foreign key is not specified, this association name is used with a suffix of id to derive the foreign key.

• key - (string)

• dependent - (boolean) Whether to remove the associated resource if the current one is removed from the store.

One-to-One and One-to-Many relationships

The belongsTo resource option is used to define a one-to-one and one-to-many relationships.

import { resources } from 'redux-and-the-rest';

const addresses = resources({
  name: 'addresses',
  url: 'http://test.com/addresses/:id?',
  keyBy: 'id'
}, ['createItem', 'updateItem', 'destroyItem']);
                                     

const users = resources({
    name: 'users',
    url: 'http://test.com/users/:id?',
    keyBy: 'id',
    belongsTo: ['addresses']
  }, {
    fetchList: true,
    newItem: true,
  });     
                                                                                   
/**
 * The following will add 'temp' to 'addressIds' of the user with id '1' (if it exists in the store).
 */
addresses.actionCreators.createItem({ id: 'temp' }, { userId: 1, city: 'Boston' });

Many-to-Many relationships

The hasAndBelongsToMany resource option is used to define many-to-many relationships. It behaves and accepts the same arguments as belongsTo, but correctly maintains an array of foreign keys on items of the resource being defined, rather than a single id. For example, if each user item has an addressId with a singular value, use belongsTo, however if a user item has an addressesId with an array if address ids, use hasAndBelongsToMany.

Connecting to React

Usage with react-redux

Although not required, when using redux-and-the-rest with React, it's recommended you use react-redux. It provides the connect function, which accepts two arguments:

The full API can be seen in the docs.

Because redux-and-the-rest is built around the principle of providing a reduced set of reducers for the standard CRUD operations (with a few extras for selection and clearing), you're expected to define utility functions for performing "sub-operations". Take the example of a widget that sets the user's age: you only want to modify one of the the user items's values, but you need to provide the entire new set of values back to redux-and-the-rest (this is to allow for removal of attributes and complex or deep merging that redux-and-the-rest cannot be expected to guess).

Because the connect function separates access to dispatch (mapDispatchToProps) and access to the current Redux state (mapStateToProps), you have a few options.

When your component needs access to all the resource's attributes anyway, you can pass the whole item into your component and then back out again in the handler:

import { connect } from 'react-redux'

import { getUser, updateUser } from './resources/users';    
import AgeWidget from './components/AgeWidget';

const mapStateToProps = ({ user } ) => {
  return {
    user: getUser(user)
  }
};

const mapDispatchToProps = ((dispatch) => {
  return {
    updateAge: (user, newAge) => dispatch(updateUser({ ...user, age: newAge }))
  };
});

export default connect(
  mapStateToProps,
  mapDispatchToProps
)(AgeWidget)

And you would then call it in your component:

<Button onPress={updateAge(user.values, user.values.age + 1)} >
  Increment
</Button>

You may also choose to use connect's third argument to curry your handler props:

import { connect } from 'react-redux'

import { getUser, updateUser } from './resources/users';    
import AgeWidget from './components/AgeWidget';

const mapStateToProps = ({ user } ) => {
  return {
    user: getUser(user)
  }
};

const mapDispatchToProps = ((dispatch) => {
  return {
    updateAge: (values, newAge) => dispatch(updateUser({ ...values, age: newAge }))
  };
});         

const mergeProps = ((stateProps, dispatchProps, ownProps) => {
  return {
    ...stateProps,
    ...dispatchProps,
    updateAge: (newAge) => dispatchProps.updateAge(stateProps.user.values, newAge),
    ...ownProps
  }   
});

export default connect(
  mapStateToProps,
  mapDispatchToProps,
  mergeProps
)(AgeWidget)

And call it in your component with the reduced argument list:

<Button onPress={updateAge(user.values.age + 1)} >
  Increment
</Button>

However, if your component doesn't need access to the rest of the user's attributes it's recommended that you keep the component's interface minimal and your handler arguments as few as possible and just retrieve the state directly from the store when it's needed in your handlers:

import { connect } from 'react-redux'

import { getUser, updateUser } from './resources/users';
import store from './store';    
import AgeWidget from './components/AgeWidget';

const mapStateToProps = ({ user } ) => {
  return {
    user: getUser(user)
  }
};

const mapDispatchToProps = ((dispatch) => {
  return {
    updateAge: (newAge) => {
      const { values } = getUser(store.getState().users); 
      
      dispatch(updateUser({ ...values, age: newAge }));
    }   
  };
});

export default connect(
  mapStateToProps,
  mapDispatchToProps
)(AgeWidget)

Or alternatively, you can chose not to pass down the attributes you only needed to make available to your handlers:

import { connect } from 'react-redux'

import { getUser, updateUser } from './resources/users';    
import AgeWidget from './components/AgeWidget';

const mapStateToProps = ({ user } ) => {
  return {
    user: getUser(user)
  }
};

const mapDispatchToProps = ((dispatch) => {
  return {
    updateAge: (user, newAge) => dispatch(updateUser({ ...user, age: newAge }))
  };
});         

const mergeProps = ((stateProps, dispatchProps, ownProps) => {
  // The final list of props passed to your component
  return {
    age: stateProps.user.values.age,
    updateAge: (newAge) => dispatchProps.updateAge(stateProps.user.values, newAge),
    ...ownProps
  }   
});

export default connect(
  mapStateToProps,
  mapDispatchToProps,
  mergeProps
)(AgeWidget)

Either option will allow you to call the handler in your component with only the new values:

<Button onPress={updateAge(age + 1)} >
  Increment
</Button>

API Reference

Levels of configuration

redux-and-the-rest achieves its flexibility using four levels of configuration; each one has a different scope and is specified at different times.

You need to selectItem where you place your configuration depending on how wide you want particular options to apply, and when the desired values are available.

The options are set out in a hierarchy, so as their scope becomes increasingly specific, their priority increases and they override any corresponding action that may have been provided to a lower priority set of options.

For example, actionCreatorOptions take precedence over actionOptions (which take precedence over resourceOptions).

Here is an example of them used all in once place:

import { configure, resources } from 'redux-and-the-rest';

configure({
    // globalOptions
    // ...
});

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // resourceOptions
        name: 'users',
        url: 'http://www.example.com/users/:id',
        keyBy: 'id'
    },
    {
        fetchList: {
            // actionOptions
            // ...
        },
        fetch: {
            // actionOptions
            // ...
        }
    }
);

fetchUsers({order: 'newest'}, {
  // actionCreatorOptions
  // ...
})

Global Options API

Usage

import { configure } from 'redux-and-the-rest';

configure({
  // globalOptions
});

Options

Resource Options API

Values passed to resourceOptions are used to configure the resource and apply to all of that resource's actions, unless overridden by more specific configuration in actionOptions.

Usage

import { resources } from 'redux-and-the-rest';

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // resourceOptions
    },
    {
        // ...
    }
);

Options

Naming and indexing

Synchronising with a remote API

Reducers

The reducer functions used in the beforeReducers, afterReducers and reducesOn options accept 3 arguments:

• The current resource(s) Redux state (not the entire Redux state)
• The current action being dispatch (not restricted to only those defined on the current resource being defined)
• An object of getter and reducer helper functions (to avoid having to manipulate the internal structure directly)

The helper object contains the following methods:

• getItemStatus(state, params): Returns the status of an item by providing its params

• mergeItemStatus(state, params, newStatus): Returns a copy of current resource's redux state with an item's status merged with new values

• getItemValues(state, params): Returns the values of an item by providing its params

• mergeItemValues(state, params, newValues): Returns a copy of current resource's redux state with an item's values merged with new values
• replaceItemValues(state, params, values): Returns a copy of current resource's redux state with an item's values replaced by new values
• clearItemValues(state, params): Returns a copy of current resource's redux state with an item's values cleared

• clearItem(state, params): Returns a copy of current resource's redux state with an item omitted

• getItemMetadata(state, params): Returns the metadata of an item by providing its params

• mergeItemMetadata(state, params, metadata): Returns a copy of current resource's redux state with an item's metadata merged with new metadata
• replaceItemMetadata(state, params, metadata): Returns a copy of current resource's redux state with an item's metadata replaced by new metadata

• clearItemMetadata(state, params): Returns a copy of current resource's redux state with an item's metadata cleared

• getListStatus(state, params): Returns the status of an list by providing its params

• mergeListStatus(state, params, newStatus): Returns a copy of current resource's redux state with an list's status merged with new values

• getListPositions(state, params): Returns the positions of an list by providing its params

• removeItemFromListPositions(state, listParams, itemParams): Returns a copy of current resource's redux state with item's key removed from the list specified

• replaceListPositions(state, params, positions): Returns a copy of current resource's redux state with an list's positions replaced by new positions

• getListMetadata(state, params): Returns the metadata of an list by providing its params

• mergeListMetadata(state, params, metadata): Returns a copy of current resource's redux state with a list's metadata merged with new metadata
• replaceListMetadata(state, params, metadata): Returns a copy of current resource's redux state with a list's metadata replaced by new metadata

• clearListMetadata(state, params): Returns a copy of current resource's redux state with a list's metadata cleared

• clearList(state, params): Returns a copy of current resource's redux state with a list omitted

• deselectItem(state, params): Returns a copy of current resource's redux state with the item no longer selected
• deselectItems(state, params[]): Returns a copy of current resource's redux state with the items specified no longer selected
• selectAnotherItem(state, params): Returns a copy of current resource's redux state with an item selected (without clearing those already selected)
• selectMoreItems(state, params[]): Returns a copy of current resource's redux state with the items selected (without clearing those already selected)
• selectItem(state, params): Returns a copy of current resource's redux state with only a single item selected
• selectItems(state, params[]): Returns a copy of current resource's redux state with only the listed items selected

• clearSelectedItems(state, params): Returns a copy of current resource's redux state with no items selected

• clearResource(): Returns an empty singular resource state, for clearing the entire resources

• clearResources(): Returns an empty resource state, for clearing the entire resource

Action Options API

actionOptions are used to configure individual resource actions and override any options specified in globalOptions or resourceOptions. They are the most specific level of options available at the time that resources are defined and can only be superseded by options provided to action creators when they are called.

Usage

import { resources } from 'redux-and-the-rest';

const { actionCreators: { fetchList: fetchUsers } } = resources(
    {
        // ...
    },
    {
        fetchList: {
            // actionOptions
        },
        fetch: {
            // actionOptions
        }
    }
);

Options

Naming and indexing

Synchronising with a remote API

Reducers

Store data

Getting items from the store

To get an item from a resource, you use the getItem() function returned by resources().

It will return an empty item (instead of undefined) if one with the corresponding key does not exist in the store.

import { serializeKey, ITEM } from `redux-and-the-rest`;
import { connect } from 'react-redux';

const { reducers: usersReducers, actionCreators: { fetchList: fetchUsers }, getItem } = resources(
    {
        name: 'users',
        url: 'http://test.com/users/:id?'.
        keyBy: 'id'
    },
    {
        fetch: true
    }
);

function mapStateToProps({ users }, { params: { id } }) {
  return getItem(users, { id });
}

Automatically fetching items not in the store

To get a item or list from the store and fallback to making a request to the remote API if it's not there, use the getOrFetchItem() function returned by resources().

If the item is in the store, it will return it. However, if it is not there, it will return an empty item (instead of undefined) and trigger the action(s) to fetch the resource in the background.

You can use this function multiple times, across renders and components mounted at the same time, because duplicate actions and requests are ignored, so no unnecessary updates to the store or remote requests will be made.

In order for you to use this, a few pre-requisites must be met:

You must use the configure() function to pass redux-and-the-rest the instance of the store after you define it:

import { configure } from 'redux-and-the-rest';
import { createStore } from 'redux';

const store = createStore(reducers, {});

configure({ store });

And you must define a fetchItem action when defining your resource:

import { serializeKey, ITEM } from `redux-and-the-rest`;
import { connect } from 'react-redux';

const { reducers: usersReducers, actionCreators: { fetchList: fetchUsers }, getOrFetchItem } = resources(
    {
        name: 'users',
        url: 'http://test.com/users/:id?'.
        keyBy: 'id',
    },
    {
        fetch: true,
    }
);

getOrFetchItem() expects the current resources state (the part of the Redux store that contains your resources data) as its first argument. The second argument is the params object that will be serialized to generate the item or list's key. The third (optional) argument are options to pass to the action creator, if it's called.

function mapStateToProps({ users }, { params: { id } }) {
  // Looks for the user item in store.getState().users.items[<id>]
  return getOrFetchItem(users, { id }); 
}

The actionCreatorOptions accepts the option forceFetch, which accepts a boolean or a function that is passed the current item or list and is expected to return a boolean value. This provides a way to conditionally ignore the version of the item or list in the store and to make a fetchItem request anyway:

function mapStateToProps({ users }, { params: { id } }) {
  // Looks for the user item in store.getState().users.items[<id>]
  return getOrFetchItem(users, { id }, {
    forceFetch: ({ status: { type } }) => type === 'BOOTSTRAPPED',
  }); 
}

Automatically instantiating new items not in the store

To retrieve a new item form the store, or initialize one if it does not already exist, you can use the getOrInitializeNewItem() function.

Similar to getOrFetchItem(), it expects the current resources state (the part of the Redux store that contains your resources data) as its first argument. The second argument should be the values to initialize a new resource item with, if it does not exist in the store already.

This method returns the new item immediately, but it does not update it in the Redux store until after the current render cycle. So it's safet to use in your component's redner function.

It does not accept any parameters argument, as it relies on (and sets) the internal pointer to a new item (so this method cannot be used to initialise an existing item).

This method is particularly helpful for ensuring forms have default resource items to edit when a user first accesses them.

It's also memoized, so multiple components can use it in the same render cycle and only one update to the store is made.

function mapStateToProps({ users }, { params: { id } }) {
  return getOrInitializeNewItem(users, { username: 'DEFAULT', age: 18 }); 
}

Getting lists from the store

To get a list from a resource, you use the getList() function returned by resources().

It will return an empty list (instead of undefined) if one with the corresponding key does not exist in the store.

import { serializeKey, LIST } from `redux-and-the-rest`;
import { connect } from 'react-redux';

const { reducers: usersReducers, actionCreators: { fetchList: fetchUsers }, getList } = resources(
    {
        name: 'users',
        url: 'http://test.com/users/:id?'.
        keyBy: 'id'
    },
    {
        fetchList: true
    }
);

function mapStateToProps({ users: usersResource }, { params: { order } }) {
  return getList(usersResource, { order });
}

Automatically fetching lists that are not in the store

Similar to getOrFetchItem(), the resources() function returns a getOrFetchList() that accepts the same arguments and performs in the same manner.

To use it, you will also need to have configured redux-and-the-rest to use your store instance and you'll need to have defined an fetchList action when defining your resources().

Store data schemas

Nomenclature

It is helpful to first clarify some of the terms used in the next few sections:

• Resource: A type of thing that is available in your application and you can view or perform actions on. Examples of resources are "users", "posts" or "comments".
• List: An ordered list of items of a particular resource. This is generally what is returned from an RESTful index server endpoint. They can be ordered, scoped or filtered. Examples include "the newest users", "the most popular posts", or simply "comments" (lists don't have to have an explicit order - but one will be implied by how they are listed in a server's response).
• Item: Individual resource objects, that can belong to lists or can exist as individual entities. They have a unique primary id when using resources() or an implicit id when using resource(). For example "user with ID 123" or "post with ID 7".

Use helper methods where possible

Although the structure of each resource is standard, it's strongly recommended you use the helper methods redux-and-the-rest makes available to retrieve the data, whenever possible. Doing so will help isolate you from any changes in the underlying structure that may occur with future versions of the package.

Resource schema

All resources defined with the resources() function, return a reducers object that initialises and maintains the same data schema. This means you can easily reason about each of your resources and there is very little overhead to defining a new resource.

Top level schema

The top-level schema looks like the following, before it any data is added to your store:

{
    items: {},
    lists: {},
    selectionMap: {},
    newItemKey: null
}

We will now explore each one:

• items - A map of item keys to item objects, from all of the lists currently in the store. This means that lists with a large amount of overlap (i.e. they share many of the same items) only store one copy of each item.
• lists - A map of lists, keyed by their parameters. This allows you to have many lists of the same resource all in the one place (e.g. "newest", "most popular"), without having to re-fetch them if the user moves back and forth between them.
• selectionMap - A dictionary of item keys, representing which of the resources are currently selected in your application (if any). Because it is a map, it is easy to query if any one particular item is currently selected or not, in constant time.
• newItemKey - A value that keeps track of the key assigned to the latest item that was created of this particular resource. This is useful when you are creating a new item with a temporary id (say the current time) and you need to know the new ID the server has assigned it once it has been successfully created there, so you can move from the temporary id to the new server-assigned Id.

Item schema

A blank item has the following schema:

{
  values: {},
  status: { type: null },
  metadata: { type: null }
};

• values: This is where all of the item's attributes are stored.
• status: This is where status information is stored, separate from the item's attributes. This allows the values to remain pure - so if you are editing an item, all you need to do is send the new values back to the server, without having to worry about any irrelevant attributes being mixed in.
• metadata: This is where information about the nature of the item's set of attributes is stored. A type attribute indicates whether all of the item's attributes have been retrieved (COMPLETE by default), or whether only some of them have (e.g. PREVIEW). Other information can also be stored here, and is configurable when the resource action is defined or when the action creator is called.

Setting the metadata when defining the resource:

const { reducers, actionCreators: { fetchList: fetchUsers } } = resources({
  name: 'users',
  url: 'http://test.com/users',
  keyBy: 'id',
}, {
  fetch: {
    metadata: { type: 'PREVIEW' }
  }
});

Setting the metadata when calling the action creator:

dispatch(fetchUser(1, { metadata: { type: 'PREVIEW' }}));

List schema

A blank list has the following schema:

{
  positions: [],
  status: { type: null },
  metadata: { type: null }
};

• positions: This is an array of keys of the items that exist in the list. It stores the order of the items separate from the items themselves, so the items may be efficiently stored (without any duplicates) when we have multiple lists that may share them. It also means that we may update individual item's values, without having to alter all of the lists they are a part of.
• status: This is where status information is stored for the entire list.
• metadata: This is where information about the nature of the list is stored. A type attribute indicates whether all of the items in the list have been retrieved (COMPLETE by default), or whether only some of them have. Other information can also be stored here, and is configurable when the resource action is defined or when the action creator is called.

Setting the metadata when defining the resource:

const { reducers, actionCreators: { fetchList: fetchUsers } } = resources({
  name: 'users',
  url: 'http://test.com/users',
  keyBy: 'id',
}, {
  fetchList: {
    metadata: { type: 'PAGINATED' }
  }
});

Setting the metadata when calling the action creator:

dispatch(fetchUsers({}, { metadata: { type: 'PAGINATED', page: 1 }}));

Data lifecycle

redux-and-the-rest uses the status.type attribute of lists and items to indicate what state they are currently in. However, it's recommended to use one of the helper methods to query the status rather than accessing the attribute directly.

• isNew(item) - Whether the item is new and has yet to be created on the remote
• isEditing(item) - Whether the item has been modified since it was last synced with the server

Checking if a value is the same as the new item's temporary key:

• isNewItemKey(resourceReduxState, key) - Whether the (internally managed) newItemKey for the resource matches the key supplied

Checking if an item or list is syncing with a remote API:

There are 3 levels or groups to be aware of:

• Syncing - When any sort of request is in flight to upload or download data in the store to keep the redux store and the remote in sync. This includes fetching, creating, updating or destroying.
• Saving - When the data in the redux store is being uploaded to the remote. This includes creating or updating. Saving is a subset of syncing.

• Individual RESTful actions - fetching, creating, updating and destroying (separately)

• isFetching(itemOrList) - Whether the item or list is fetching (specifically) from the remote

• isCreating(item) - Whether the item being created (specifically) on the remote
• isUpdating(item) - Whether the item being updated (specifically) on the remote
• isDestroying(item) - Whether the item being destroyed (specifically) on the remote
• isSaving(item) - Whether the item being saved (created or updated) on the remote

• isSyncing(itemOrList) - Whether the item or list being synced (fetched, updated, created, destroyed) on the remote

To check against custom statuses, you can use the more generic:

• isStatus(itemOrList, statusList) - Whether the resource item currently has a particular status - statusList is either a single value or an array of values (a match on any of which will return true).

Checking when a sync is finished:

• isFinishedFetching(itemOrList) - Whether the request to fetch the item or list is finished
• isFinishedCreating(item) - Whether the request to create the item is finished
• isFinishedUpdating(item) - Whether the request to update the item is finished
• isFinishedSaving(item) - Whether the request to save the item is finished
• isFinishedSyncing(itemOrList) - Whether the request to sync the item or list is finished
• isNotAvailableLocally(itemOrList) - Whether a list or item is undefined, null or an empty schema, indicating it was not in the store when it was retrieved.

To check against custom statuses, you can use the more generic:

• isFinished(itemOrList, statusList) - Whether a resource item or list has exited the provided status (or any value in the status list) and is now in a success or error state

Checking the result of the latest sync with the remote API:

• isSucces(itemOrList) - Whether the item or list was successful in its last sync
• isError(itemOrList) - Whether the item or list was failed in its last sync
• getHttpStatusCode(itemOrList) - The HTTP status code of the last request related to the resource item or list as a number

import React from 'react';
import { isFinishedSyncing, isSuccess } from 'redux-and-the-rest';

class MyComponent extends Component {
    render() {
        const { item } = this.props;

        if (isFinishedSyncing(item)) { 
            if (isSuccess(item)) {
              // item is loaded and ready to display
            } else {
              // display error message
            }
        } else {
           // display preloader
        }
    }
}

If for whatever reason the above helper methods are not suitable for your needs, the raw status type are as follows:

Client statuses

These statuses are useful for creating behaviour specific to new or changed items, such as displaying warning messages if the user attempts to navigate away without saving:

• NEW: When a new item is being created on the client, but has not yet been sent to the server.
• EDITING: When an existing item is being updated but has not yet been saved to the server.

Pending statuses

Checking for these statuses is generally useful for displaying loaders or progress indicators:

• FETCHING: When an item or list is being fetched from the server but it has not yet arrived.
• CREATING: When the request to create a new item has been sent to the server, but the response has not yet arrived.
• UPDATING: When the request to save the changes to an existing item have been sent to the server, but the response has not yet arrived.
• DESTROYING: When the request to destroy an existing item has been sent to the server, but the response has not yet arrived.
• PROGRESS: When progress updates are enabled, this status occurs while an upload or download request is taking place. You can check status.progressUp (for the upload request progress) and status.progressDown (for the download response progress).

Response statuses

Checking for these statuses is useful for displaying success or error messages:

• SUCCESS: When the response to the a request to fetch list or an item has arrived and it was a success. You can now use the contents of the list or item.
• ERROR: When the response to the a request to fetch list or an item has arrived and it was an error. You should now check the status.errors attribute for details.
• DESTROY_ERROR: When the response to the request to destroy an existing item has arrived, and it's an error. You should now check the status.errors attribute for details.

Setting initial state

redux-and-the-rest provides a Builder for each resource that can be used to define the initial resource state in a minimal fashion. This builder provides a chainable interface for specifying values and a build() function for returning the initial state, correctly nested and formatted to work with the resource's reducers.

resources() returns a buildInitialState() helper function that returns an InitialResourceStateBuilder instance. This instance lets you set values that will propagate to all of the resource's lists and items.

const { buildInitialState } = resources({
    name: 'users',
    url: 'http://test.com/users/:id',
}, ['fetch']);

const stateBuilder = buildInitialState([ { id: 1, username: 'John' }]);

createStore(reducers, { users: stateBuilder.build() });

It provides a addList() function for specifying a list, which returns a builder scoped to that list, so you can further specify state and metadata values o