Pagination

Add paginate when one logical call spans many pages and you want the stitch to follow them for you — it loops until you say stop, aggregates every page's items into one array, and applies auth, retry, and throttle to each page along the way.

Example

import { stitch } from 'stitchapi';

const allUsers = stitch({
    baseUrl: 'https://api.example.com',
    path: '/users',
    paginate: {
        next: (prevBody) => {
            const cursor = (prevBody as { nextCursor?: string }).nextCursor;
            return cursor ? { query: { cursor } } : undefined;
        },
        items: (value) => (value as { results: unknown[] }).results,
        pages: 20,
    },
});

Each page reads nextCursor off the raw body and asks for the next page; when the body has no cursor, next returns undefined and the loop stops. prevBody and value arrive as unknown — narrow them before you reach in.

Options

next(prevBody, pagesFetched) receives the previous page's raw body plus the page count and returns the StitchInput for the next page, merged over the original call — set only what changes, like a cursor or page number. Return undefined to stop.

items(value) selects the array to aggregate from each page's picked value; it defaults to the value itself when that value is already an array. The pick runs first, so pair items with pick when the array sits under an envelope, and use items to dig into a nested shape.

pages caps the page count as a safety net (default 50) so a misbehaving next can't loop forever.

Auth, retry, and throttle apply per page, not once for the whole run: a throttle of "2/s" paces the page loop, and a retry recovers each page on its own.

See also