npm package: @stubbies/nestjs-paginate-lib
Description: A reusable pagination library for NestJS and TypeORM
Latest version: 1.0.0


# 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

```bash
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`.

```typescript
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.

```typescript
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`).

```typescript
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:

```json
{
  "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