Pagination

An API usually does not return thousands of items in one response. It returns a smaller set of items called a page. The response also contains a method to request the next page. This process is pagination.

Packbase uses different pagination methods for different resources. The inbox uses a cursor. Search uses an offset. Some endpoints return the full list.

Cursor-based pagination

The inbox uses cursor-based pagination. A cursor is a bookmark that the server returns. Do not read or change the cursor. Save the value and send it unchanged in the next request.

The first request does not require a cursor. Its response contains a cursor for the next request. The has_more Boolean shows whether another page is available.

This method lets new notifications arrive while you request older notifications.

Paginated<T> shape

import type { Paginated, Notification } from '@packbase/sdk-ts'

// Paginated<T> wraps any list response
type InboxPage = Paginated<Notification>

• data: the items in this page.
• has_more: true if another page is available.
• cursor: the bookmark to pass with the next request.
• total_count: the total number of matching items, when the endpoint provides it.

Example: fetch all inbox notifications

async function fetchAllNotifications() {
  const notifications = []
  let cursor: string | undefined

  let has_more = true
  do {
    const page = await pb.inbox.fetch({ limit: 50, cursor })
          
const page: Paginated<Notification>
    notifications.push(...page.data)
    cursor = page.cursor
    has_more = page.has_more
  } while (has_more)

  return notifications
}

The loop always makes one request. After each response, it saves the cursor and checks has_more. A large inbox can cause this loop to make many requests. For a large inbox, use a “Load more” button.

Pack members are not paginated

Not every list requires a pagination loop. The pack members endpoint returns one full array:

async function fetchAllMembers(packId: string) {
  return pb.packs(packId).members()
}

"Load more" UI pattern

For a button interface, keep the loaded items, latest cursor, and hasMore value in the application state. This example omits framework-specific state code:

async function loadMore() {
  const page = await pb.inbox.fetch({ limit: 20, cursor })
        
const page: Paginated<Notification>
  items = [...items, ...page.data]
  cursor = page.cursor
  hasMore = page.has_more
}

Call loadMore() once for the first page and again whenever the user asks for more. Disable or hide the button when hasMore becomes false.

Offset pagination with the search builder

Search uses offset-based pagination. An offset is the number of matching items to omit. .take(25).skip(0) requests the first 25 items. .take(25).skip(25) requests the next 25 items.

Calculate these numbers with .skip() and .take(). Alternatively, use .page():

// Page 1 (items 0-24)
const page1 = from('packs').orderBy('created_at').take(25).skip(0).build()

// Page 2 (items 25-49)
const page2 = from('packs').orderBy('created_at').take(25).skip(25).build()

// Or use the helper (1-indexed)
const page3 = from('packs').orderBy('created_at').page(3, 25).build()
// Equivalent: take(25).skip(50)

You can request multiple pages at the same time with Promise.all(). Most interfaces request a page only when it is necessary:

const [{ p1 }, { p2 }] = await Promise.all([
  pb.search({ p1: from('packs').page(1, 20).build() }),
  pb.search({ p2: from('packs').page(2, 20).build() }),
])

Select the pagination method

The endpoint specifies the pagination method. Examine the return value and use the applicable continuation value: