Registry / web-framework / nestjs-typeorm-paginate

nestjs-typeorm-paginate

library4.1.0jsnpmunverified

The `nestjs-typeorm-paginate` library provides a robust and strictly typed pagination solution for NestJS applications integrated with TypeORM. It simplifies the process of generating pagination objects from TypeORM repositories or query builders, ensuring type safety throughout your codebase. The current stable version is 4.1.0, which is specifically designed for compatibility with TypeORM `^0.3.0` and a broad spectrum of `@nestjs/common` versions up to `^11.0.0`. The project's release cadence is often tied to major version updates of TypeORM and NestJS, necessitating careful version management during upgrades. Its key differentiators include explicit support for both `Repository` instances and `QueryBuilder` objects, offering flexibility in how data is queried, alongside comprehensive TypeScript typings for all pagination options and the resulting paginated data structure, making it a reliable choice for complex data presentation needs.

web-framework database

npm install nestjs-typeorm-paginate

github ↗package ↗

INSTALL

IMPORT

SIG · NESTJS-TYPEORM-PAG

nestjs-typeorm-paginate

web-frameworkjavascriptv4.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

paginate

✓ import { paginate } from 'nestjs-typeorm-paginate';

✗ const paginate = require('nestjs-typeorm-paginate').paginate;

This is the primary function used to perform pagination on a TypeORM repository or query builder.

Pagination

✓ import { Pagination } from 'nestjs-typeorm-paginate';

✗ import { IPaginationResult } from 'nestjs-typeorm-paginate';

Represents the structure of the returned paginated data, including items, meta, and links. Older versions might have used `IPaginationResult`.

IPaginationOptions

✓ import { IPaginationOptions } from 'nestjs-typeorm-paginate';

Interface for defining the pagination parameters, such as `page`, `limit`, and `route`.

This quickstart demonstrates how to implement pagination in a NestJS application using `nestjs-typeorm-paginate`. It covers the setup of a `CatEntity`, a `CatService` that utilizes the `paginate` function with a TypeORM `QueryBuilder`, and a `CatsController` that handles URL query parameters for page and limit, returning a `Pagination` object.

import { Controller, DefaultValuePipe, Get, ParseIntPipe, Query, Injectable } from '@nestjs/common'; import { Repository, Entity, PrimaryGeneratedColumn, Column } from 'typeorm'; import { InjectRepository } from '@nestjs/typeorm'; import { paginate, Pagination, IPaginationOptions } from 'nestjs-typeorm-paginate'; // cat.entity.ts @Entity('cats') export class CatEntity { @PrimaryGeneratedColumn() id: number; @Column() name: string; @Column() breed: string; } // cat.service.ts @Injectable() export class CatService { constructor( @InjectRepository(CatEntity) private readonly repository: Repository<CatEntity>, ) {} async paginate(options: IPaginationOptions): Promise<Pagination<CatEntity>> { // Example using a QueryBuilder const queryBuilder = this.repository.createQueryBuilder('c'); queryBuilder.orderBy('c.name', 'ASC'); return paginate<CatEntity>(queryBuilder, options); } } // cats.controller.ts @Controller('cats') export class CatsController { constructor(private readonly catService: CatService) {} @Get('') async index( @Query('page', new DefaultValuePipe(1), ParseIntPipe) page: number = 1, @Query('limit', new DefaultValuePipe(10), ParseIntPipe) limit: number = 10, ): Promise<Pagination<CatEntity>> { limit = limit > 100 ? 100 : limit; // In a real application, BASE_URL would be dynamically determined, e.g., from request context const baseUrl = process.env.BASE_URL ?? 'http://localhost:3000'; return this.catService.paginate({ page, limit, route: `${baseUrl}/cats`, }); } }

Debug

Known issues

breakingVersion 4.0.0 introduced breaking changes by requiring TypeORM v0.3.0 or higher. Previous TypeORM versions (e.g., v0.2.x) are incompatible with `nestjs-typeorm-paginate@4.x`.

fix

Upgrade your TypeORM dependency to `^0.3.0` or later. If maintaining TypeORM `^0.2.6`, you must use `nestjs-typeorm-paginate^3.2.0`.

affects: >=4.0.0

gotchaThe `route` property within `IPaginationOptions` is essential for generating accurate pagination links in the response metadata. Omitting this option will result in a `Pagination` object without crucial link information.

fix

Always provide the `route` property in your `IPaginationOptions` object, specifying the base URL for your paginated API endpoint (e.g., `{ page, limit, route: 'http://api.example.com/items' }`).

affects: >=3.0.0

breakingMajor versions of `nestjs-typeorm-paginate` may introduce subtle changes to the `Pagination` interface or `IPaginationOptions` properties, potentially requiring minor adjustments in consuming code.

fix

Consult the package's `CHANGELOG.md` or TypeScript type definitions (`.d.ts` files) when upgrading to understand any structural changes to the pagination objects or options.

affects: >=4.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'createQueryBuilder') OR TypeError: queryRunner.release is not a function

This typically indicates an incompatibility between your installed TypeORM version and `nestjs-typeorm-paginate`.

fix

Verify that your TypeORM version (`^0.3.0` or higher) is compatible with `nestjs-typeorm-paginate@4.x`. For TypeORM `^0.2.x`, you should use `nestjs-typeorm-paginate@3.x`.

Property 'links' does not exist on type 'Pagination<T>'

The `route` option was not provided to the `paginate` function, which prevents the library from generating the pagination links.

fix

Ensure you are passing a `route` property within your `IPaginationOptions` object. For example: `this.catService.paginate({ page, limit, route: '/api/cats' })`.

Error: Nest can't resolve dependencies of the CatService (?). Please make sure that the argument CatRepository at index [0] is available in the CatModule context.

The TypeORM repository for the `CatEntity` has not been correctly registered or provided within the NestJS module where `CatService` is used.

fix

Ensure that `TypeOrmModule.forFeature([CatEntity])` is imported in the `imports` array of the relevant NestJS module (e.g., `CatModule`) that provides `CatService`.

Upgrade

Version history

4.1.0latest on npm

Audit

Dependencies

@nestjs/commonrequiredPeer dependency for integration with the NestJS framework.

typeormrequiredPeer dependency as the core ORM used for database interactions.

Agent activity

9 hits · last 30 days

node

Perplexity

Resources

githubhttps://github.com/nestjsx/nestjs-typeorm-paginate ↗

packagehttps://www.npmjs.com/package/nestjs-typeorm-paginate ↗