Presto

CursorPaginator

Source
import { CursorPaginator } from "@prestojs/util";

Cursor based paginator

Expects a nextCursor, previousCursor and optional pageSize key in the response. See getPaginationState for how to customise this if your backend implementation differs.

API

Constructor

new CursorPaginator(currentStatePair,internalStatePair)

Source
ParameterTypeDescription
*currentStatePairnull
*internalStatePairnull

Methods

first()

Source

Go to the first page.

Returns
void

firstState()

Source

Return the state for the first page

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

Returns
CursorPaginationState
KeyTypeDescription
cursorstring
pageSizenumber

getRequestInit(props)

Source
ParameterTypeDescription
*props.optionsoptions
*props.queryany
Returns
PaginatorRequestOptions
KeyTypeDescription
headersHeadersInit|Record

Any headers to add to the request. You can unset default headers that might be specified in the default Endpoint.defaultConfig.requestInit by setting the value to undefined.

queryRecord

Any query request parameters

urlArgsRecord

Any arguments for the URL

hasNextPage()

Source

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

Returns
boolean

next()

Source

Go to the next page.

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

Returns
void

nextState()

Source

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.

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

Returns

One of the following:

CursorPaginationState
KeyTypeDescription
cursorstring
pageSizenumber

OR

null

pageSizeState(pageSize)

Source

Return the state for the specified page size

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

ParameterTypeDescription
*pageSizenumber|null
Returns
CursorPaginationState
KeyTypeDescription
cursorstring
pageSizenumber

previous()

Source

Go to the previous page.

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

Returns
void

previousState()

Source

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.

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

Returns

One of the following:

CursorPaginationState
KeyTypeDescription
cursorstring
pageSizenumber

OR

null

setPageSize(pageSize)

Source

Set the page size

ParameterTypeDescription
*pageSizenull|number
Returns
void

setResponse(props)

Source

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

See getPaginationState for how to customise this if your backend implementation differs.

ParameterTypeDescription
*props.nextCursorundefined|null|string
*props.pageSizenumber
*props.previousCursorundefined|null|string
Returns
void

Static Methods

getPaginationState(requestDetails)

Source

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

ParameterTypeDescription
requestDetails.decodedBodyany

The value returned by decodedBody. See Endpoint.execute.

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

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

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

{
    count: 10,
    results: [...]
}
requestDetails.queryRecord

Any query string parameters

requestDetails.responseResponse

The Response object, if available

*requestDetails.urlstring

Resolved URL

requestDetails.urlArgsRecord

Any arguments used to resolve URL

Returns

One of the following:

Record

OR

false

Properties

cursor: string|null

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

nextCursor: string|null

The next cursor (if any)

pageSize: number|null

The current page size, if known

previousCursor: string|null

THe previous cursor (if any)

Inherited Methods

replaceStateControllers(currentStatePair,internalStatePair)

Source

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:

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

ParameterTypeDescription
*currentStatePairany

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.

*internalStatePairany

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.

Returns
void

Inherited Properties

currentState: CursorPaginationState

internalState:

responseIsSet: boolean

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

setCurrentState:
Function

setInternalState:
Function