Skip to content

commandBackend and APIs

Add Pagination

Adds pagination to a list endpoint in the style your project already uses, with a stable order and updated tests.

npx workspacetemplates add add-pagination --tool claude-code

Writes 1 file to .claude/commands/

.claude/commands/add-pagination.md16 lines · 1.1 KBFile
---
description: Adds pagination to a list endpoint in the style your project already uses, with a stable order and updated tests.
argument-hint: "[list endpoint or query function]"
---

Add pagination to: $ARGUMENTS

1. Read the endpoint and the query behind it. Search other list endpoints for an existing convention (page and limit, offset, or cursor) and follow it. If there is none, prefer cursor paging for large or changing tables and page numbers for small admin lists, and say which you chose.
2. Add a default and a hard maximum page size, and validate both inputs.
3. Make the order deterministic: add a unique tiebreaker such as id after the sort column.
4. Return the project's envelope with items plus total or next cursor, whichever fits the chosen style. Avoid an expensive COUNT on huge tables unless the convention requires it.
5. Check that an index supports the sort and filter; if not, name the index to add but do not create it.
6. Update tests: first page, middle page, last page, empty result, limit above the maximum, invalid cursor.
7. Run the tests.

Report the new request and response shape, and the index suggestion if any.

What it does

An unbounded list works in development and times out in production. This command adds paging to one list endpoint, choosing between page numbers and cursors based on what the codebase already does.

It insists on a deterministic sort, since paging over an unstable order skips or repeats rows. Tests cover the first page, the last page and an empty result.

Example

you › /add-pagination GET /customers

agent › Chose cursor paging to match /orders. Params: limit (default 25, max 100), cursor. Order by createdAt desc, id desc.
Response: {items, nextCursor}. 6 tests pass.
Suggested index: customers(created_at, id). Not created.

Questions

Page numbers or cursors?
It copies whatever your other endpoints use. Without a convention it picks cursors for big, changing data and explains why.
Will it add database indexes?
It only recommends one with the exact columns. Creating it is a schema change that you approve yourself.
  • Add Caching

    CommandBackend and APIs

    Free
  • Add Endpoint

    CommandBackend and APIs

    Free
  • Add Health Check

    CommandBackend and APIs

    Free
  • Add Rate Limit

    CommandBackend and APIs

    Free