Pagination

WorkApps uses cursor-based pagination exclusively. Never use offset-based pagination.

Manual Pagination

1// First page — omit cursor2const page1 = await sdk.listRecords('tasks', {3  pageSize: 25,4  sort: 'created_at:desc',5});67// page1.meta.hasMore  — true if more pages exist8// page1.meta.cursor   — pass to next request9// page1.meta.total    — total count (omitted for apps with more than ~10,000 records)1011// Next page — pass cursor from previous response12if (page1.meta.hasMore) {13  const page2 = await sdk.listRecords('tasks', {14    pageSize: 25,15    sort: 'created_at:desc',16    cursor: page1.meta.cursor,17  });18}

paginateRecords(entityKey, options?) — Async Generator

The SDK provides an async generator that handles cursor passing automatically:

1for await (const record of sdk.paginateRecords('tasks', {2  filter: { status: { eq: 'open' } },3  sort: 'due_date:asc',4  pageSize: 50,5})) {6  renderTask(record);7}

Options

Safety Limits

To prevent unbounded iteration on large entities, use maxPages and/or maxRecords:

1for await (const record of sdk.paginateRecords('tasks', {2  maxPages: 10,       // Stop after 10 pages3  maxRecords: 500,    // Stop after 500 records total4  signal: controller.signal,  // Cancel on navigation/unmount5})) {6  process(record);7}

Error Handling During Pagination

If a page fetch fails, the error is re-thrown with the page number and cursor included in the message:

1try {2  for await (const record of sdk.paginateRecords('tasks')) {3    process(record);4  }5} catch (error) {6  // error.message includes page number and cursor for debugging7  console.error('Pagination failed:', error.message);8}

Reads During Maintenance

paginateRecords (and all read methods) are allowed during maintenance mode. Only writes throw MaintenanceError immediately.

Page Size Limits

Requesting more than 100 records per page throws a validation error.