feat(utils): add get pagination params

Author: cyber-hari

src/types/api-response.ts

@@ -179,3 +179,39 @@ export interface StreamResponse {
   /** Chunk size in bytes */
   chunkSize: number;
 }
+
+/**
+ * Sort direction enumeration.
+ */
+export enum SortDirection {
+  /** Ascending sort order */
+  ASC = 'asc',
+
+  /** Descending sort order */
+  DESC = 'desc'
+}
+
+/**
+ * Pagination parameters for API requests.
+ */
+export interface PaginationParams {
+  /** Current page number (1-based index) */
+  page: number;
+
+  /** Number of records per page */
+  limit: number;
+
+  /** Field by which the data is sorted */
+  sortBy: string;
+
+  /** Sort order: ascending or descending */
+  sortOrder: SortDirection;
+
+  /** Optional search query */
+  search?: string;
+}
+
+/**
+ * Type that combines pagination parameters with additional data.
+ */
+export type WithPagination<T = {}> = PaginationParams & T;

src/utils/request.utils.ts

@@ -22,6 +22,9 @@
  * SOFTWARE.
  */
 
+import { Request } from 'express';
+import { SortDirection, WithPagination } from '../types/api-response';
+
 /**
  * Options for parsing and validating request parameters.
  */
@@ -53,6 +56,32 @@ export interface ValidationResult<T> {
   error?: string;
 }
 
+/**
+ * Extracts pagination, sorting, and optional search params from a request.
+ *
+ * @param req - Express request
+ * @returns Object containing validated pagination, sorting, and additional query params
+ */
+export const getPaginationParams = <T = {}>(req: Request): WithPagination<T> => {
+  const query = req.query as Record<string, string | string[]>;
+
+  // Extract page & limit
+  const { page, limit } = extractPaginationParams(query, 1, 20, 100);
+  const { sortBy, sortOrder } = extractSortParams(query, []);
+
+  // Optional search param
+  const search = typeof query.search === 'string' ? query.search : undefined;
+
+  return {
+    ...(query as T),
+    page,
+    limit,
+    sortBy,
+    sortOrder: sortOrder as SortDirection,
+    search
+  };
+};
+
 /**
  * Safely parses a string parameter to a number.
  *
@@ -199,7 +228,7 @@ export function extractSortParams(
   }
 
   // Validate field
-  if (!allowedFields.includes(sortBy)) {
+  if (allowedFields.length && !allowedFields.includes(sortBy)) {
     sortBy = defaultSort.sortBy;
   }