react-sync

A declarative approach to fetching API data using HTML5 Fetch

Purpose

react-sync provides a single higher order component used for fetching data from your APIs

Rendering the data is your responsibility, but refreshing the data from the API is as simple as changing the parameters of your request. Let the component manage the state of fetching the data.

ReactSync Props

Name	Description	Type	Required	Default
url	The url to fetch without any query parameters	string	Yes
headers	Object containing all the headers to pass to the request	object	No	null
params	Object containing all the query parameters to pass to the request	object	No	null
toQueryString	Function used to convert the query parameters prop to a query string	function	No	./toQueryString.js
toData	Function that takes a fetch response object and returns a promise that resolves to the data in the response	function	No	returns response JSON by default
children	Function that takes an object {promise, data, error} and returns a node to be rendered	function	Yes

Source: props.jsx

Child Props

The function passed to the children prop receives the fetch state

Name	Description	Type
promise	The pending promise if any requests are outstanding	instanceof Promise
data	Data that has been fetched from the API	result of toData
error	Any fetch errors that may have occurred	instanceof Error

Install

npm install --save react-sync

Alternately this project builds to a UMD module named ReactSync, so you can include a unpkg script tag in your page

Look for window.ReactSync when importing the UMD module via a script tag

Usage

See the demo source for example usage with filtering

import React from 'react';
import ReactSync from 'react-sync';
 
const StarGazers = ({ owner, repo, githubToken }) => (
  <ReactSync 
    url={`https://api.github.com/repos/${owner}/${repo}/stargazers`} 
    headers={{Authorization: `token ${githubToken}`}}>
    {
      ({ promise, data, error }) => (
        <span>
          {promise !== null ? 'Loading...' : data}      
        </span>
      )
    }
  </ReactSync>
);

Patterns

Composition is king when using this component.

For example, want to automatically refetch every minute? Create a component that wraps ReactSync and updates a timestamp query parameter every minute.

import React, { Component } from 'react';
import PropTypes from 'prop-types';
import Sync from 'react-sync';
 
const now = () => (new Date()).getTime();
 
export default class RefreshSync extends Component {
  static propTypes = {
    refreshEvery: PropTypes.number
  };
 
  _timer = null;
  state = {
    _ts: now()
  };
 
  triggerNextRefresh = after => {
    clearTimeout(this._timer);
    this._timer = setTimeout(this.refresh, after);
  };
 
  refresh = () => {
    this.setState({ _ts: now() });
    this.triggerNextRefresh(this.props.refreshEvery);
  };
 
  componentDidMount() {
    this.triggerNextRefresh(this.props.refreshEvery);
  }
 
  componentWillReceiveProps({ refreshEvery }) {
    if (refreshEvery !== this.props.refreshEvery) {
      this.triggerNextRefresh(refreshEvery);
    }
  }
 
  render() {
    const { params, ...rest } = this.props,
      { _ts } = this.state;
 
    return <Sync {...rest} params={{ ...params, _ts }}/>;
  }
}

What about attaching a token from the context to all requests?

import React, { Component } from 'react';
import PropTypes from 'prop-types';
import Sync from 'react-sync';
 
export default class AuthenticatedSync extends Component {
  static contextTypes = {
    token: PropTypes.string
  };
 
  render() {
    const { headers, ...rest } = this.props,
      { token } = this.context;
 
    return (
      <Sync
        {...rest}
        headers={{
          ...headers,
          Authorization: token ? `Bearer ${token}` : null
        }}
      />
    );
  }
}

How about just defaulting a base URL?

import React from 'react';
import Sync from 'react-sync';
 
export const MyApiSync = ({ path, ...rest }) => (
  <Sync {...rest} url={[ 'https://my-api.com', path ].join('/')}/>
);