pagination.md

Using Pagination

As this project deals with multiple API sources (Rest, GraphQL etc) from different vendors there is a standard set of pagination arguments which should be supported by each backend to have consistency between the API implementations.

See Pagination for code.

Where is Pagination used?

The Pagination arguments are present in the following methods:

• getProducts(keyword)
• getProducts(category)

Parameters for method supporting Pagination

pageNum?: number
cursor?: string
cursorPage?: number
pageSize?: number
pageCount?: number

total?: number (only returned)

Param	Meaning	Notes
pageNum	the index of the page to fetch (0 based)	If the pageNum is undefined, it will be 0.
pageSize	the size of each page	If pageSize is undefined, it will select a default value.
pageCount	the number of pages to fetch (starting at pageNum)	If pageCount is undefined, all items will be fetched.
cursor	the cursor string of the closet previously known page.	Used to speed up pagination on cursor based APIs. If the cursor is undefined, the desired page number will still be fetched but this cursor will be used to fetch it faster.
cursorPage	the page that he cursor string corresponds to.	If it is less than or equal to the requested page, time can be saved fetching the page with the cursor, rather than having to iterate the list up to the requested point. If the cursorPage is undefined, cursor cannot be used and will be treated as undefined.
total	the total number of pages.	This cannot be set and is returned if available as a number.

Usage

Paginated methods return updated information about the page in the arguments object that was originally provided. For example, cursor and cursorPage will be updated to match the 'after' cursor for the next page when making a cursor pagination request. When the total number of items is known, it is returned in total, otherwise it is left undefined. When an undefined pageCount is provided, the backend should return the pageCount it decided to use.

Helper Methods

Backends must implement pagination on these methods in the way described above. Fortunately, there are helper methods to let you do pagination with proper arguments writeback in pagination.ts.

Method	Meaning	Usage	Notes
paginateArgs	Paginate a normal endpoint using arguments from a codec method.	Provide a getPage method that gets a page by pageNum and pageSize.	-
paginateCursorArgs	Paginate an endpoint that uses cursors using arguments from a codec method.	Provide a getPage method that gets a page by cursor and pageSize.	This method may request additional pages if the start cursor and cursorPage isn't the same as the requested page.
getListPage	Generate a getPage method for a full list of items.	useful if pagination is not supported by the backend.	See the REST codec example for use.
paginateBlankArgs	Properly handle pagination arguments for cases where there is always no result data.

Examples

paginateArgs()

await paginateArgs(exampleMethod, args, 123)

Input args:

{
    pageCount: 2,
    pageNum: 1,
    pageSize: 20
}

Example response:

[21, 22, 23]

Output args:

{
    pageCount: 2,
    pageNum: 1,
    pageSize: 20,
    total: 23
}

paginateCursorArgs()

Example request:

await paginateCursorArgs(exampleCursorMethod, args, 123)

Input args:

{
    cursor: 'prevPage',
    cursorPage: 1,
    pageCount: 2,
    pageNum: 1,
    pageSize: 3
}

Example response:

{
    data: [4, 5, 6, 7, 8, 9],
    hasNext: true,
    nextCursor: 'nextPage',
}

Output args:

{
    cursor: 'nextPage',
    cursorPage: 3,
    pageCount: 2,
    pageNum: 1,
    pageSize: 3,
    total: 12,
}

getListPage()

Example request:

getListPage([1, 2, 3, 4, 5, 6, 7, 8, 9])(1, 3))

Example response:

{ 
    data: [4, 5, 6], 
    total: 9 
}

paginateBlankArgs()

Example request:

paginateBlankArgs(args)

Input args:

{
    pageNum: 0,
    pageSize: 20,
}

Example response:

[]

Output args:

{
    pageNum: 0,
    pageSize: 20,
    total: 0
}