useAsyncListing

import { useAsyncListing } from "@prestojs/util";

useAsyncListing(props)

Execute an asynchronous call and return the value which can optionally be paginated.

If the result is paginated you can pass paginator. Whenever the paginator state is changed the function will be called unless trigger is MANUAL. You can pass accumulatePages to accumulate results for sequential pages returned from execute. This is useful to implement things like infinite scroll. If a non-sequential page is accessed or query changes then accumulated results will be cleared.

	Parameter	Type	Description
	props.accumulatePages	boolean	Whether to accumulate pages as more results are fetched. For example if the first page of results is returned, then the next page is fetched then the combined results for the first two pages will be resolved. This resets whenever `query` changes or if pagination state changes to anything other than the next page. If this is true you must specify `paginator`.
*	props.execute	Function	Asynchronous function that returns the result for the query. Passed an object with `query` and `paginator` keys. Note that when `trigger` is `DEEP` changes to this function will cause it to be called again so you must memoize it (eg. with `useCallback`) if it's defined in your component or hook.
	props.paginator	PaginatorInterface\|null	Optional paginator if result is paginated. This will be monitored for any state changes which will trigger a call to `execute`. Required if `accumulatePages` is true.
	props.query	Record	Any query string parameters for the request
	props.trigger	"MANUAL"\|"DEEP"	When to trigger the fetch. Defaults to `DEEP` which means whenever a deep equality check on `query` or `paginator` state fails it will refetch. If set to `MANUAL` nothing will happen until it changes to `DEEP` or you call the returned `run` function. You can use this to defer execution until the value is required. Defaults to 'DEEP'.

Returns

One of the following:

Key	Type	Description
isLoading	boolean	True while `execute` call is in progress.
paginator	null\|PaginatorInterface	The same `paginator` passed in to `useAsyncListing`
reset	Function	When called will set both result and error to null. Will not immediately trigger a call to the action but subsequent changes to query or paginator will according to the value of `trigger`.
run	Function	A function to manually trigger the action. If `options.trigger` is `MANUAL` calling this function is the only way to trigger the action. This function will return a promise that resolves/rejects to same value returned by `execute`. If `accumulatePages` is set the value returned is the accumulated value.
error	null	Until first call has resolved neither error nor result will be set
result	null

Key	Type	Description
isLoading	boolean	True while `execute` call is in progress.
paginator	null\|PaginatorInterface	The same `paginator` passed in to `useAsyncListing`
reset	Function	When called will set both result and error to null. Will not immediately trigger a call to the action but subsequent changes to query or paginator will according to the value of `trigger`.
run	Function	A function to manually trigger the action. If `options.trigger` is `MANUAL` calling this function is the only way to trigger the action. This function will return a promise that resolves/rejects to same value returned by `execute`. If `accumulatePages` is set the value returned is the accumulated value.
error	Error	Set to the rejected value of the promise. Only one of `error` and `result` can be set. If `isLoading` is true consider this stale (ie. based on previous props). This can be useful when you want the UI to show the previous value until the next value is ready.
result	null	Result will not be set when error is set

Key	Type	Description
isLoading	boolean	True while `execute` call is in progress.
paginator	null\|PaginatorInterface	The same `paginator` passed in to `useAsyncListing`
reset	Function	When called will set both result and error to null. Will not immediately trigger a call to the action but subsequent changes to query or paginator will according to the value of `trigger`.
run	Function	A function to manually trigger the action. If `options.trigger` is `MANUAL` calling this function is the only way to trigger the action. This function will return a promise that resolves/rejects to same value returned by `execute`. If `accumulatePages` is set the value returned is the accumulated value.
error	null	Error will not be set when result is set
result	T	The value returned from execute