TypeORM Cursor Pagination

Cursor-based pagination works with TypeORM Query Builder.

Why or What is Cursor-Based Pagination

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

© Ben Hu (benjamin658), 2021-NOW

Released under the MIT License