diff --git a/src/common/helper/page.helper.ts b/src/common/helper/page.helper.ts index 18946f12..ad63d8ea 100644 --- a/src/common/helper/page.helper.ts +++ b/src/common/helper/page.helper.ts @@ -1,6 +1,6 @@ /* * Description: This file implements the PageHelper class. - * Its an utility class for generating the PageResponseDto data. + * It's a utility class for generating the PageResponseDto data. * * Author(s): * Nictheboy Li @@ -10,15 +10,22 @@ import { PageDto } from '../DTO/page-response.dto'; export class PageHelper { - // Used when you do - // - // SELECT ... FROM ... - // WHERE ... - // AND id >= (firstId) - // LIMIT (pageSize + 1) - // ORDER BY id ASC - // - // in SQL. + /** + * Used to paginate data from the starting position. + * Typically used for the initial query to paginate data. + * + * Equivalent SQL: + * SELECT ... FROM ... + * WHERE ... + * AND id >= (firstId) + * LIMIT (pageSize + 1) + * ORDER BY id ASC + * + * @param data Array of data items + * @param pageSize Number of items per page + * @param idGetter Function to get the ID of a data item + * @returns A tuple containing the paginated data array and pagination information + */ static PageStart( data: TData[], pageSize: number, @@ -27,23 +34,31 @@ export class PageHelper { return PageHelper.PageInternal(data, pageSize, false, 0, idGetter); } - // Used when you do both - // - // SELECT ... FROM ... - // WHERE ... - // AND id < (firstId) - // LIMIT (pageSize) - // ORDER BY id DESC - // - // and - // - // SELECT ... FROM ... - // WHERE ... - // AND id >= (firstId) - // LIMIT (pageSize + 1) - // ORDER BY id ASC - // - // in SQL. + /** + * Used to paginate data from a middle position. + * Handles both previous and current page data. + * + * Equivalent SQL for fetching the previous page: + * SELECT ... FROM ... + * WHERE ... + * AND id < (firstId) + * LIMIT (pageSize) + * ORDER BY id DESC + * + * Equivalent SQL for fetching the current page: + * SELECT ... FROM ... + * WHERE ... + * AND id >= (firstId) + * LIMIT (pageSize + 1) + * ORDER BY id ASC + * + * @param prev Array of data items from the previous page + * @param data Array of data items from the current page + * @param pageSize Number of items per page + * @param idGetterPrev Function to get the ID of a data item from the previous page + * @param idGetter Function to get the ID of a data item from the current page + * @returns A tuple containing the paginated data array and pagination information + */ static PageMiddle( prev: TPrev[], data: TData[], @@ -67,14 +82,22 @@ export class PageHelper { ); } - // Used when you do - // - // SELECT ... FROM ... - // WHERE ... - // LIMIT 1000 - // ORDER BY id ASC - // - // in SQL. + /** + * Used to paginate data from a complete dataset. + * This method should be used only when the entire dataset is loaded into memory. + * Determines the starting point for pagination based on the provided pageStart parameter. + * + * This method handles two scenarios: + * 1. When pageStart is undefined, it starts pagination from the beginning of the dataset. + * 2. When pageStart is defined, it starts pagination from the specified ID. + * + * @param allData Array of all data items + * @param pageStart The ID where pagination starts + * @param pageSize Number of items per page + * @param idGetter Function to get the ID of a data item + * @param errorIfNotFound Optional error handler function, called if pageStart is not found in allData + * @returns A tuple containing the paginated data array and pagination information + */ static PageFromAll( allData: TData[], pageStart: number | undefined, @@ -92,7 +115,6 @@ export class PageHelper { const pageStartIndex = allData.findIndex((r) => idGetter(r) == pageStart); if (pageStartIndex == -1) { /* istanbul ignore if */ - // Above is a hint for istanbul to ignore this if-statement. if (errorIfNotFound == undefined) return this.PageStart([], pageSize, idGetter); else errorIfNotFound(pageStart); @@ -103,6 +125,16 @@ export class PageHelper { } } + /** + * Internal method used to handle the core pagination logic. + * + * @param data Array of data items + * @param pageSize Number of items per page + * @param hasPrev Whether there is a previous page + * @param prevStart The starting ID of the previous page + * @param idGetter Function to get the ID of a data item + * @returns A tuple containing the paginated data array and pagination information + */ private static PageInternal( data: TData[], pageSize: number,