useAsyncData()
import { useAsyncData } from '@dr.pogodin/react-global-state';
useAsyncData(path, loader, options = {}): object;
Resolves asynchronous data, and stores them at the given path
of global
state. When multiple components rely on asynchronous data at the same path
,
the data are resolved once, and reused until their age is within specified
bounds. Once the data are stale, the hook allows to refreshes them. It also
garbage-collects stale data from the global state when the last component
relying on them is unmounted.
The hook stores loaded async data and related meta data at the path
of global
state in form of AsyncDataEnvelope object. That global state segment can be
accessed, and even modified using other hooks,
e.g useGlobalState(), but doing so you should be careful to not interfere
with the related useAsyncData() hook logic in an undesireable way.
Arguments
path
- string - Dot-delimitered state path, where data envelope is stored.loader
- AsyncDataLoader - Asynchronous function which resolves (loads) async data, which should be stored at the global statepath
. When multiple components use useAsyncData() hook for the samepath
, the library assumes that all hook instances are called with the sameloader
(i.e. whichever of these loaders is used to resolve async data, the result is acceptable to be reused in all related components).options
- object - Optional object with additional parameters:deps
- any[] - An array of dependencies to watch. If provided, the hook will reload async data when any of these dependencies changes. Given dependencies are watched shallowly.noSSR
- boolean - Set true to opt-out of loading async data during the server-side rendering.garbageCollectAge
- number - The maximum age of data (in milliseconds) after which they are dropped from the global state when the last component referencing them via useAsyncCollection() or useAsyncData() hook unmounts. Defaults to the value ofmaxage
option.maxage
- number - The maximum age of data (in milliseconds) acceptable to the hook's caller. If loaded data stored in the global state are older than this value null is returned instread of the loaded data. Defaults to 5 minutes.refreshAge
- number - The maximum age of data (in milliseconds) after which their refresh is triggered when any component referencing them via useAsyncCollection() or useAsyncData() hook is (re-)rendered. Defaults to the value ofmaxage
option.
Result
Returns an object with the following fields:
data
- any - Async data loaded in the lastloader
invokation, if any, and if satisfy themaxage
limit; null otherwise.loading
- boolean - true if the data are being loaded (i.e. the hook is currently waiting for the result of aloader
function's invokation).timestamp
- number - Unix timestamp (in milliseconds) of async data currently loaded into the global state, if any.cautionIf
data
is null because async data loaded into the state do not satisfy themaxage
limit, the value oftimestamp
still will correspond to the time when those async data were loaded into the state.
AsyncDataLoader
function loader(oldData): Promise<any>;
This is the signature of loader
function accepted by useAsyncData() hook.
Arguments
oldData
- any - Previously loaded async data currently stored at thepath
, if any.
Result
Returns a Promise which resolves to the async data.