TypeORM Cursor Pagination

Cursor-based pagination works with TypeORM Query Builder.

If this project is helpful to you, I truly appreciate you all for your stars ⭐⭐⭐ and contributions 💪💪💪.

Installation

npm install typeorm-cursor-pagination --save

Usage

Query first page without any cursor

import { getConnection } from "typeorm";
import { buildPaginator } from 'typeorm-cursor-pagination';
const queryBuilder = getConnection()
  .getRepository(User)
  .createQueryBuilder('user')
  .where("user.gender = :gender", { gender: 'male' });
const paginator = buildPaginator({
  entity: User,
  paginationKeys: ['id'],
  query: {
    limit: 10,
    order: 'ASC',
  },
});
// Pass queryBuilder as parameter to get paginate result.
const { data, cursor } = await paginator.paginate(queryBuilder);

The buildPaginator function has the following options

entity [required]: TypeORM entity.
alias [optional]: alias of the query builder.
paginationKeys [optional]: array of the fields to be used for the pagination, default is id.
query [optional]:
- limit: limit the number of records returned, default is 100.
- order: ASC or DESC, default is DESC.
- beforeCursor: the before cursor.
- afterCursor: the after cursor.

paginator.paginate(queryBuilder) returns the entities and cursor for the next iteration

interface PagingResult<Entity> {
  data: Entity[];
  cursor: Cursor;
}
interface Cursor {
  beforeCursor: string | null;
  afterCursor: string | null;
}

Query next page by `afterCursor`

const nextPaginator = buildPaginator({
  entity: User,
  paginationKeys: ['id'],
  query: {
    limit: 10,
    order: 'ASC',
    afterCursor: cursor.afterCursor,
  },
});
const { data, cursor } = await nextPaginator.paginate(queryBuilder);

Query prev page by `beforeCursor`

const prevPaginator = buildPaginator({
  entity: User,
  paginationKeys: ['id'],
  query: {
    limit: 10,
    order: 'ASC',
    beforeCursor: cursor.beforeCursor,
  },
});
const { data, cursor } = await prevPaginator.paginate(queryBuilder);

Integration Test with Docker

To start an integration test, run the following command:

npm run test:docker

Contributing

All contributions are welcome, open a pull request or issue any time.

Commit your changes using a descriptive commit message that follows commit message conventions.

License

Released under the MIT License