import type { Misina, MisinaRequestInit, MisinaResponse } from "../types.mjs";
export interface PaginateContext {
	attempt: number;
	response: MisinaResponse<unknown>;
	url: string;
}
export interface PaginateOptions<
	T,
	R = unknown
> {
	/** Extract the page items from a response. Default: `res.data` if array, else `[]`. */
	transform?: (response: MisinaResponse<R>) => T[] | Promise<T[]>;
	/** Filter items per page. */
	filter?: (item: T) => boolean;
	/**
	* Build the next request. Return `false` to stop. Return a partial init to
	* issue a follow-up request. If omitted, follows `Link: rel=next` headers.
	*/
	next?: (response: MisinaResponse<R>, ctx: PaginateContext) => false | {
		url?: string;
		init?: MisinaRequestInit;
	} | Promise<false | {
		url?: string;
		init?: MisinaRequestInit;
	}>;
	/** Stop after N total items. */
	countLimit?: number;
	/** Stop after N requests. */
	requestLimit?: number;
}
/**
* Async-iterate over a paginated REST endpoint. Default behavior follows the
* `Link: rel="next"` header (RFC 5988). Use `next` for cursor or page-number
* APIs.
*
* ```ts
* for await (const user of paginate(misina, "/users")) { ... }
* ```
*
* Built-in cycle detection: if the same URL is visited twice without a
* change in `init`, the iterator stops (prevents infinite loops on a
* misconfigured `next` callback).
*/
export declare function paginate<
	T = unknown,
	R = unknown
>(misina: Misina, input: string, options?: PaginateOptions<T, R>, init?: MisinaRequestInit): AsyncIterableIterator<T> & AsyncDisposable;
/** Materialize a paginator into an array. */
export declare function paginateAll<
	T = unknown,
	R = unknown
>(misina: Misina, input: string, options?: PaginateOptions<T, R>, init?: MisinaRequestInit): Promise<T[]>;