@clayui/data-provider

ClayDataProvider component

Usage no npm install needed!

<script type="module">
  import clayuiDataProvider from 'https://cdn.skypack.dev/@clayui/data-provider';
</script>

README

title: 'Data Provider' description: 'Simple but very powerful client, it was designed to help you consume data easily.' lexiconDefinition: 'https://liferay.design/lexicon/core-components/dropdowns/' packageNpm: '@clayui/data-provider'

import { DataProvider, DataProviderWithCacheRootLevel, DataProviderWithNetworkStatus, UseResource, UseResourceWithJitter, UseResourceWithNetworkStatus, UseResourceWithVariablesChange, } from '$packages/clay-data-provider/docs/index';

Introduction

ClayDataProvider gives functionality of data caching, attempts, polling, network status and avoiding the thundering herd problem. It is simple and powerful because:

  • Easy adoption, you can incrementally use in your application and both useResource hook and ClayDataProvider component and have all the functionality available.
  • Simple to start, use the basics you already know or take advantage of the full set of features to get the most out of it.
  • Built for data to reflect what users are doing in your application, it works perfectly for cases where data changes according to user interaction.
  • Extensible, enjoy the single cache in only one source of truth and save data between navigations to be used in future interactions.

Getting started

To consume data, you can work with two different ways in React, using the <ClayDataProvider /> component or useResource hook. We recommend that you use useResource for cases where your component has more logic to handle data, so it decreases the complexity and eliminates logic within JSX, use <ClayDataProvider /> for simpler cases that do not have so much logic involved in the data or when you are not familiar with hooks.

useResource hook

The vast majority of APIs are the same between useResource and <ClayDataProvider />, the difference is that there is no notifyOnNetworkStatusChange API in useResource, you control them via the OnNetworkStatusChange parameter when you need it.

Features

Retry

Make attempts on a request several times when a network or server error occurs.

fetchRetry is easy to set up and is enabled by default with the jitter setting for delays between attempts by default.

Warning The values ​​contained in the code below are the default value.

Network Status

The DataProvider provides network status information for you if you want to create customizations in those statuses. If you are using <ClayDataProvider /> you can enable this information by activating the notifyOnNetworkStatusChangeAPI prop, once activated it will cause new renderings each time the network status changes.

Using network status with hooks is another option, it does not provide an abstraction for loading, error and networkStatus and all information is collected through the onNetworkStatusChange callback.

  • loading is equivalent to networkStatus < 4
  • error is equivalent to status === 5

Variables change

variables is an API for GET requests that help satisfy whether your cache will be retrieved from storage or not, this can be useful for cases where your data is formed by user interactions such as Autocomplete, you can still set a delay on the fetchDelay prop to ensure that your requests are not called every time a change of input value occurs, for example.

Caching data

You can cache your requests so that in new user interactions a new request is no longer necessary, by default the cache is deactivated.

The cache is guided by a policy, use the fetchPolicy prop to enable and configure the cache according to your use case.

Warning The cache is governed by the algorithm least recently used ( LRU ), you can set the amount of data that will be stored using the storageMaxSize API. Each new query is equivalent to 1 size.

Data Fetching

const {resource} = useResource({fetch, link});

This is an API that replaces the link behavior of receiving an async function, this did not allow us to validate the cache correctly because we do not have the URL view. This API is more friendly and has a unique responsibility, you may be able to pass an async function that accepts the link and options, and return the data. useResource will use its async function instead of the fetch default.

Fetch

import fetch from 'unfetch';

const App = () => {
    const {resource} = useResource({fetch, link: 'https://clay.dev'});
    // ...
};

Advanced

Avoiding thundering herd problem

Starting with delay.initial, the delay of each subsequent retry is increased exponentially, meaning it's multiplied by 2 each time. For example, if delay.initial is 100, additional retries will occur after delays of 200, 400, 800, etc.

With the jitter option enabled, delays are randomized anywhere between 0ms (instant), and 2x the configured delay. This way you get the same result on average, but with random delays.

These two features combined help alleviate the thundering herd problem, by distributing load during major outages. Without these strategies, when your server comes back up it will be hit by all of your clients at once, possibly causing it to go down again.

Warning The implementation of this was based on the apollo-link-retry plugin for React Apollo.

Caching data at root level

The DataProvider can be used on small components that need some data and if it is very reused by the application in other pages, it does not make sense to consult this data every time the user interacts with it in other parts of your application, you can take advantage of the root level cache, ensuring that the next user interactions in the component are with data in the cache, even if it is on other pages.

API

DataProvider

[APITable "clay-data-provider/src/index.tsx"]