useAsyncCollection()
import { useAsyncCollection } from '@dr.pogodin/react-global-state';
useAsyncCollection(id, path, loader, options = {}): object;
Resolves and stores at the given path
of global state elements of
an asynchronous data collection. In other words, it is an auxiliar wrapper
around useAsyncData() hook, which uses a loader which resolves to different
data, based on an ID argument passed in, and stores data fetched for different
IDs in the state.
For a given pair of id
and path
arguments this hook will store at
the `${path}.${id}`
path of the global state an AsyncDataEnvelope object
holding the loaded data alongside some related meta-information. 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 useAsyncCollection() hook logic in an undesireable way.
Arguments
id
- string - ID of the collection item to load & use.path
- string - The global state path where entire collection should be stored.loader
- AsyncCollectionLoader - A loader function, which takes an ID of data to load, and resolves to the corresponding data.options
- object - Optional object with additional settings. The valid fields are: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.
AsyncCollectionLoader
function loader(id, oldData): Promise<any>;
This is the signature of loader
function accepted by
useAsyncCollection() hook.
Arguments
id
- string - ID of the collection item to load.oldData
- any - Previously fetched data for this ID, if any are stored in the global state.
Result
Returns a Promise which resolves to the async data loaded for the specified
id
.