feat: add reusable pagination utility service

src/modules/pagination/dto/create-pagination.dto.ts

@@ -1 +1,47 @@
-export class CreatePaginationDto {}
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreatePaginationDto {
+  @ApiPropertyOptional({
+    description: 'Page number for offset pagination',
+    default: 1,
+    minimum: 1,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  page?: number = 1;
+
+  @ApiPropertyOptional({
+    description: 'Number of records per page',
+    default: 20,
+    minimum: 1,
+    maximum: 100,
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit?: number = 20;
+
+  @ApiPropertyOptional({
+    description: 'Opaque cursor for forward pagination',
+    example: 'MQ==',
+  })
+  @IsOptional()
+  @IsString()
+  after?: string;
+
+  @ApiPropertyOptional({
+    description: 'Opaque cursor for backward pagination',
+    example: 'MTA=',
+  })
+  @IsOptional()
+  @IsString()
+  before?: string;
+}
+
+export class PaginationQueryDto extends CreatePaginationDto {}

src/modules/pagination/pagination.module.ts

@@ -4,5 +4,6 @@ import { PaginationService } from './pagination.service';
 @Module({
   controllers: [],
   providers: [PaginationService],
+  exports: [PaginationService],
 })
 export class PaginationModule {}

src/modules/pagination/pagination.service.spec.ts

@@ -0,0 +1,130 @@
+import { Test, TestingModule } from '@nestjs/testing';
+import { BadRequestException } from '@nestjs/common';
+import { PaginationService } from './pagination.service';
+
+const makeQb = (rows: any[], total?: number) => ({
+  skip: jest.fn().mockReturnThis(),
+  take: jest.fn().mockReturnThis(),
+  andWhere: jest.fn().mockReturnThis(),
+  orderBy: jest.fn().mockReturnThis(),
+  getManyAndCount: jest.fn().mockResolvedValue([rows, total ?? rows.length]),
+  getMany: jest.fn().mockResolvedValue(rows),
+});
+
+const makeRepo = (rows: any[], total?: number) => ({
+  findAndCount: jest.fn().mockResolvedValue([rows, total ?? rows.length]),
+});
+
+describe('PaginationService', () => {
+  let service: PaginationService;
+
+  beforeEach(async () => {
+    const module: TestingModule = await Test.createTestingModule({
+      providers: [PaginationService],
+    }).compile();
+    service = module.get<PaginationService>(PaginationService);
+  });
+
+  describe('paginate', () => {
+    it('returns paginated response with correct meta', async () => {
+      const rows = [{ id: 1 }, { id: 2 }];
+      const qb = makeQb(rows, 10) as any;
+
+      const result = await service.paginate(qb, 2, 2);
+
+      expect(result.data).toEqual(rows);
+      expect(result.meta.page).toBe(2);
+      expect(result.meta.limit).toBe(2);
+      expect(result.meta.total).toBe(10);
+      expect(result.meta.totalPages).toBe(5);
+      expect(result.meta.hasNext).toBe(true);
+      expect(result.meta.hasPrev).toBe(true);
+    });
+
+    it('clamps page to minimum 1', async () => {
+      const qb = makeQb([], 0) as any;
+      const result = await service.paginate(qb, -5, 10);
+      expect(result.meta.page).toBe(1);
+    });
+
+    it('enforces max limit of 100', async () => {
+      const qb = makeQb([], 0) as any;
+      const result = await service.paginate(qb, 1, 9999);
+      expect(result.meta.limit).toBe(100);
+    });
+
+    it('includes pagination links when a route is provided', async () => {
+      const qb = makeQb([{ id: 1 }], 5) as any;
+
+      const result = await service.paginate(qb, 2, 2, {
+        route: '/skills',
+        query: { q: 'nodejs' },
+      });
+
+      expect(result.links).toEqual({
+        first: '/skills?q=nodejs&page=1&limit=2',
+        prev: '/skills?q=nodejs&page=1&limit=2',
+        next: '/skills?q=nodejs&page=3&limit=2',
+        last: '/skills?q=nodejs&page=3&limit=2',
+      });
+    });
+
+    it('hasNext is false on last page', async () => {
+      const qb = makeQb([{ id: 1 }], 1) as any;
+      const result = await service.paginate(qb, 1, 10);
+      expect(result.meta.hasNext).toBe(false);
+      expect(result.meta.hasPrev).toBe(false);
+    });
+
+    it('page beyond total still returns valid meta', async () => {
+      const qb = makeQb([], 5) as any;
+      const result = await service.paginate(qb, 100, 10);
+      expect(result.meta.page).toBe(100);
+      expect(result.meta.hasNext).toBe(false);
+    });
+  });
+
+  describe('paginateRepository', () => {
+    it('calls findAndCount with correct skip/take', async () => {
+      const rows = [{ id: 1 }];
+      const repo = makeRepo(rows, 30) as any;
+
+      const result = await service.paginateRepository(repo, 3, 10);
+
+      expect(repo.findAndCount).toHaveBeenCalledWith(
+        expect.objectContaining({ skip: 20, take: 10 }),
+      );
+      expect(result.meta.page).toBe(3);
+    });
+  });
+
+  describe('cursor pagination', () => {
+    it('encodes and decodes cursor round-trip', () => {
+      const encoded = service.encodeCursor('42');
+      expect(service.decodeCursor(encoded)).toBe('42');
+    });
+
+    it('throws BadRequestException for invalid cursor', () => {
+      expect(() => service.decodeCursor('!!invalid!!')).toThrow(BadRequestException);
+    });
+
+    it('returns nextCursor when more rows exist', async () => {
+      const rows = [{ id: 1 }, { id: 2 }, { id: 3 }]; // limit=2, hasMore
+      const qb = makeQb(rows) as any;
+
+      const result = await service.cursorPaginate(qb, 2);
+
+      expect(result.data).toHaveLength(2);
+      expect(result.nextCursor).not.toBeNull();
+    });
+
+    it('returns null nextCursor on last page', async () => {
+      const rows = [{ id: 1 }]; // limit=2, no more
+      const qb = makeQb(rows) as any;
+
+      const result = await service.cursorPaginate(qb, 2);
+
+      expect(result.nextCursor).toBeNull();
+    });
+  });
+});