feat: add cursor pagination (#1050)

Author: smileeunsong

README.md

@@ -17,6 +17,7 @@ Pagination and filtering helper method for TypeORM repositories or query builder
 - Filter using operators (`$eq`, `$not`, `$null`, `$in`, `$gt`, `$gte`, `$lt`, `$lte`, `$btw`, `$ilike`, `$sw`, `$contains`)
 - Include relations and nested relations
 - Virtual column support
+- Cursor-based pagination
 
 ## Installation
 
@@ -93,6 +94,61 @@ http://localhost:3000/cats?limit=5&page=2&sortBy=color:DESC&search=i&filter.age=
 }
 ```
 
+### Example (Cursor-based Pagination)
+
+The following code exposes a route using cursor-based pagination:
+
+#### Endpoint
+
+```url
+http://localhost:3000/cats?limit=5&cursor=2022-12-20T10:00:00.000Z&cursorColumn=lastVetVisit&cursorDirection=after
+```
+
+#### Result
+
+```json
+{
+  "data": [
+    {
+      "id": 3,
+      "name": "Shadow",
+      "lastVetVisit": "2022-12-21T10:00:00.000Z"
+    },
+    {
+      "id": 4,
+      "name": "Luna",
+      "lastVetVisit": "2022-12-22T10:00:00.000Z"
+    },
+    {
+      "id": 5,
+      "name": "Pepper",
+      "lastVetVisit": "2022-12-23T10:00:00.000Z"
+    },
+    {
+      "id": 6,
+      "name": "Simba",
+      "lastVetVisit": "2022-12-24T10:00:00.000Z"
+    },
+    {
+      "id": 7,
+      "name": "Tiger",
+      "lastVetVisit": "2022-12-25T10:00:00.000Z"
+    }
+  ],
+  "meta": {
+    "itemsPerPage": 5,
+    "cursor": "2022-12-20T10:00:00.000Z",
+    "firstCursor": "2022-12-21T10:00:00.000Z",
+    "lastCursor": "2022-12-25T10:00:00.000Z"
+  },
+  "links": {
+    "previous": "http://localhost:3000/cats?limit=5&sortBy=lastVetVisit:ASC&cursor=2022-12-21T10:00:00.000Z&cursorColumn=lastVetVisit&cursorDirection=before",
+    "current": "http://localhost:3000/cats?limit=5&sortBy=lastVetVisit:ASC&cursor=2022-12-20T10:00:00.000Z&cursorColumn=lastVetVisit&cursorDirection=after",
+    "next": "http://localhost:3000/cats?limit=5&sortBy=lastVetVisit:ASC&cursor=2022-12-25T10:00:00.000Z&cursorColumn=lastVetVisit&cursorDirection=after"
+  }
+}
+```
+
 #### Code
 
 ```ts
@@ -232,6 +288,17 @@ const paginateConfig: PaginateConfig<CatEntity> {
    */
   filterableColumns: { age: [FilterOperator.EQ, FilterOperator.IN] },
 
+  /**
+   * Required: false
+   * Type: (keyof CatEntity)[]
+   * Default: None
+   * Description: Columns that can be used as cursors for cursor-based pagination.
+   * Typically used with date or unique & sequential columns like 'lastVetVisit' or 'id'.
+   * If `cursorColumn` is not provided in the query, the first column in this array is used as the default.
+   * If `cursorDirection` is not provided in the query, 'before' is used as the default direction.
+   */
+  cursorableColumns: ['lastVetVisit'],
+
   /**
    * Required: false
    * Type: RelationColumn<CatEntity>
@@ -259,8 +326,10 @@ const paginateConfig: PaginateConfig<CatEntity> {
   /**
    * Required: false
    * Type: string
-   * Description: Allow user to choose between limit/offset and take/skip.
+   * Description: Allow user to choose between limit/offset and take/skip, or cursor-based pagination.
    * Default: PaginationType.TAKE_AND_SKIP
+   * Options: PaginationType.LIMIT_AND_OFFSET, PaginationType.TAKE_AND_SKIP, PaginationType.CURSOR
+   * Note: CURSOR requires `cursorableColumns` to be defined.
    *
    * However, using limit/offset can cause problems with relations.
    */

src/__tests__/cat.entity.ts

@@ -11,8 +11,8 @@ import {
     OneToOne,
     PrimaryGeneratedColumn,
 } from 'typeorm'
-import { CatToyEntity } from './cat-toy.entity'
 import { CatHomeEntity } from './cat-home.entity'
+import { CatToyEntity } from './cat-toy.entity'
 import { SizeEmbed } from './size.embed'
 
 export enum CutenessLevel {

src/decorator.spec.ts

@@ -108,6 +108,9 @@ describe('Decorator', () => {
             searchBy: undefined,
             filter: undefined,
             select: undefined,
+            cursor: undefined,
+            cursorColumn: undefined,
+            cursorDirection: undefined,
             path: 'http://localhost/items',
         })
     })
@@ -125,6 +128,9 @@ describe('Decorator', () => {
             searchBy: undefined,
             filter: undefined,
             select: undefined,
+            cursor: undefined,
+            cursorColumn: undefined,
+            cursorDirection: undefined,
             path: 'http://localhost/items',
         })
     })
@@ -138,6 +144,9 @@ describe('Decorator', () => {
             'filter.name': '$not:$eq:Kitty',
             'filter.createdAt': ['$gte:2020-01-01', '$lte:2020-12-31'],
             select: ['name', 'createdAt'],
+            cursor: 'abc123',
+            cursorColumn: 'id',
+            cursorDirection: 'after',
         })
 
         const result: PaginateQuery = decoratorfactory(null, context)
@@ -157,6 +166,9 @@ describe('Decorator', () => {
                 name: '$not:$eq:Kitty',
                 createdAt: ['$gte:2020-01-01', '$lte:2020-12-31'],
             },
+            cursor: 'abc123',
+            cursorColumn: 'id',
+            cursorDirection: 'after',
         })
     })
 
@@ -169,6 +181,9 @@ describe('Decorator', () => {
             'filter.name': '$not:$eq:Kitty',
             'filter.createdAt': ['$gte:2020-01-01', '$lte:2020-12-31'],
             select: ['name', 'createdAt'],
+            cursor: 'abc123',
+            cursorColumn: 'id',
+            cursorDirection: 'after',
         })
 
         const result: PaginateQuery = decoratorfactory(null, context)
@@ -188,6 +203,9 @@ describe('Decorator', () => {
                 createdAt: ['$gte:2020-01-01', '$lte:2020-12-31'],
             },
             select: ['name', 'createdAt'],
+            cursor: 'abc123',
+            cursorColumn: 'id',
+            cursorDirection: 'after',
         })
     })
 })

src/decorator.ts

@@ -19,6 +19,9 @@ export interface PaginateQuery {
     search?: string
     filter?: { [column: string]: string | string[] }
     select?: string[]
+    cursor?: string
+    cursorColumn?: string
+    cursorDirection?: 'before' | 'after'
     path: string
 }
 
@@ -101,6 +104,10 @@ export const Paginate = createParamDecorator((_data: unknown, ctx: ExecutionCont
         searchBy,
         filter: Object.keys(filter).length ? filter : undefined,
         select,
+        cursor: query.cursor ? query.cursor.toString() : undefined,
+        cursorColumn: query.cursorColumn ? query.cursorColumn.toString() : undefined,
+        cursorDirection:
+            query.cursorDirection === 'after' || query.cursorDirection === 'before' ? query.cursorDirection : undefined,
         path,
     }
 })