nestjs-paginate

nestjs-paginate is a helper for NestJS that adds pagination, filtering, sorting, and search to TypeORM repositories and query builders. A single paginate() call reads query parameters, applies safe, whitelisted operations, and returns a JSON:API-conforming response with data and pagination metadata, removing the boilerplate of building paged list endpoints by hand.

It supports filtering with a rich operator set ($eq, $in, $gt, $btw, $ilike, and more), sorting by multiple columns, column selection, relation and nested-relation loading, virtual columns, and both offset and cursor-based pagination. A @Paginate() parameter decorator and Swagger helpers integrate it cleanly into NestJS controllers.

What You Get

• A paginate() helper for TypeORM repositories and query builders
• JSON:API-conforming responses with data and pagination links/metadata
• Filtering with operators like $eq, $in, $gt, $btw, $ilike, and $contains
• Multi-column sorting, column selection, and cross-column search
• Relation loading, virtual columns, and cursor-based pagination

Common Use Cases

• Building paginated list endpoints in NestJS REST APIs
• Exposing safe, whitelisted filtering and sorting to API clients
• Adding search across multiple columns to a resource endpoint
• Implementing cursor-based pagination over large TypeORM datasets

Under The Hood

Architecture — The core lives in src/paginate.ts, which accepts a query object, a TypeORM repository or query builder, and a PaginateConfig describing sortable/searchable/filterable columns. filter.ts and filter-expression.ts translate the operator DSL ($eq, $in, $btw, $ilike, etc.) into safe TypeORM where-clauses, helper.ts handles relations and column selection, and decorator.ts provides the @Paginate() param decorator with a swagger/ module for API docs.

Tech Stack — TypeScript with a single runtime dependency (lodash) and peer dependencies on @nestjs/common, @nestjs/swagger, typeorm, and Express/Fastify — keeping the package light and framework-aligned.

Code Quality — Coverage is strong: paginate, filter, filter-expression, and decorator each ship .spec.ts suites with Codecov reporting and semantic-release automation. The whitelisting model (only configured columns are filterable/sortable) is a deliberate safety design against injection of arbitrary query params.

API Design — Usage is one paginate() call plus a declarative config, returning a JSON:API-shaped result; the @Paginate() decorator removes controller boilerplate and Swagger helpers document the query contract automatically. The operator syntax mirrors familiar query semantics, keeping the learning curve modest.