Redux API Resource creator (redux-resx)

Yet another Redux action creators, a reducer and middleware for resource-based APIs.

resx = shortening for resource

Based on the async actions pattern in redux (https://redux.js.org/docs/advanced/AsyncActions.html)

Installation

1npm install --save redux-resx

Usage

Resource Definition

A resource is a grouping of redux reducers, actions and selectors for your api endpoint. You define a unique name for it and the url. You can also add your own reducer to augment the state at the "mountpoint" on the state store.

1// somewhere like src/resources/user.js
2import createResource from 'redux-resx';
3
4export default createResource({
5  // Required:
6  name: '@resx/USER', // Unique namespace for actions and reducer
7  url: '/users',
8
9  // Optional (defaults shown)
10  // This function should return the root object of where you mount your state
11  baseSelector: s => s.resources,
12  // Use this to add extra reducers which receive the state after the built-in reducer
13  // has done it's thing - this can perhaps be used in conjunction with custom middleware
14  // It only receives resource actions, not every action
15  reducer: (state, _action) => state,
16});
17
18
19// src/resources/index.js
20export default as user from './user';

Reducer

1import { combineReducers } from 'redux';
2
3import * as resources from '../resources';
4import { reducer as resourceReducer } from 'redux-resx';
5
6export default combineReducers({
7  resources: combineReducers(resourceReducer(resources)),
8});

Lets break this down a bit:

1export default combineReducers({
2  // 'resources' can be anywhere, you just need to specify a base selector that selects it in
3  // create resource
4  resources: combineReducers(
5    // resourceReducer is really just transforms the object to something that combineReducers can use
6    // Give it { users: [result of createResource] } and it will return { users: reducerFn } - simple
7    resourceReducer(resources)
8  ),
9});
10
11
12// Another way you could do this
13
14import userResource from '../resources/users';
15...
16resources: combineReducers({
17  myUser: userResource.reducer,
18  //etc
19})

Component

Please see the NB comments

1import React, { PropTypes } from 'react';
2import { connect } from 'react-redux';
3
4import { user as userResx } from '../resources';
5
6// NB: New in 1.0.0+
7// *************************************************************************
8// You need to provide a namespace for your 'instance' (any string) that you want to use.
9// This is so you can call a resource in multiple components without interferance.
10const myUserResx = userResx.create('@HOME');
11// If you omit the namespace, a default one will be used (essentially the same behaviour prior to 1.0.0)
12// const myUserResx = userResx.create();
13// Using the default method, returns a singleton instance for reuse
14// const myUserResx = userResx.default();
15
16const Home = React.createClass({
17//....
18
19  componentWillMount() {
20    const { getUser, findUsers, resetUsers } = this.props;
21    // XXX: Optional, you'll get old results before new ones are loaded if you don't do this.
22    // New in 1.0.0: If your resource is only used in this component and you destroy on unmount,
23    // you definitely/obviously won't need to use reset.
24    resetUsers();
25    findUsers({ status: 'active' }); // params of request
26    getUser(123).then(...); // id=123 NB: only if middleware returns a promise
27  },
28
29  // NB: New in 1.0.0 - will remove the namespaced data entirely
30  componentWillUnmount() {
31    this.props.destroyResx();
32  }
33
34  render() {
35    const { users, user } = this.props;
36
37    return (
38      <div>
39        {users ? JSON.stringify(users) : null}
40        {user ? JSON.stringify(user) : null}
41      </div>
42    );
43  },
44});
45
46function mapStateToProps(state) {
47  // Select the resource state
48  const {
49    hasLoaded, // true when find has been loaded before
50    isBusy, // true when any of the following are true
51    isFinding,
52    isGetting,
53    isCreating,
54    isUpdating,
55    isPatching,
56    isRemoving,
57
58    // Result for find - always an array (initial value: [])
59    items,
60
61    // Last result for create, get, update, patch, remove
62    entity, // (initial value: undefined)
63  } = userResx.selector(state);
64
65  return {
66    users: items,
67    user: entity,
68    isBusy,
69  };
70}
71
72const { find: findUsers, get: getUser, reset: resetUsers, destroy: destroyResx } = myUserResx.actions;
73
74export default connect(mapStateToProps, {
75  findUsers,
76  getUser,
77  resetUsers,
78  destroyResx,
79})(Home);

Selector

Each resx has a selector function which can be used to select the resource from the state store.

A resx has the following structure:

1// Initial structure of resx
2{
3  hasLoaded: false, // Has the resource loaded before (has find returned a result and items populated)
4  isBusy: false, // true if any operation is running on this resx, otherwise false
5  isFinding: false, // true if find call is busy, otherwise false
6  isGetting: false, // true if get call is busy, otherwise false
7  isCreating: false, // true if create call is busy, otherwise false
8  isUpdating: false, // true if update call is busy, otherwise false
9  isPatching: false, // true if patch call is busy, otherwise false
10  isRemoving: false, // true if remove call is busy, otherwise false
11  items: [], // The result of a find call
12  entity: undefined, // The result of the last get, create, patch, update and remove call
13  lastError: undefined, // The result of the call if it was an error
14}

Middlewares

The middleware's job is to "handle" the actions coming in from resource action creators. This is where the side-effects are. A middleware is included which calls endpoints like you would expect, but you can implement your own or use e.g. sagas.

Builtin middleware

Add middleware to store in the normal way

1// NB: Only bundled if you are using it
2import middleware from 'redux-resx/middleware';
3import fetch from 'isomorphic-fetch';
4//... other imports
5
6const resxMiddleware = middleware({
7  baseUrl: '/api',
8  provider: fetch, // could write adapter to convert fetch params to e.g. request/jquery
9});
10
11export default function createApplicationStore() {
12  return createStore(
13    reducers,
14    compose(applyMiddleware(resxMiddleware))
15  );
16}

Other middleware

• redux-resx-feathers-middleware - uses feathers-client to make requests
• redux-resx-saga - sagas to handle resource actions (TODO)

TODO

• Example

Future Ideas

• Middleware (separate package) that implements a decoupled cache using state