@anpdgovbr/shared-types/dist/cjs/interfaces/pagination.helpers.d.ts

Biblioteca central de tipos TypeScript compartilhados para os projetos da ANPD (BETA)

/**
 * @fileoverview
 * Utilitários e helpers para trabalhar com paginação de resultados.
 *
 * @remarks
 * Este módulo fornece funções auxiliares para calcular metadados de paginação,
 * validar parâmetros e criar respostas paginadas padronizadas.
 *
 * @module interfaces/pagination.helpers
 * @public
 */
import type { BasePaginatedResponse } from "./base-paginated-response.interface";
import type { BaseQueryParams } from "./base-query-params.interface";
/**
 * Metadados calculados de paginação.
 *
 * @remarks
 * Interface que contém informações úteis sobre o estado da paginação,
 * calculadas a partir dos parâmetros de consulta e total de itens.
 */
export interface PaginationMeta {
    /**
     * Número total de páginas disponíveis.
     */
    totalPages: number;
    /**
     * Número da página atual (1-indexed).
     */
    currentPage: number;
    /**
     * Tamanho da página (quantidade de itens por página).
     */
    pageSize: number;
    /**
     * Indica se existe uma próxima página.
     */
    hasNext: boolean;
    /**
     * Indica se existe uma página anterior.
     */
    hasPrevious: boolean;
    /**
     * Índice do primeiro item da página atual (0-indexed).
     */
    startIndex: number;
    /**
     * Índice do último item da página atual (0-indexed).
     */
    endIndex: number;
    /**
     * Número total de itens em todas as páginas.
     */
    totalItems: number;
}
/**
 * Calcula os metadados de paginação.
 *
 * @param page Número da página atual (1-indexed)
 * @param pageSize Tamanho da página
 * @param totalItems Total de itens disponíveis
 * @returns Metadados calculados da paginação
 *
 * @example
 * ```typescript
 * const meta = calculatePaginationMeta(2, 20, 150)
 * console.log(meta.totalPages) // 8
 * console.log(meta.hasNext) // true
 * console.log(meta.hasPrevious) // true
 * ```
 */
export declare function calculatePaginationMeta(page: number, pageSize: number, totalItems: number): PaginationMeta;
/**
 * Valida e normaliza parâmetros de paginação.
 *
 * @param params Parâmetros de consulta recebidos
 * @returns Parâmetros validados e normalizados
 *
 * @remarks
 * - Garante que `page` seja >= 1
 * - Garante que `pageSize` esteja entre MIN_PAGE_SIZE e MAX_PAGE_SIZE
 * - Aplica valores padrão quando não especificados
 *
 * @example
 * ```typescript
 * const params = validatePaginationParams({ page: 0, pageSize: 1000 })
 * console.log(params.page) // 1 (corrigido)
 * console.log(params.pageSize) // 100 (limitado ao máximo)
 * ```
 */
export declare function validatePaginationParams(params: Partial<BaseQueryParams>): Required<Pick<BaseQueryParams, "page" | "pageSize">> & {
    search?: string;
    orderBy?: string;
    ascending?: boolean;
};
/**
 * Cria uma resposta paginada padronizada.
 *
 * @template T Tipo dos itens da página
 * @param data Array de itens da página atual
 * @param page Número da página atual
 * @param pageSize Tamanho da página
 * @param total Total de itens disponíveis
 * @returns Resposta paginada completa com metadados
 *
 * @example
 * ```typescript
 * const usuarios = [{ id: 1, nome: "João" }, { id: 2, nome: "Maria" }]
 * const response = createPaginatedResponse(usuarios, 1, 20, 50)
 * console.log(response.hasNext) // true
 * console.log(response.total) // 50
 * ```
 */
export declare function createPaginatedResponse<T>(data: T[], page: number, pageSize: number, total: number): BasePaginatedResponse<T>;
/**
 * Calcula o offset (skip) para consultas ao banco de dados.
 *
 * @param page Número da página (1-indexed)
 * @param pageSize Tamanho da página
 * @returns Número de registros a pular (offset)
 *
 * @example
 * ```typescript
 * const offset = calculateOffset(3, 20)
 * console.log(offset) // 40 (pula as 2 primeiras páginas)
 * ```
 */
export declare function calculateOffset(page: number, pageSize: number): number;
/**
 * Verifica se a página solicitada existe dado o total de itens.
 *
 * @param page Número da página
 * @param pageSize Tamanho da página
 * @param totalItems Total de itens disponíveis
 * @returns `true` se a página existe, `false` caso contrário
 *
 * @example
 * ```typescript
 * const exists = isValidPage(10, 20, 150)
 * console.log(exists) // false (apenas 8 páginas disponíveis)
 * ```
 */
export declare function isValidPage(page: number, pageSize: number, totalItems: number): boolean;
/**
 * Calcula o range de páginas a serem exibidas em uma paginação de UI.
 *
 * @param currentPage Página atual
 * @param totalPages Total de páginas
 * @param maxVisible Número máximo de páginas a exibir (padrão: 7)
 * @returns Array com números de páginas a exibir
 *
 * @remarks
 * Útil para criar componentes de paginação no frontend.
 *
 * @example
 * ```typescript
 * const pages = getPageRange(5, 10, 5)
 * console.log(pages) // [3, 4, 5, 6, 7]
 * ```
 */
export declare function getPageRange(currentPage: number, totalPages: number, maxVisible?: number): number[];
/**
 * Cria uma resposta vazia paginada (quando não há resultados).
 *
 * @template T Tipo dos itens (inferido)
 * @returns Resposta paginada vazia
 *
 * @example
 * ```typescript
 * const empty = createEmptyPaginatedResponse<Usuario>()
 * console.log(empty.total) // 0
 * console.log(empty.data) // []
 * ```
 */
export declare function createEmptyPaginatedResponse<T>(): BasePaginatedResponse<T>;
//# sourceMappingURL=pagination.helpers.d.ts.map