Pagination
Pagination has two modes. Offset mode supports numbered pages. Cursor mode moves forward through a result without the cost of large offsets.
| Mode | Request | Counts by default | Good for |
|---|---|---|---|
offset | pageIndex (starts at 1), pageSize | "exact" | numbered pages, "page 4 of 12" |
cursor | cursor from the previous page | "none" | feeds, "load more", infinite scroll, exports |
Offset
import type { QueryRequest } from "drizzle-resource";
const pagination: QueryRequest["pagination"] = {
mode: "offset",
pageIndex: 1,
pageSize: 25,
count: "exact",
};
Page 1 is offset 0; page 500 with 25 rows per page is offset 12,475. The response repeats the mode:
import type { QueryOffsetPageInfo } from "drizzle-resource";
const pageInfo: QueryOffsetPageInfo = {
mode: "offset",
pageIndex: 1,
pageSize: 25,
hasNextPage: true,
count: "exact",
rowCount: 12_483,
};
Change pageIndex in the example below to move through the sample data.
Cursor
Allow cursor mode on the resource, and make it the default if you like:
const query = {
pagination: { modes: ["cursor", "offset"] },
defaults: {
pagination: { mode: "cursor", pageSize: 25 },
},
sort: {
defaults: [{ key: "createdAt", dir: "desc" }],
},
} satisfies ExampleQueryConfig;
The first request has no cursor. Each next request sends the nextCursor of the previous response:
import type { QueryRequestInput } from "drizzle-resource";
const firstPage: QueryRequestInput["pagination"] = {
mode: "cursor",
pageSize: 25,
};
const nextPage: QueryRequestInput["pagination"] = {
mode: "cursor",
cursor: "opaque-cursor-from-the-previous-response",
pageSize: 25,
};
Cursor mode needs a visible, sortable root id:
- The engine appends it to the sort when missing, so
createdAt descbecomescreatedAt desc, id descand equal timestamps keep a stable order. - It fetches one extra id to know whether there's a next page. That row isn't returned.
import type { QueryCursorPageInfo } from "drizzle-resource";
const pageInfo: QueryCursorPageInfo = {
mode: "cursor",
pageSize: 25,
nextCursor: "opaque-next-cursor",
count: "none",
rowCount: null,
};
A cursor is a position in one ordered result. Reset it to null when the sorting, filters, search or scope change.
Exact counts
An exact count reads every matching row. Cursor mode skips it by default; ask for it when the interface shows a total:
import type { QueryRequestInput } from "drizzle-resource";
const pagination: QueryRequestInput["pagination"] = {
mode: "cursor",
cursor: null,
pageSize: 25,
count: "exact",
};
pageInfo.count tells TypeScript whether rowCount is a number:
import type { QueryPageInfo } from "drizzle-resource";
declare const pageInfo: QueryPageInfo;
if (pageInfo.count === "exact") {
pageInfo.rowCount;
} else {
pageInfo.rowCount;
}
Either mode accepts either count policy: an offset "load more" endpoint can skip the count too.
Limits
const validation = {
maxPageSize: 100,
maxCursorLength: 1024,
} satisfies ResourceQueryValidationConfig;
maxPageSize applies to both modes. maxCursorLength defaults to 2,048 characters and is enforced by direct calls and by the Zod and Valibot request schemas.
Cursor pages can't jump to page 500 or show a page count without an exact total. Keep offset mode for numbered navigation.