React Refetch

A simple, declarative, and composable way to fetch data for React components.

Installation

Requires React 0.14 or later.

npm install --save react-refetch

This assumes that you’re using npm package manager with a module bundler like Webpack or Browserify to consume CommonJS modules.

The following ES6 functions are required:

• Object.assign

• Promise

• fetch

• Array.prototype.find

Check the compatibility tables (

Object.assign

Promise

fetch

Array.prototype.find

Introduction

See Introducing React Refetch on the Heroku Engineering Blog for background and a quick introduction to this project.

Motivation

This project was inspired by (and forked from) React Redux. Redux/Flux is a wonderful library/pattern for applications that need to maintain complicated client-side state; however, if your application is mostly fetching and rendering read-only data from a server, it can over-complicate the architecture to fetch data in actions, reduce it into the store, only to select it back out again. The other approach of fetching data inside the component and dumping it in local state is also messy and makes components smarter and more mutable than they need to be. This module allows you to wrap a component in a

connect()

Example

If you have a component called

Profile

userId

connect()

userId

userFetch

likesFetch

import React, { Component } from 'react'
import { connect, PromiseState } from 'react-refetch'

class Profile extends Component {
  render() {
    // see below
  }
}
export default connect(props => ({
  userFetch: /users/${props.userId},
  likesFetch: /users/${props.userId}/likes
}))(Profile)

When the component mounts, the requests will be calculated, fetched, and the result will be passed into the component as the props specified. The result is represented as a

PromiseState

Promise

pending

fulfilled

rejected

render() {
  const { userFetch, likesFetch } = this.props

  if (userFetch.pending) {
    return 
  } else if (userFetch.rejected) {
    return 
  } else if (userFetch.fulfilled) {
    return 
  }
  // similar for likesFetch
}

See the composing responses to see how to handle

userFetch

likesFetch

PromiseStateContainer

PromiseState

Refetching

When new props are received, the requests are re-calculated, and if they changed, the data is refetched and passed into the component as new

PromiseState

By default, the requests are compared using their URL, headers, and body; however, if you want to use a custom value for the comparison, set the

comparison

userStatsFetch

connect(props => ({
  usersFetch:  `/users?status=${props.status}&page=${props.page}`,
  userStatsFetch: { url: `/users/stats`, comparison: `${props.status}:${props.page}` }
}))(UsersList)

In this example,

usersFetch

props.status

props.page

userStatsFetch

comparison: ${props.status}:${props.page}

usersFetch

If you always want data to be refetched when any new props are received, set the

force: true

comparison

connect(props => ({
  usersFetch: `/users?status=${props.status}&page=${props.page}`,
  userStatsFetch: { url: `/users/stats`, force: true }
}))(UsersList)

Setting

force: true

comparison

Automatic Refreshing

If the

refreshInterval

likesFetch

likeFetch

connect(props => ({
  userFetch:`/users/${props.userId}`,
  likesFetch: { url: `/users/${props.userId}/likes`, refreshInterval: 60000 }
}))(Profile)

When refreshing, the

PromiseState

fulfilled

refreshing

pending

value

refreshing

value

PromiseState

rejected

Fetch Functions

Instead of mapping the props directly to a URL string or request object, you can also map the props to a function that returns a URL string or request object. When the component receives props, instead of the data being fetched immediately and injected as a

PromiseState

Lazy Loading

Here is a simple example of lazy loading the

likesFetch

connect(props => ({
  userFetch: `/users/${props.userId}`,
  lazyFetchLikes: max => ({
    likesFetch: `/users/${props.userId}/likes?max=${max}`
  })
}))(Profile)

In this example,

userFetch

lazyFetchLikes

likesFetch

lazyFetchLikes

this.props.lazyFetchLikes(10)

When this function is called, the request is calculated using both the bound props and any passed in arguments, and the

likesFetch

PromiseState

Posting Data

Functions can also be used for post data to the server in response to a user action. For example:

connect(props => ({
  postLike: subject => ({
    postLikeResponse: {
      url: `/users/${props.userId}/likes`,
      method: 'POST',
      body: JSON.stringify({ subject })
    }
  })
}))(Profile)

The

postLike

 this.props.postLike(someSubject)}>Like!

When the user clicks the button,

someSubject

postLikeResponse

PromiseState

Manually Refreshing Data

Functions can also be used to manually refresh data by overwriting an existing

PromiseState

connect(props => {
 const url = `/users/${props.userId}`

 return {
   userFetch: url,
   refreshUser: () => ({
     userFetch: {
       url,
       force: true,
       refreshing: true
     }
   })
 }
})(Profile)

The

userFetch

refreshUser

this.props.refreshUser()

userFetch

force: true

userFetch

PromiseState

Note, the example above sets

force: true

refreshing: true

refreshUser()

force: true

url

method

headers

body

userFetch

this.props.refreshUser()

force: true

this.props.refreshUser()

refreshing: true

PromiseState

Posting + Refreshing Data

The two examples above can be combined to post data to the server and refresh an existing

PromiseState

PATCH /users/:user_id

userFetch

connect(props => ({
  userFetch: `/users/${props.userId}`,
  updateUser: (firstName, lastName) => ({
    userFetch: {
      url: `/users/${props.userId}`
      method: 'PATCH'
      body: JSON.stringify({ firstName, lastName })
     }
   })
}))(Profile)

Composing Responses

If a component needs data from more than one URL, the

PromiseState

PromiseState.all()

pending

PromiseState

render() {
  const { userFetch, likesFetch } = this.props

  // compose multiple PromiseStates together to wait on them as a whole
  const allFetches = PromiseState.all([userFetch, likesFetch])
  // render the different promise states
  if (allFetches.pending) {
    return 
  } else if (allFetches.rejected) {
    return 
  } else if (allFetches.fulfilled) {
    // decompose the PromiseState back into individual
    const [user, likes] = allFetches.value
    return (
      

          
          
      


    )
  }
}

Similarly,

PromiseState.race()

PromiseState

Promise

PromiseStates

then()

catch()

likesFetch

PromiseState.all([userFetch, likesFetch.catch(reason => [])])

Chaining Requests

Inside of

connect()

then()

catch()

andThen()

andCatch()

PromiseState

PromiseState

then()

/foos/${name}

foo.id

/bar-for-foos-by-id/${foo.id}

barFetch

foo

connect(({ name }) => ({
  barFetch: {
    url: `/foos/${name}`,
    then: foo => `/bar-for-foos-by-id/${foo.id}`
  }
}))

andThen()

connect(({ name }) => ({
  fooFetch: {
    url: `/foos/${name}`,
    andThen: foo => ({
      barFetch: `/bar-for-foos-by-id/${foo.id}`
    })
  }
}))

This is also helpful for cases where a fetch function is changing data that is in some other fetch that is a collection. For example, if you have a list of

foo

foo

 connect(({ name }) => ({
    foosFetch: '/foos',
    createFoo: name => ({
      fooCreation: {
        method: 'POST',
        url: '/foos',
        andThen: () => ({
          foosFetch: {
            url: '/foos',
            refreshing: true
          }
        })
      }
    })
  }))

catch

andCatch

Identity Requests: Static Data & Transforming Responses

To support static data and response transformations, there is a special kind of request called an "identity request" that has a

value

url

value

PromiseState

connect(props => ({
  usersFetch: {
    value: [
      {
        id: 1,
        name: 'Jane Doe',
        verified: true
      },
      {
        id: 2,
        name: 'John Doe',
        verified: false
      }
    ]
  }
}))(Users)

In this case, the

usersFetch

PromiseState

then

connect(props => ({
  usersFetch: {
    url: `/users`,
    then: (users) => ({
      value: users.filter(u => u.verified)
    })
  }
}))(Users)

Note, this form of transformation is similar to what is possible on the

PromiseState

this.props.usersFetch.then(users => users.filter(u => u.verified))

usersFetch

Identity requests can also be provided a

Promise

Function

value

Promise

PromiseState

pending

Promise

value

Function

Function

comparison

connect(props => ({
  userFetch: {
    comparison: props.userId,
    value: () => SomeExternalAPI.getUser(`/users/${props.userId}`)
  }
}))(Users)

Accessing Headers & Metadata

Both request and response headers and other metadata are accessible. Custom request headers can be set on the request as an object:

connect(props => ({
  userFetch: {
    url: `/users/${props.userId}`,
    headers: {
      FOO: 'foo',
      BAR: 'bar'
    }
  }
}))(Profile)

The raw

Request

Response

meta

PromiseState

userFetch.meta.response.headers.get('FOO')

Do not attempt to read bodies directly from

meta.request

meta.response

Setting defaults and hooking into internal processing

It is possible to modify the various defaults used by React Refetch, as well as substitute in custom implementations of internal functions. A simple use case would be to avoid repeating the same option for every fetch block:

import { connect } from 'react-refetch'
const refetch = connect.defaults({
  credentials: 'include'
})

refetch(props => ({
  userFetch: /users/${props.userId}
}))(Profile)

A more advanced use case would be to replace the

buildRequest

Request

// api-connector.js
import { connect } from 'react-refetch'
import urlJoin from 'url-join'
import { getPrivateToken } from './api-tokens'

const baseUrl = 'https://api.example.com/'
export default connect.defaults({
  buildRequest: function (mapping) {
    const options = {
      method: mapping.method,
      cache: 'force-cache',
      referrer: 'https://example.com',
      headers: mapping.headers,
      credentials: mapping.credentials,
      redirect: mapping.redirect,
      mode: mapping.mode,
      body: mapping.body
    }
if (mapping.url.match(/private/)) {
  options.headers['X-Api-Token'] = getPrivateToken()
}

if (mapping.url.match(/listOfServers.json$/)) {
  options.integrity = 'sha256-BpfBw7ivV8q2jLiT13fxDYAe2tJllusRSZ273h2nFSE='
}

return new Request(urlJoin(baseUrl, mapping.url), options)
  }
})
// ProfileComponent.js
import connect from './api-connector'
connect(props => ({
  userFetch: /users/${props.userId},
  serversFetch: /listOfServers.json
}))(Profile)

You can also replace the

handleResponse

Response

// api-connector.js
import { connect } from 'react-refetch'
import { parse } from 'csv'

const csvConnector = connect.defaults({
  handleResponse: function (response) {
    if (response.headers.get('content-length') === '0' || response.status === 204) {
      return
    }
const csv = response.text()

if (response.status >= 200 && response.status < 300) {
  return csv.then(text => new Promise((resolve, reject) => {
    parse(text, (err, data) => {
      if (err) { reject(err) }
      resolve(data)
    })
  }))
} else {
  return csv.then(cause => Promise.reject(new Error(cause)))
}
  }
})
csvConnector(props => ({
  userFetch: /users/${props.userId}.csv
}))(Profile)

On changing the

fetch

and

Request

implementations

Through this same API it is possible to change the internal

fetch

Request

buildRequest

handleResponse

For example, here's a simplistic implementation of a "caching fetch," which will cache the result of successful requests for a minute, regardless of headers:

import { connect } from 'react-refetch'

const cache = new Map()
function cachingFetch(input, init) {
  const req = new Request(input, init)
  const now = new Date().getTime()
  const oneMinuteAgo = now - 60000
  const cached = cache.get(req.url)
  if (cached && cached.time < oneMinuteAgo) {
    return new Promise(resolve => resolve(cached.response.clone()))
  }
  return fetch(req).then(response => {
    cache.set(req.url, {
      time: now,
      response: response.clone()
    })
return response
  })
}
connect.defaults({ fetch: cachingFetch })(props => ({
  userFetch: /users/${props.userId}
}))(Profile)

When using this feature, make sure to read the

fetch

body

Response

fetch

Response

.clone()

This is an advanced feature. Use existing declarative functionality wherever possible. Customise

buildRequest

handleResponse

fetch

Request

Unit Testing Connected Components

For unit testing components connected, a non-default export of the unconnected component can be exposed to allow unit tests to inject their own

PromiseState

PromiseState

PromiseState

The recommended naming convention for the unconnected component is to prepend an underscore to the component name. For example, if there is a component called

Profile

_Profile

connect

class Profile extends React.Component {
  static propTypes = {
    userFetch: PropTypes.instanceOf(PromiseState).isRequired,
  }

  render() {
    const { userFetch } = this.props
if (userFetch.pending) {
  return <loadinganimation></loadinganimation>
} else if (userFetch.rejected) {
  return <errorbox error="{userFetch.reason}/">
} else if (userFetch.fulfilled) {
  return <user user="{userFetch.value}/">
}
  }
}
export { Profile as _Profile }
export default connect(props => ({
  userFetch: /users/${props.userId}
}))(Profile)

Now, unit tests can use the static methods on

PromiseState

PromiseState

_Profile

PromiseState

LoadingAnimation

const c = shallow(
  <_profile userfetch="{PromiseState.create()}">
)

expect(wrapper.find(LoadingAnimation)).to.have.length(1)

Similarly, the rejected and fulfilled cases can be tested:

const expectedError = new Error('boom')

const c = shallow(
  <_profile userfetch="{PromiseState.reject(expectedError)}"></_profile>
)
expect(c.find(ErrorBox).first().prop().error).toEqual(expectedError)

const user = new User()

const c = shallow(
  <_profile userfetch="{PromiseState.resolve(user)}"></_profile>
)
expect(wrapper.find(User)).to.have.length(1)

Complete Example

This is a complex example demonstrating various feature at once:

import React, { Component, PropTypes } from 'react'
import { connect, PromiseState } from 'react-refetch'

class Profile extends React.Component {
  static propTypes = {
    params: PropTypes.shape({
      userId: PropTypes.string.isRequired,
    }).isRequired,
    userFetch: PropTypes.instanceOf(PromiseState).isRequired
    likesFetch: PropTypes.instanceOf(PromiseState).isRequired
    updateStatus: PropTypes.func.isRequired
    updateStatusResponse: PropTypes.instanceOf(PromiseState) // will not be set until after updateStatus() is called
  }
  render() {
    const { userFetch, likesFetch } = this.props
// compose multiple PromiseStates together to wait on them as a whole
const allFetches = PromiseState.all([userFetch, likesFetch])

// render the different promise states
if (allFetches.pending) {
  return <loadinganimation></loadinganimation>
} else if (allFetches.rejected) {
  return <error error="{allFetches.reason}/">
} else if (allFetches.fulfilled) {
  // decompose the PromiseState back into individual
  const [user, likes] = allFetches.value
  return (
    <div>
      <user data="{user}/">
      <likes data="{likes}/">
    </likes></user>

      )
    }

// call `updateStatus()` on button click
<button onclick="{()"> { this.props.updateStatus("Hello World")} }&gt;Update Status</button>

if (updateStatusResponse) {
  // render the different promise states, but will be `null` until `updateStatus()` is called
}
  }
}
// declare the requests for fetching the data, assign them props, and connect to the component.
export default connect(props => {
  return {
    // simple GET from a URL injected as userFetch prop
    // if userId changes, data will be refetched
    userFetch: /users/${props.params.userId},
// similar to `userFetch`, but using object syntax
// specifies a refresh interval to poll for new data
likesFetch: {
  url: `/users/${props.userId}/likes`,
  refreshInterval: 60000
},

// declaring a request as a function
// not immediately fetched, but rather bound to the `userId` prop and injected as `updateStatus` prop
// when `updateStatus` is called, the `status` is posted and the response is injected as `updateStatusResponse` prop.
updateStatus: status =&gt; ({
  updateStatusResponse: {
    url: `/users/${props.params.userId}/status`,
    method: 'POST',
    body: status
  }
})
  }
})(Profile)

TypeScript

If you are using React Refetch in a project that is using TypeScript, this library ships with type definitions.

Below is example connected component in TypeScript. Note how there is both an

OuterProps

InnerProps

OuterProp

OuterProps

userId: string

InnerProps

PromiseState

connect()

InnerProps

OuterProps

InnerProps extends OuterProps

extends React.Component

userId: string

userFetch: PromiseState

connect

OuterProps

React.Component

userId: string

interface OuterProps {
    userId: string
}

interface InnerProps extends OuterProps {
    userFetch: PromiseState
}
class UserWidget extends React.Component {
  render() {
    return (
      

        
{ this.props.userId }
        
{ this.props.userFetch.fulfilled && this.props.userFetch.value.name }
      
    )
  }
}

export default connect((props) => ({
  userFetch: /users/${props.userId}
}))(UserWidget)

API Documentation

• connect([mapPropsToRequestsToProps])

• connect.defaults([newDefaults])

• PromiseState(iterable)

Support

This software is provided "as is", without warranty or support of any kind, express or implied. See license for details.

License

MIT