paginate

Parses pagination query parameters into structured shapes on the domain accumulator (acc). Works in concert with send()’s paginate: true option to automatically generate RFC 8288 Link headers and X-Total-Count for paginated responses.

Supports two strategies: offset (page/per_page) and cursor (opaque cursor token + limit).

Pipeline stage: Negotiation

Import

import {paginate} from '@centralping/ergo';

Options

Option	Type	Default	Description
strategy	'offset' | 'cursor'	'offset'	Pagination strategy
defaultPage	number	1	Default page number (offset strategy)
defaultPerPage	number	20	Default items per page (offset strategy)
maxPerPage	number	100	Maximum items per page (offset strategy)
defaultLimit	number	20	Default item limit (cursor strategy)
maxLimit	number	100	Maximum item limit (cursor strategy)

Return Value

Returns parsed pagination parameters stored at acc.paginate. The shape depends on the active strategy:

Offset strategy:

{
  strategy: 'offset',
  page: 1,        // clamped to ≥ 1
  perPage: 20,    // clamped to ≤ maxPerPage
  offset: 0,      // computed: (page - 1) * perPage
  limit: 20,      // same as perPage
}

Cursor strategy:

{
  strategy: 'cursor',
  cursor: undefined,  // opaque string from query, or undefined on first page
  limit: 20,          // clamped to ≤ maxLimit
}

Response-side contract

This page documents the request-side contract — what paginate() parses and stores at acc.paginate. For the response-side contract (response.paginate shape that your handler returns and the conditions under which send() generates headers), see the Pagination recipe.

Error Responses

None. Invalid or missing query parameters fall back to defaults silently.

Usage

Standalone

import http from 'node:http';
import {compose, url, paginate, handler} from '@centralping/ergo';

const pipeline = compose(
  url(),
  paginate(),
  async (req, res, acc) => {
    const {offset, limit} = acc.paginate;
    const items = await db.find(offset, limit);
    const total = await db.count();
    return {
      response: {body: items, paginate: {total}},
    };
  },
);

const server = http.createServer(
  handler(pipeline, {paginate: true}),
);

When using standalone compose(), you must include url() before paginate() — the pagination middleware reads parsed query parameters from acc.url.query.

ergo-router

router.get('/articles', {
  paginate: true,
  execute: async (req, res, acc) => {
    const {offset, limit} = acc.paginate;
    const items = await db.find(offset, limit);
    const total = await db.count();
    return {
      response: {body: items, paginate: {total}},
    };
  },
});

ergo-router automatically includes url() parsing and enables send()’s paginate option when paginate is set in the route config.

RFC References

• RFC 8288 — Web Linking

Related Recipes

• Pagination — End-to-end offset and cursor pagination with auto-generated Link headers

API Reference

See the auto-generated paginate API docs.