README.md

Important Notice

⚠ Project Discontinuation
We regret to inform you that this project is no longer maintained. For an alternative solution, consider using React Query

---

React bindings for @data-provider

Set of hooks and HOCs for binding @data-provider to React components

Installation

npm i --save @data-provider/react

Available hooks

• useDataLoadingError
• useDataLoadedError
• useData
• useLoading
• useLoaded
• useError
• usePolling

Available HOCs

• withDataLoadingError
• withDataLoadedError
• withData
• withLoading
• withLoaded
• withError
• withPolling
• withDataLoadingErrorComponents
• withDataLoadedErrorComponents

Hooks

useDataLoadingError(provider, [equalityFn])

Triggers the provider read method and gives you the data, loading and error properties from the state of the provider or selector. When the provider cache is cleaned, it automatically triggers read again.

Use this hook only when you need all mentioned properties, because your component will be re-rendered any time one of them changes. If you only need one or two properties, better use one of the hooks described bellow.

Arguments

• provider (Object): Data Provider provider or selector instance.
• equalityFn (Function): Function used to determine if returned value is different from the previous one, which will produce a re-render of the component. Read React-redux hooks docs for further info.

Returns

• (Array) - Array containing data, loading and error properties, in that order.

Example

import { useDataLoadingError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const [data, loading, error] = useDataLoadingError(books);
  // Do your stuff here
};

useDataLoadedError(provider, [equalityFn])

This hook has the same behavior and interface than the described for the useDataLoadingError one, but it returns the data, loaded and error properties from the state of the provider or selector.

Use this hook only when you don't want to rerender a Component each time the provider is loading. It will return loaded as true once the provider has loaded for the first time, and it will not change again. This is useful to avoid rerenders in scenarios having "pollings", for example, as it will avoid to render a "loading" each time the data is refreshed.

Take into account that the loaded property will not be set as true until a success read has finished, so the error may have a value, even when loaded is false.

Returns

• (Array) - Array containing data, loaded and error properties, in that order.

Example

import { useDataLoadedError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const [data, loaded, error] = useDataLoadedError(books);
  // Do your stuff here
};

useData(provider, [equalityFn])

Triggers read and gives you only the data property from the state of the provider or selector. When the provider cache is cleaned, it automatically triggers read again.

Arguments are the same than described for the useDataLoadingError hook.

Returns

• (Any) - Value of the data property from the provider state.

Example

import { useData } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const data = useData(books);
  // Do your stuff here
};

useLoading(provider)

Triggers read and gives you only the loading property from the state of the provider or selector. When the provider cache is cleaned, it automatically triggers read again.

Arguments

• provider (Object): Data Provider provider or selector instance.

Returns

• (Boolean) - Value of the loading property from the provider state.

Example

import { useLoading } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const loading = useLoading(books);
  // Do your stuff here
};

useLoaded(provider)

Triggers read and gives you only the loaded property from the state of the provider or selector. When the provider cache is cleaned, it automatically triggers read again.

Arguments

• provider (Object): Data Provider provider or selector instance.

Returns

• (Boolean) - Value of the loaded property from the provider state.

Example

import { useLoaded } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const loaded = useLoaded(books);
  // Do your stuff here
};

useError(provider)

Triggers read and gives you only the error property from the state of the provider or selector. When the provider cache is cleaned, it automatically triggers read again.

Arguments

• provider (Object): Data Provider provider or selector instance.

Returns

• (null)/(Error) - null when the is no error, or Error causing the provider read method rejection.

Example

import { useError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const error = useError(books);
  // Do your stuff here
};

usePolling(provider, [interval/options], [options])

Triggers cleanDependenciesCache method of the provider each interval miliseconds while the component is "alive". It can be used in multiple components at the same time for the same provider. In that case, the used interval will be the lower one, and it will be recalculated each time a component is added or removed.

This hook can also be used with Data Provider selectors, as it will clean the cache of all selector dependencies. So, if you are using a selector combining data from two axios providers, for example, it will result in repeating both provider http requests and recalculating the selector result every defined interval.

Arguments

• provider (Object): Data Provider provider or selector instance.
• interval (Number): Interval in miliseconds to clean the provider dependencies cache. Default is 5000.
• options (Object): Options object that will be passed as is to the cleanCache method of providers or cleanDependenciesCache method of selectors. Check the data-provider API documentation for further info. Options can be defined as second argument if interval is omitted.

Examples

import { useData, usePolling } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = () => {
  const data = useData(books);
  usePolling(books, 3000);
  // Do your stuff here. Books will fetched again from server every 3 seconds
};

import { useData, usePolling } from "@data-provider/react";

import { booksAndAuthors, books } from "../data/books";

const BooksList = () => {
  const data = useData(books);
  usePolling(booksAndAuthors, {
    except: [books]
  });
  // Do your stuff here. booksAndAuthors selector dependencies will fetched again from server every 3 seconds, except the "books" provider.
};

HOCs

withDataLoadingError(provider, [customPropertiesNames])(Component)

This High Order Component triggers the read method of the provider and gives to the component the data, loading and error properties from its state. It will trigger the read method each time the provider cache is cleaned.

Use this HOC only when you need all mentioned properties, because your component will be re-rendered any time one of them changes. If you only need one or two properties, better use one of the HOCs described bellow.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function returning a provider or selector instance, or undefined. The function receives the component props as argument (Use a function when you want to query the provider depending of the component props). The HOC also accepts the function returning undefined, in which case, no provider will be used (so, you can also decide to "not connect" the component dependending of its props)
• customPropertiesNames (Array of Strings): By default, the HOC will pass to the component data, loading and error properties. You can change that props passing an array with new names in the same order (["fooData", "fooLoading", "fooError"]). You can omit properties you don't want to redefine, for example: ["fooData"] will change only the data property.

Examples

Using a provider:

import { withDataLoadingError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data, loading, error }) => {
  // Do your stuff here
};

export default withDataLoadingError(books)(BooksList);

With custom properties:

const BooksList = ({ booksData, booksLoading, booksError }) => {
  // Do your stuff here
};

export default withDataLoadingError(books, ["booksData", "booksLoading", "booksError"])(BooksList);

Using a function:

const BookDetail = ({ data, loading, error }) => {
  // Do your stuff here
};

export default withDataLoadingError(({ id }) => books.query({ urlParam: { id }}))(BookDetail);

withDataLoadedError(provider, [customPropertiesNames])(Component)

This hoc has the same behavior and interface than the described for the withDataLoadingError one, but it provides the data, loaded and error properties from the state.

Use this hook only when you don't want to rerender a Component each time the provider is loading. It will return loaded as true once the provider has loaded for the first time, and it will not change again. This is useful to avoid rerenders in scenarios having "pollings", for example, as it will avoid to render a "loading" each time the data is refreshed.

Take into account that the loaded property will not be set as true until a success read has finished, so the error may have a value, even when loaded is false.

Examples

Using a provider:

import { withDataLoadedError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data, loaded, error }) => {
  // Do your stuff here
};

export default withDataLoadedError(books)(BooksList);

With custom properties:

const BooksList = ({ booksData, booksAreLoaded, booksError }) => {
  // Do your stuff here
};

export default withDataLoadedError(books, ["booksData", "booksAreLoaded", "booksError"])(BooksList);

withData(provider, customPropName)(Component)

This High Order Component triggers the read method of the provider and gives to the component only the data property from its state. It will trigger the read method each time the provider cache is cleaned.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs
• customPropName (String): By default, the HOC will pass to the component a data property. You can change that prop passing a new property name as second argument.

Examples

import { withData } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data }) => {
  // Do your stuff here
};

export default withData(books)(BooksList);

Using custom property:

const BooksList = ({ booksData }) => {
  // Do your stuff here
};

export default withData(books, "booksData")(BooksList);

withLoading(provider, customPropName)(Component)

This High Order Component triggers the read method of the provider and gives to the component only the loading property from its state.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs
• customPropName (String): By default, the HOC will pass to the component a loading property. You can change that prop passing a new property name as second argument.

Examples

import { withLoading } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ loading }) => {
  // Do your stuff here
};

export default withLoading(books)(BooksList);

Using custom property:

const BooksList = ({ booksLoading }) => {
  // Do your stuff here
};

export default withLoading(books, "booksLoading")(BooksList);

withLoaded(provider, customPropName)(Component)

This High Order Component triggers the read method of the provider and gives to the component only the loaded property from its state.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs
• customPropName (String): By default, the HOC will pass to the component a loaded property. You can change that prop passing a new property name as second argument.

Examples

import { withLoaded } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ loaded }) => {
  // Do your stuff here
};

export default withLoaded(books)(BooksList);

Using custom property:

const BooksList = ({ booksLoaded }) => {
  // Do your stuff here
};

export default withLoaded(books, "booksLoaded")(BooksList);

withError(provider, customPropName)(Component)

This High Order Component triggers the read method of the provider and gives to the component only the error property from its state. It will trigger the read method each time the provider cache is cleaned.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs
• customPropName (String): By default, the HOC will pass to the component an error property. You can change that prop passing a new property name as second argument.

Examples

import { withError } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ error }) => {
  // Do your stuff here
};

export default withError(books)(BooksList);

Using custom property:

const BooksList = ({ booksError }) => {
  // Do your stuff here
};

export default withError(books, "booksError")(BooksList);

withPolling(provider, [interval/options], [options])(Component)

This High Order Component works as the hook usePolling described above.

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs
• interval (Number): Interval in miliseconds to clean the provider dependencies cache. Default is 5000.
• options (Object): Options object that will be passed as is to the cleanCache method of providers or cleanDependenciesCache method of selectors. Check the data-provider API documentation for further info. Options can be defined as second argument if interval is omitted.

Example

import { withData, withPolling } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data }) => {
  // Do your stuff here. Books data will fetched again from server every 3 seconds
};

export default withPolling(books, 3000)(withData(books)(BooksList));

Arguments

• provider (Object): Data Provider provider or selector instance, or a function as described in the withDataLoadingError HOC docs

withDataLoadingErrorComponents(provider, [customPropertiesNames])(Component, LoadingComponent, ErrorComponent)

This HOC works as the already described withDataLoadingError, but it will render one component or another depending of the result. If the provider is loading, it will render LoadingComponent, if it has an error, it will render ErrorComponent (passing the error property to it), or it will render Component when there is no error and it is not loading (passing the data property to it).

import { withDataLoadingErrorComponents } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data }) => {
  // Do your stuff here
};

const BooksLoading = () => {
  // Do your stuff here
};

const BooksError = ({ error }) => {
  // Do your stuff here
};

export default withDataLoadingErrorComponents(books)(BooksList, BooksLoading, BooksError);

withDataLoadedErrorComponents(provider, [customPropertiesNames])(Component, NotLoadedComponent, ErrorComponent)

This HOC works as the already described withDataLoadedError, but it will render one component or another depending of the result. If the provider has an error, it will render ErrorComponent (passing the error property to it), if it has not loaded, it will render NotLoadedComponent, or it will render Component when there is no error and it has loaded (passing the data property to it).

import { withDataLoadedErrorComponents } from "@data-provider/react";

import { books } from "../data/books";

const BooksList = ({ data }) => {
  // Do your stuff here
};

const BooksNotLoaded = () => {
  // Do your stuff here
};

const BooksError = ({ error }) => {
  // Do your stuff here
};

export default withDataLoadedErrorComponents(books)(BooksList, BooksNotLoaded, BooksError);

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.