@donation-alerts/api/cjs/api/donation-alerts-api-paginator.d.ts

Interact with Donation Alerts API.

import { type RateLimiterRequestOptions } from '@d-fischer/rate-limiter';
import { type DonationAlertsApiCallOptions } from '@donation-alerts/api-call';
import { type UserIdResolvable } from '@donation-alerts/common';
import { type DonationAlertsResponseWithMeta } from './donation-alerts-response';
import { type ApiClient } from '../api-client';
/**
 * Donation Alerts API paginator.
 *
 * @remarks
 * A utility class for managing paginated responses from the Donation Alerts API.
 * This paginator supports navigating through paginated data by individual pages or fetching all data at once. It internally keeps track of the current page, total pages, and other metadata to simplify navigation.
 */
export declare class DonationAlertsApiPaginator<D, T> {
    private readonly _api;
    private readonly _user;
    private readonly _callOptions;
    private readonly _mapper;
    private readonly _rateLimiterOptions?;
    private _path?;
    private _currentPage?;
    private _totalPages?;
    private _from?;
    private _to?;
    private _perPage?;
    private _total?;
    private _currentData?;
    private _isFinished;
    /** @internal */
    constructor(_api: ApiClient, _user: UserIdResolvable, _callOptions: DonationAlertsApiCallOptions, _mapper: (data: D) => T | T[], _rateLimiterOptions?: RateLimiterRequestOptions | undefined);
    /**
     * The current API endpoint path.
     *
     * @remarks
     * This represents the path currently associated with the pagination request.
     */
    get path(): string | undefined;
    /**
     * The index of the first element in the currently fetched page.
     */
    get from(): number | null | undefined;
    /**
     * The index of the last element in the currently fetched page.
     */
    get to(): number | null | undefined;
    /**
     * The current page number.
     *
     * @remarks
     * This value is updated after each retrieval of a specific page.
     */
    get currentPage(): number | undefined;
    /**
     * The total number of pages.
     */
    get totalPages(): number | undefined;
    /**
     * Number of items per page.
     */
    get perPage(): number | undefined;
    /**
     * The total number of items in the dataset.
     */
    get total(): number | undefined;
    /**
     * Indicates whether the paginator has reached the last page.
     *
     * @remarks
     * When this flag is `true`, calling `getNext()` will return an empty array without making additional API requests.
     */
    get isFinished(): boolean;
    /**
     * The raw data of the last retrieved page, including metadata.
     *
     * @returns The full API response for the most recently fetched page, or `undefined` if no request has been made yet.
     */
    get rawData(): DonationAlertsResponseWithMeta<D> | undefined;
    /**
     * Resets the paginator's internal state.
     *
     * @remarks
     * After calling this method, the paginator will appear as if it has not yet fetched any data.
     */
    reset(): void;
    /**
     * Fetches and returns data from a specific page.
     *
     * @remarks
     * If the requested page number exceeds the total number of pages, the method returns an empty array.
     *
     * @param page The page number to fetch. Defaults to `1`.
     *
     * @returns An array of mapped data objects for the requested page.
     *
     * @throws {@link HttpError} if the response status code is not within the `200-299` range.
     * @throws {@link UnregisteredUserError} if the user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token does not include the required scope.
     *
     * @example
     * ```ts
     * const data = await paginator.getPage(42);
     * ```
     */
    getPage(page?: number): Promise<T[]>;
    /**
     * Fetches the next page of data, or the first page if no pages have been loaded yet.
     *
     * @remarks
     * This method automatically increments the page counter and checks the total number of pages to stop requests
     * when the end is reached.
     *
     * @returns An array of mapped data objects for the next page, or an empty array if the last page is reached.
     *
     * @throws {@link HttpError} if the response status code is not within the `200-299` range.
     * @throws {@link UnregisteredUserError} if the user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token does not include the required scope.
     */
    getNext(): Promise<T[]>;
    /**
     * Fetches the previous page of data.
     *
     * @remarks
     * If the current page is `1`, this method will return data for the first page.
     *
     * @returns An array of mapped data objects for the previous page.
     *
     * @throws {@link HttpError} if the response status code is not within the `200-299` range.
     * @throws {@link UnregisteredUserError} if the user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token does not include the required scope.
     */
    getPrev(): Promise<T[]>;
    /**
     * Fetches all pages and aggregates the results into a single array.
     *
     * @remarks
     * This method resets the paginator at the start and end of the operation. It sequentially requests each page
     * and concatenates the results.
     *
     * This method may take longer to execute, especially for users with a large volume of donations.
     * For better performance with large datasets, consider using the {@link getNext} method to fetch data in chunks.
     *
     * @returns A combined array of all mapped data objects from all pages.
     *
     * @throws {@link HttpError} if the response status code is not within the `200-299` range.
     * @throws {@link UnregisteredUserError} if the user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token does not include the required scope.
     */
    getAll(): Promise<T[]>;
    /**
     * Enables asynchronous iteration over all available pages.
     *
     * @throws {@link HttpError} if the response status code is not within the `200-299` range.
     * @throws {@link UnregisteredUserError} if the user is not registered in the authentication provider.
     * @throws {@link MissingScopeError} if the access token does not include the required scope.
     *
     * @example
     * ```ts
     * const paginator = apiClient.donations.createDonationsPaginator();
     *
     * for await (const pageData of paginator) {
     *   console.log(pageData);
     * }
     * ```
     */
    [Symbol.asyncIterator](): AsyncGenerator<T[], void, undefined>;
    private _fetchData;
    private _processData;
}
//# sourceMappingURL=donation-alerts-api-paginator.d.ts.map