Have ideas to improve npm?Join in the discussion! »

    fetch-hoc

    0.5.1 • Public • Published

    fetch-hoc

    Build Status Coverage Status npm version

    A React higher order component for fetching data from a server and passing the result as props.

    Using a HoC for fetching data is easier to understand and master than redux, while at the same time being more consise than writing utilities and extending components.

    The resource can be either a string or a function. If the resouce is a function, then the HoC will automatically re-fetch the resouce when the resource URL changes.

    This library is super tiny, measuring just over 1kB gzipped, and has no dependencies!

    Installation

    yarn add fetch-hoc
    # or 
    npm i -S fetch-hoc

    If you don't yet use npm or a bundler like webpack, you can get a UMD bundle from unpkg. Simply add one of the following links into your app, and the library will be accessible as FetchHOC on window. Remember to replace [VERSION] with the version you want.

    <script src="https://unpkg.com/fetch-hoc@[VERSION]/dist/fetch-hoc.min.js"></script>

    Usage

    Now it's my job to tell you why this library is cool.

    Simply wrap your component in the result of the fetch function to get started. Using this method enables most of your components to be written as functional stateless components, which is great for legibility and testabiliy.

    fetch('/some/static/resource')(Component)
    // Or
    fetch(props => `/some/resource/${props.someProp}`)(Component)

    Here is a more complete example:

    const FooComponent = props => {
      if (props.error) {
        return <div className="error">{`An error occured! ${props.error}`}</div>;
      }
      if (props.loading) {
        return <div className="loading">Loading...</div>;
      }
     
      return (
        <div>
          {props.data.map(row => <div>{row.text}</div>)}
        </div>
      );
    }
     
    // This feeds the props used in render
    fetch('http://foo.com/bar')(FooComponent);

    If you need more flexibility in your component, you can also use a function to reduce the URL from the component's props. These props can be redux props if you also have used connect on the component.

    // With props from parent
    fetch(props => `/user/${props.user}/cart`)(FooComponent);
     
    // With redux
    compose(
      mapStateToProps(state => ({ user: state.user })),
      fetch(props => `/user/${props.user}/cart`),
    )(FooComponent);

    Example: Composition is king

    Use composition to compose behaviors upon the props this HoC provides! For example, to add an easily reusable loading icon and error message:

    // withLoadingAnimation.js
    export default Component => props => (
      props.loading
        ? <YourLoadingComponent />
        : <Component {...props} />
    );
    // withErrorMessage.js
    export default message => Component => props => (
      props.error
        ? <div className="error">{message}</div>
        : <Component {...props} />
    );
    // FooComponent.js
    import withLoadingAnimation from './withLoadingAnimation';
    import withErrorMessage from './withErrorMessage';
     
    const FooComponent = ({ data }) => (
      <div>
        <h1>I will only render on a successfully completed fetch!</h1>
        <pre>{data.toString()}</pre>
      </div>
    );
     
    export default compose(
      fetch('/foo'),
      withLoadingAnimation,
      withErrorMessage('Failed to fetch that thing'),
    )(FooComponent);

    Example: Normalizing data

    What about if you need a subset of the data, and the entire dataset is not convenient to work with? Simple, add a HoC for that:

    const normalize = func => Component => ({ data, ..rest }) => (
      <Component data={func(data)} {...rest} />
    );
     
    export default compose(
      fetch('/foo'),
      normalize(data => data.rows.filter(row => row.enabled))
    );

    API

    // @flow
     
    type Options = {
      /* The same as the Fetch API options, see
       * https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch
       */
    };
     
    fetch(url: string|Function, options: Options|(props: {}) => Options)(component: React.Component)

    The HoC will inject the following props:

    Prop Type Description
    data Object The data returned from the server
    error Error Any error that occured while fetching the data
    loading boolean Whether the request is currently in flight
    success boolean Whether the request was successfully fetched
    response Response The full response with headers. Cloned and can be read again
    refetchData Function Forces the component to refetch the data without changing the url

    Install

    npm i fetch-hoc

    DownloadsWeekly Downloads

    2,398

    Version

    0.5.1

    License

    MIT

    Unpacked Size

    56.8 kB

    Total Files

    12

    Last publish

    Collaborators

    • avatar