NestJS TypeORM Pagination Lib

A reusable, opinionated library for paginating TypeORM SelectQueryBuilder results in NestJS applications. It encapsulates the logic for applying pagination (skip/take), calculates total pages, and formats the response into a standardized DTO with metadata.

Features:

• TypeORM Support: Works directly with SelectQueryBuilder.
• Standardized Response: Returns data alongside total, page, limit, and totalPages.
• Swagger Ready: DTOs are decorated with @nestjs/swagger for automatic API documentation.
• Validation: Built-in class-validator decorators for query parameters.

Installation

npm install nestjs-paginate-lib

Note: This library relies on typeorm, @nestjs/common, @nestjs/swagger, class-validator, and class-transformer as peer dependencies. Ensure they are installed in your project.

Quick Start

1. Import the Module

Import PaginationModule into your feature module or root AppModule.

import { Module } from '@nestjs/common';
import { PaginationModule } from 'nestjs-paginate-lib';

@Module({
  imports: [
    PaginationModule,
    // ... other modules
  ],
})
export class AppModule {}

2. Use in Service

Inject PaginationService and pass your TypeORM SelectQueryBuilder and the PaginationQueryDto to the paginate method.

import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { PaginationService, PaginationQueryDto } from 'nestjs-paginate-lib';
import { User } from './user.entity';

@Injectable()
export class UsersService {
  constructor(
    @InjectRepository(User)
    private readonly userRepository: Repository<User>,
    private readonly paginationService: PaginationService,
  ) {}

  async findAll(paginationQuery: PaginationQueryDto) {
    const queryBuilder = this.userRepository.createQueryBuilder('user');

    queryBuilder
      .where('user.isActive = :isActive', { isActive: true })
      .orderBy('user.createdAt', 'DESC');

    return this.paginationService.paginate(queryBuilder, paginationQuery);
  }
}

3. Use in Controller

Use the PaginationQueryDto with the @Query decorator. Swagger will automatically pick up the query parameters (page and limit).

import { Controller, Get, Query } from '@nestjs/common';
import { PaginationQueryDto } from 'nestjs-paginate-lib';
import { UsersService } from './users.service';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll(@Query() paginationQuery: PaginationQueryDto) {
    return this.usersService.findAll(paginationQuery);
  }
}

API Reference

Input: PaginationQueryDto

The PaginationQueryDto automatically handles validation and defaults.

| Field | Type | Default | Description | | :--- | :--- | :--- | :--- | | page | number | 1 | The current page number (minimum 1). | | limit | number | 10 | Items per page (minimum 1). |

Output: PaginationResponseDto<T>

The service returns a standardized JSON structure:

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "isActive": true
    }
    // ... items
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "totalPages": 10
  }
}

• data: Array of items T.
• meta.total: Total number of items in the database matching the query.
• meta.page: Current page number.
• meta.limit: Number of items per page.
• meta.totalPages: Total number of pages based on the limit.

License

MIT