usePaginator

Hook to help manage paginator state. An instance of the specified paginator is created with provided
state setter or a default setter if none provided. You only need to provide a state setter if you
want to store the state somewhere external eg. from URL query parameters.

Must either be an object with a `getPaginatorClass` method (eg.
[Endpoint](doc:Endpoint)) or a [Paginator](doc:Paginator) class. This class defines how pagination is
handled.

paginatorClassOrProvider

A tuple of current state and a state setter function. If not provided state
is handled internally in usePaginator. You can pass `useState()` to this parameter.


currentStatePair

PaginatorInterface

PaginatorState

null

currentState

State

internalState

InternalState

responseIsSet

boolean

setCurrentState

__type

__call

setInternalState

first

void

firstState

getRequestInit

options

PaginatorRequestOptions

hasNextPage

nextState

previousState

replaceStateControllers

internalStatePair

setResponse

response

Properties

Methods

CursorPaginator

InferredPaginator

LimitOffsetPaginator

PageNumberPaginator

Paginator

Record

constructor

new PaginatorInterfaceClass

args

Function

FunctionConstructor

Function.arguments

arguments

Function.caller

caller

Function.length

length

number

Returns the name of the function. Function names are read-only and can not be changed.

Function.name

name

string

Function.prototype

prototype

Function.[Symbol.hasInstance]

[Symbol.hasInstance]

Determines whether the given value inherits from this function if this function was used
as a constructor function.

A constructor function can control which objects are recognized as its instances by
'instanceof' by overriding this method.


value

Function.apply

apply

Calls the function, substituting the specified object for the this value of the function, and the specified array for the arguments of the function.

this

thisArg

argArray

Function.bind

bind

For a given function, creates a bound function that has the same body as the original function.
The this object of the bound function is associated with the specified object, and has the specified initial parameters.

Function.call

call

Calls a method of an object, substituting another object for the current object.

getPaginationState

requestDetails

Function.toString

toString

Returns a string representation of a function.

Constructors

PaginatorInterfaceClass

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.

Accessors

Variables

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.


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

getPaginatorClass

PaginatorClassProvider

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.


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

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

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.


TestDataItem

label

new Record

item

_key

getLabel

new PageNumberPaginator

PageNumberPaginationState

InternalPageNumberPaginationState

page

The total number of results available on the backend

totalPages

Adds `page` and `pageSize` into query options passed through to the endpoint

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

	Parameter	Type	Description
*	paginatorClassOrProvider	PaginatorInterfaceClass\|PaginatorClassProvider	Must either be an object with a `getPaginatorClass` method (eg. Endpoint) or a Paginator class. This class defines how pagination is handled.
	currentStatePair	[PaginatorState, Function ]	A tuple of current state and a state setter function. If not provided state is handled internally in usePaginator. You can pass `useState()` to this parameter.

	Parameter	Type	Description
*	paginatorClassOrProvider	PaginatorInterfaceClass\|PaginatorClassProvider\|null
	currentStatePair	[PaginatorState, Function ]