useAsyncChoices

Hook that makes it easy to use an [AsyncChoices](doc:AsyncChoicesInterface) definition.

This hook does the following:

1) Calls [useListProps](doc:AsyncChoicesInterface#method-useListProps) to get any dependencies for [list](doc:AsyncChoicesInterface#method-list)

2) Calls [list](doc:AsyncChoicesInterface#method-list) and passes through the dependencies and a `query` object representing any query parameters for the async call

3) Calls [useRetrieveProps](doc:AsyncChoicesInterface#method-useRetrieveProps) to get any dependencies for [retrieve](doc:AsyncChoicesInterface#method-retrieve)

4) If there is a current `value` [retrieve](doc:AsyncChoicesInterface#method-retrieve) is called and is passed the dependencies returned above

5) An object is returned with the available choices in `choices`, the result of 2 in `list` and result of 4 in `selected`


props

UseAsyncChoicesProps

UseAsyncChoicesReturn

ItemT

ValueT

UseAsyncValueReturn

Set to the rejected value of the promise. Only one of `error` and `value` 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.

error

True while `resolve` call is in progress.

isLoading

boolean

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`.

If value is found in `existingValues` then it will still be returned even if
you call `reset` - `reset` only clears values that are returned from `resolve`.


reset

__type

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.


value

Variables

currentState

State

internalState

InternalState

responseIsSet

setCurrentState

__call

setInternalState

first

void

firstState

getRequestInit

options

PaginatorRequestOptions

hasNextPage

nextState

previousState

replaceStateControllers

currentStatePair

internalStatePair

setResponse

response

Properties

Methods

CursorPaginator

InferredPaginator

LimitOffsetPaginator

PageNumberPaginator

Paginator

PaginatorInterface

null

Record

constructor

new Paginator

PaginatorInterface.currentState

PaginatorInterface.internalState

PaginatorInterface.setCurrentState

PaginatorInterface.setInternalState

True once setResponse has been called and pagination state is known.

__get

PaginatorInterface.responseIsSet

PaginatorInterface.first

PaginatorInterface.firstState

Does not transition state. To transition state call `first` instead.


PaginatorInterface.getRequestInit

Return the options to use with `Endpoint.execute` or `Endpoint.prepare`. Usually
this just involves setting `query` to the query string parameters for the paginator
but can also provide custom headers or different URL resolve arguments.

PaginatorInterface.hasNextPage

Returns true if there's more results after the current page

PaginatorInterface.next

PaginatorInterface.nextState

Does not transition state. To transition state call `next` instead.


PaginatorInterface.previous

PaginatorInterface.previousState

Does not transition state. To transition state call `previous` instead.


PaginatorInterface.replaceStateControllers

Paginator receives 2 tuples of a state and state setter pair. This is expected to
match the same interface as `useState` in React. The following is a valid simple usage:

```js
const paginator = new Paginator(useState(), useState());
```

Note that we can also pass the state controllers in via `replaceStateControllers` rather
than in the constructor. This is so we can memoize the `Paginator` instance which is desirable
when using the paginator as a dependency to React hooks.

As state is passed in and managed external to the class be aware that any data stored
on the class instance will be lost unless written with `setCurrentState` or `setInternalState`.
This design is a compromise between allowing a clear interface for how paginators should
be defined and allowing the state to be managed externally (eg. using React state).


PaginatorInterface.setResponse

This is called when an `Endpoint` has resolved and is passed the response from the
endpoint. This is used to update the relevant paginator state  - eg. the total
number of records, next & previous cursors etc.

Constructors

Accessors

Pick

UseAsyncListingProps

asyncChoices

listOptions

onRetrieveError

onRetrieveSuccess

retrieveOptions

The state object and setter (eg. from `useState`) that is used to store
and transition pagination state. Using this you can do things like easily store state in the URL
(eg. using `useUrlQueryState`) or other data sources.

The state object and setter that is used for internal state. Internal state
is stored separately as it does not need to be restored (eg. if you refresh the page). It is used
to store things like the total number of results or the current cursor. Passing `useState` here is
fine.


See [getChoices](doc:AsyncChoicesInterface#method-getChoices)

choices

ReturnType

See [useAsyncListing](doc:useAsyncListing#return-type)

list

UseAsyncListingReturn

See [useAsyncValue](doc:useAsyncValue#return-type)

selected

The response as returned by the endpoint this paginator is used with.


Omit

RequestInit

headers

query

urlArgs

eg. the return value from [Endpoint.execute](doc:Endpoint#method-execute)

PaginationRequestDetails

The value returned by `decodedBody`. See [Endpoint.execute](doc:Endpoint#method-execute).

This may be a sub-key of the data returned by `Endpoint.execute`, eg. if the `path` option is used in
[paginationMiddleware](doc:paginationMiddleware). eg. If `decodedBody` from the `Endpoint` was

```json
{
    users: {
        count: 10,
        results: [...],
    }
    extraDetails: {...}
}
```

and `paginationMiddleware` was used with `path: 'users'` then `decodedBody` would be:

```json
{
    count: 10,
    results: [...]
}
```


decodedBody

Response

string

UseAsyncListingExecuteProps

paginator

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`.


accumulatePages

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.


execute

Optional paginator if result is paginated. This will be monitored for
any state changes which will trigger a call to `execute`.

Any query string parameters for the request

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'.


trigger

Paginator.__constructor

new CursorPaginator

Paginator.currentState

CursorPaginationState

Paginator.internalState

InternalCursorPaginatorState

Paginator.setCurrentState

Paginator.setInternalState

The current cursor. This will be null before the first response is received.

cursor

nextCursor

pageSize

previousCursor

Paginator.responseIsSet

Paginator.first

Paginator.firstState

Paginator.getRequestInit

__namedParameters

Paginator.hasNextPage

Paginator.next

If the last next is not yet known because results haven't been returned this function
does nothing.


Paginator.nextState

Return the state for the first page. If the next page isn't yet known (eg. results
haven't yet been returned) then null will be returned.

pageSizeState

Return the state for the specified page size

Does not transition state. To transition state call `setPageSize` instead.


Paginator.previous

If the previous page is not yet known because results haven't been returned this function
does nothing.


Paginator.previousState

Return the state for the previous page. If the previous page isn't yet known (eg. results
haven't yet been returned) then null will be returned.

Paginator.replaceStateControllers

setPageSize

Paginator.setResponse

Sets the internal data based on response. Expects `nextCursor`, `previousCursor` and optionally `pageSize` to be in
response data.

See [getPaginationState](doc:getPaginationState) for how to customise this if your backend implementation
differs.


getPaginationState

Expected pagination state in the shape:
{
    next: null|'http://example.com/?cursor=abc123',
    previous: null|'http://example.com/?cursor=abc123',
    results: Array
}

requestDetails

Expects a `nextCursor`, `previousCursor` and optional `pageSize` key in the response. See
[getPaginationState](doc:getPaginationState) for how to customise this if your backend implementation
differs.


new LimitOffsetPaginator

LimitOffsetPaginationState

InternalLimitOffsetPaginationState

limit

number

offset

The total number of records available. This will be null before the first response is received.

total

last

If the last page is not yet known because results haven't been returned this function
does nothing.


lastState

Return the state for the last page. If the last page isn't yet known (eg. results
haven't yet been returned) then null will be returned.

Does not transition state. To transition state call `last` instead.


limitState

Does not transition state. To transition state call `setLimit` instead.


offsetState

Return the state for the specified offset

Does not transition state. To transition state call `offsetState` instead.


setLimit

setOffset

Sets the internal data based on response. Expects `limit` to be in response data.

Expects a `limit` key in the response. See [getPaginationState](doc:getPaginationState) for how
to customise this if your backend implementation differs.


	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.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'.
*	props.asyncChoices	AsyncChoicesInterface	See [AsyncChoices](doc:AsyncChoices]
	props.listOptions	Record	Any extra options to pass through to list These will be available in both useListProps and list under the `listOptions` key
	props.onRetrieveError	Function	If provided this function will be called whenever `asyncChoices.retrieve` errors You can use this to do things like unset a value if it no longer exists.
	props.onRetrieveSuccess	Function	If provided this function will be called whenever a value is successfully resolved using `asyncChoices.retrieve`.
	props.retrieveOptions	Record	Any extra options to pass through to retrieve These will be available in both useRetrieveProps and retrieve under the `retrieveOptions` key
	props.value	ValueT[]\|ValueT\|null	The currently selected choice(s) - if any When specified the corresponding label(s) will be resolved automatically.

Key	Type	Description
choices	ReturnType	See getChoices
list	UseAsyncListingReturn	See useAsyncListing
selected	UseAsyncValueReturn	See useAsyncValue