Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: detailed comments for PageHelper methods #213

Open
wants to merge 1 commit into
base: dev
Choose a base branch
from
Open

docs: detailed comments for PageHelper methods #213

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 68 additions & 36 deletions src/common/helper/page.helper.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <[email protected]>
Expand All @@ -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<TData>(
data: TData[],
pageSize: number,
Expand All @@ -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<TPrev, TData>(
prev: TPrev[],
data: TData[],
Expand All @@ -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<TData>(
allData: TData[],
pageStart: number | undefined,
Expand All @@ -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);
Expand All @@ -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
*/
andylizf marked this conversation as resolved.
Show resolved Hide resolved
private static PageInternal<TData>(
data: TData[],
pageSize: number,
Expand Down
Loading