feat: custom count query (#1082)

Author: natoszme

README.md

@@ -211,7 +211,7 @@ export class CatsController {
 
 ### Config
 
-```ts
+````ts
 const paginateConfig: PaginateConfig<CatEntity> {
   /**
    * Required: true (must have a minimum of one column)
@@ -376,8 +376,31 @@ const paginateConfig: PaginateConfig<CatEntity> {
    * will be treated as a separate search term, allowing for more flexible matching.
    */
   multiWordSearch: false,
+
+  /**
+   * Required: false
+   * Type: (qb: SelectQueryBuilder<T>) => SelectQueryBuilder<any>
+   * Default: undefined
+   * Description: Callback that lets you override the COUNT query executed by
+   * paginate(). The function receives a **clone** of the original QueryBuilder,
+   * so it already contains every WHERE clause and parameter parsed by
+   * nestjs-paginate.
+   *
+   * Typical use-case: remove expensive LEFT JOINs or build a lighter DISTINCT
+   * count when getManyAndCount() becomes a bottleneck.
+   *
+   * Example:
+   * ```ts
+   * buildCountQuery: qb => {
+   *   qb.expressionMap.joinAttributes = [];   // drop all joins
+   *   qb.select('p.id').distinct(true);       // keep DISTINCT on primary key
+   *   return qb;                              // paginate() will call .getCount()
+   * }
+   * ```
+   */
+  buildCountQuery: (qb: SelectQueryBuilder<T>) => SelectQueryBuilder<any>,
 }
-```
+````
 
 ## Usage with Query Builder
 

src/paginate.spec.ts

@@ -2993,6 +2993,24 @@ describe('paginate', () => {
         expect(result.links.current).toBe('?page=1&limit=20&sortBy=id:ASC')
     })
 
+    it('uses custom count builder when provided', async () => {
+        const fakeQB = { getCount: jest.fn().mockResolvedValue(42) } as any
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+            select: ['id', 'name', 'color'],
+            buildCountQuery: () => fakeQB,
+        }
+        const query: PaginateQuery = {
+            path: '',
+            select: ['id', 'color'],
+        }
+
+        const page = await paginate<CatEntity>(query, catRepo, config)
+
+        expect(fakeQB.getCount).toHaveBeenCalledTimes(1)
+        expect(page.meta.totalItems).toBe(42)
+    })
+
     describe('should return result based on date column filter', () => {
         it('with $not and $null operators', async () => {
             const config: PaginateConfig<CatEntity> = {

src/paginate.ts

@@ -90,6 +90,7 @@ export interface PaginateConfig<T> {
     multiWordSearch?: boolean
     defaultJoinMethod?: JoinMethod
     joinMethods?: Partial<MappedColumns<T, JoinMethod>>
+    buildCountQuery?: (qb: SelectQueryBuilder<T>) => SelectQueryBuilder<any>
 }
 
 export enum PaginationLimit {
@@ -819,7 +820,12 @@ export async function paginate<T extends ObjectLiteral>(
     if (query.limit === PaginationLimit.COUNTER_ONLY) {
         totalItems = await queryBuilder.getCount()
     } else if (isPaginated && config.paginationType !== PaginationType.CURSOR) {
-        ;[items, totalItems] = await queryBuilder.getManyAndCount()
+        if (config.buildCountQuery) {
+            items = await queryBuilder.getMany()
+            totalItems = await config.buildCountQuery(queryBuilder.clone()).getCount()
+        } else {
+            ;[items, totalItems] = await queryBuilder.getManyAndCount()
+        }
     } else {
         items = await queryBuilder.getMany()
     }