redux-supermodel

redux-supermodel

Streamline the effort it takes for you to communicate between your Redux Store and a REST-like API. This is a package of action creator functions and reducers built with axios and redux-promise-middleware that handle the resource state management for you... all you need is a URL!

Check out the demo

API Reference

Creating the Client

Clients encapsulate the API you are consuming. You can create a new client by providing the base URL for the API.

import { createClient } from 'redux-supermodel'

const client = createClient('https://example.com/api/v1')

Creating Resources

Within your client, you can start defining resources. Each Resource represents an endpoint that you can interact with.

// The full URL will be https://example.com/api/v1/blogs
const blogs = client('blogs')

// https://example.com/api/v1/comments
const comments = client('comments')

Attaching your Resource's props to your Component

Start with your resource definition, let's pretend http://example.com/api/posts/latest will return a JSON object with properties title and body.

// resources.js

import { createClient } from 'redux-supermodel'

const client = createClient('http://example.com/api')

// GET http://example.com/api/posts/latest
//
// { title: 'My latest blog post', body: 'Hello, world!' }
export const post = client('post', { url: 'posts/latest' }) 

The easiest way to use redux-supermodel is with the bindResource higher-order component which will automatically fetch the resource when the component mounts, reset it when the component unmounts, and binds the resource's props and action creators to the component's props.

// MyComponent.js

import React from 'react'
import { bindResource } from 'redux-supermodel'
import { post } from './resources'

export function MyComponent (props) {
  const { ready, error, title, body, fetchPost } = props
  if (!ready) return <div className="loading">Loading...</div> 
  if (error) return <div className="error">{error.message}</div>
  
  return (
    <div>
      <h1>{title}</h1>
      <div className="body">
        {body}
      </div>
      <button type="button" onClick={fetchPost}>Refresh</button>
    </div>
  )
}

export function mapProps (state) {
  const { ready, error, payload } = post(state)
  const { data: { title, body } = {} } = payload
  return { ready, error, title, body }
}

export default bindResource({post}, {mapProps})(MyComponent)

The payload can be a massive object containing lots of information about the HTTP request and response, most of which you aren't going to need when you're rendering your component, so I suggest using the mapProps call to simplify the payload to just the stuff you're going to need. Try to avoid using payload directly. Check out this blog post for further reading.

For details on mapProps, read the react-redux connect() documentation.

For the full list of options, see bindResource.

Installation

npm install --save redux-supermodel redux-promise-middleware

You will need to add the redux-promise-middleware middleware and the redux-supermodel reducer to your Redux Store.

// store.js

import { createStore, applyMiddleware, compose, combineReducers } from 'redux'
import promiseMiddleware from 'redux-promise-middleware'
import { reducer as resource } from 'redux-supermodel'

const rootReducer = combineReducers({ resource })
export default compose(applyMiddleware(promiseMiddleware()))(createStore)(rootReducer)

API Reference