A declarative approach to fetching data via a React higher order component
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src improve props structure, improve readme Nov 3, 2017
tests update the build to output minified umd module plus babelified module Nov 3, 2017
.babelrc improve docs, api for component, etc. Nov 2, 2017
.gitignore update the build to output minified umd module plus babelified module Nov 3, 2017
.travis.yml Update .travis.yml Nov 2, 2017
LICENSE
README.md
package-lock.json Release v0.9.0. Nov 3, 2017
package.json Release v0.9.0. Nov 3, 2017
webpack.config.js

README.md

Build Status npm version 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('/')}/>
);