Miss any of our Open RFC calls?Watch the recordings here! »

@data-provider/react

1.2.0 • Public • Published

Build status Coverage Status Quality Gate

NPM dependencies Renovate Last commit Last release

NPM downloads License

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

Available HOCs

Hooks

useDataProvider(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 { useDataProvider } from "@data-provider/react";
 
import { books } from "../data/books";
 
const BooksList = () => {
  const [data, loading, error] = useDataProvider(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 useDataProvider 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])

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 (Object): Interval in miliseconds to clean the provider dependencies cache. Default is 5000.

Example

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
};

HOCs

withDataProvider(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 { withDataProvider } from "@data-provider/react";
 
import { books } from "../data/books";
 
const BooksList = ({ data, loading, error }) => {
  // Do your stuff here
};
 
export default withDataProvider(books)(BooksList);

With custom properties:

const BooksList = ({ booksData, booksLoading, booksError }) => {
  // Do your stuff here
};
 
export default withDataProvider(books, ["booksData", "booksLoading", "booksError"])(BooksList);

Using a function:

const BookDetail = ({ data, loading, error }) => {
  // Do your stuff here
};
 
export default withDataProvider(({ id }) => books.query({ urlParam: { id }}))(BookDetail);

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 withDataProvider 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 withDataProvider 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 withDataProvider 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 withDataProvider 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])(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 withDataProvider HOC docs
  • interval (Object): Interval in miliseconds to clean the provider dependencies cache. Default is 5000.

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

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

This HOC works as the already described withDataProvider, 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 Component when there is no error and it is not loading (passing the data property to it).

import { withDataProviderBranch } 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 withDataProviderBranch(books)(BooksList, BooksLoading, BooksError);

Contributing

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

Install

npm i @data-provider/react

DownloadsWeekly Downloads

1,037

Version

1.2.0

License

MIT

Unpacked Size

48.3 kB

Total Files

7

Last publish

Collaborators

  • avatar