/** Fetch one page. Implementations must send BOTH limit and offset. */
export type PageFetcher<T> = (params: {
    limit: number;
    offset: number;
}) => Promise<T[]>;
export interface CollectPagesOptions {
    /**
     * Requested page size. This is a HINT, not a cap: the server is free to
     * return fewer rows, and whatever it returns for the first page becomes the
     * stride for the rest of the walk. Deliberately larger than any cap we know
     * of so a single round trip suffices where the server allows it.
     */
    readonly pageSize?: number;
    /** Stop after this many rows. Undefined means "every row". */
    readonly want?: number;
    /** Start here. Defaults to 0. */
    readonly offset?: number;
    /**
     * Safety valve for a server that neither errors nor advances. Exceeding it
     * throws — a loud failure is always preferable to a quietly short list.
     */
    readonly maxPages?: number;
}
export interface CompletePage<T> {
    readonly rows: T[];
    readonly total: number;
    readonly offset: number;
    readonly limit: number;
    readonly has_more: boolean;
}
export interface CompletePopulation<T> {
    readonly rows: T[];
    readonly total: number;
    readonly pages: number;
    readonly complete: true;
}
export type CompletePageFetcher<T> = (params: {
    limit: number;
    offset: number;
}) => Promise<CompletePage<T>>;
export declare const DEFAULT_PAGE_REQUEST = 5000;
export declare const DEFAULT_MAX_PAGES = 1000;
export declare class PaginationError extends Error {
    constructor(message: string);
}
/**
 * Walk a bounded list endpoint until it is exhausted (or `want` rows are in
 * hand) and return the rows in server order.
 *
 * Termination is driven entirely by what comes back:
 *   - an empty page ends the walk;
 *   - a page shorter than the stride is the last page;
 *   - a full page means "there may be more", so we ask again at the next offset.
 *
 * A server that ignores `offset` would otherwise loop forever handing back the
 * same page; that is detected via `identify` and raised rather than silently
 * cut short.
 */
export declare function collectPages<T>(fetchPage: PageFetcher<T>, identify: (row: T) => string | undefined, options?: CollectPagesOptions): Promise<T[]>;
/**
 * Walk a producer that reports its complete match total on every page.
 *
 * This is intentionally stricter than `collectPages`: a complete population
 * is evidence, not a best-effort list. The producer total must remain stable,
 * offsets must advance exactly by the rows returned, every row must have a
 * unique identity, and the terminal page must account for the whole total.
 */
export declare function collectCompletePages<T>(fetchPage: CompletePageFetcher<T>, identify: (row: T) => string | undefined, options?: Pick<CollectPagesOptions, "pageSize" | "maxPages">): Promise<CompletePopulation<T>>;
//# sourceMappingURL=paginate.d.ts.map