TypeORM Paginator

Cursor-based pagination that works with TypeORM Query Builder. Read about the general idea of cursor-based pagination here.

This package is a fork of the typeorm-paginator package with some tweaks. See the Key differences from other packages section for more details.

The biggest difference is directional cursors. Directional cursors store the direction of pagination inside them. They allow to provide only one parameter to paginate in any direction.

• Installation
• Usage
  • With the Configuration step
    • Configuration
    • Retrieving pages
  • Without the configuration step
• Key differences from other packages
  • typeorm-paginator
  • typeorm-cursor-pagination
• Contributing
• Migration
  • v1 to v2
• License

Installation

npm install typeorm-cursor-paginate --save

Usage

With the Configuration step

Start by importing the CursorPaginator class:

import { CursorPaginator } from "typeorm-cursor-paginate";

Configuration

Instantiate the paginator with your target entity and define the ordering strategy. In this example, users are sorted by their name in ascending order and by id in descending order:

const paginator = new CursorPaginator(User, {
  orderBy: { name: "ASC", id: "DESC" },
});

Prepare your query:

const query = repoUsers.createQueryBuilder();
// you can apply desired "where" conditions to the query

Retrieving pages

1. Retrieving the First Page

   Use the paginator to fetch the initial set of results. Here, a limit of 2 items per page is specified:

   const firstPageResult = await paginator.paginate(query, { limit: 2 });

   Output structure:

   {
     nodes: [
       User { id: 4, name: 'a' },
       User { id: 3, name: 'b' },
     ],
     hasPrevPage: false,
     hasNextPage: true,
     prevPageCursor: "some-cursor-string",
     nextPageCursor: "some-cursor-string",
   }

2. Navigating to the Next Page

   To retrieve the next set of results, pass the nextPageCursor from the first query:

   const secondPageResult = await paginator.paginate(query, {
     limit: 2,
     // Use the nextPageCursor from the previous result
     pageCursor: firstPageResult.nextPageCursor,
   });

   Output structure:

   {
     nodes: [
       User { id: 1, name: 'c' },
       User { id: 2, name: 'c' },
     ],
     hasPrevPage: true,
     hasNextPage: true,
     prevPageCursor: "some-cursor-string",
     nextPageCursor: "some-cursor-string",
   }

Without the configuration step

There is also a way to skip the configuration step and use the paginate function directly. First, import the default from the package:

import paginate from "typeorm-cursor-paginate";

Then, use it like this:

// create a query builder
const query = repoUsers.createQueryBuilder();
// you can apply desired "where" conditions to the query

// Get the first page
const result = await paginate(User, query, {
  orderBy: { name: "ASC", id: "DESC" },
  limit: 2,
});

// Get the next page
const resultNext = await paginate(User, query, {
  orderBy: { name: "ASC", id: "DESC" },
  limit: 2,
  pageCursor: result.nextPageCursor,
});

Key differences from other packages

typeorm-paginator

typeorm-paginator is the original package that this one is based on.

Here are the key differences:

• Directional cursors: In the original package, cursors are not directional. The pagination direction was determined by what argument the cursor is passed to. This package, on the other hand, stores the direction of pagination inside the cursor. It allows to provide only one parameter to paginate in any direction.
• Type safety: Added some more type safety to the code. Now the orderBy property only accepts keys that are present in the entity.
• Removed PageCursor: The PageCursor class was removed. This package is about cursor-based pagination.
• No default "limit": Original package had a default limit of 20. Now, if the limit is omitted, all results will be returned.

typeorm-cursor-pagination

typeorm-cursor-pagination is another package that provides cursor-based pagination for TypeORM. As of now, March 2025, it gets more and more popular than the typeorm-paginator package.

Here are the key differences:

• Ability to provide different directions for different columns in orderBy: In the typeorm-cursor-pagination package, all columns in the orderBy array had to have the same direction. This package, on the other hand, allows to provide different directions for different columns.
• Directional cursors: see above
• No default "limit": see above
• Custom transformation of the cursor: In the current package, custom transformers to stringify and parse the cursor can be provided. This feature comes from the original package (typeorm-paginator).

Contributing

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

Please try to commit your changes using a descriptive commit message.

TODOs:

• make it work with all values allowed by TypeORM's FindOptionsOrderValue type for orderBy.
• properly setup eslint and prettier
• add to README example of using CursorTransformer
• rename CursorPaginatorParams.transformer to cursorTransformer

Migration

v1 to v2

• CursorPagination type was renamed to Paginated. Example: CursorPagination<User> became Paginated<User>.

License

Released under the MIT License