feat(graphql): add optional cursor pagination to GraphQL backend service

packages/common/src/interfaces/backendService.interface.ts

@@ -8,6 +8,7 @@ import type {
   MultiColumnSort,
   Pagination,
   PaginationChangedArgs,
+  PaginationCursorChangedArgs,
   SingleColumnSort,
 } from './index';
 import { SlickGrid } from './slickGrid.interface';
@@ -50,8 +51,8 @@ export interface BackendService {
   /** Update the Filters options with a set of new options */
   updateFilters?: (columnFilters: ColumnFilters | CurrentFilter[], isUpdatedByPresetOrDynamically: boolean) => void;
 
-  /** Update the Pagination component with it's new page number and size */
-  updatePagination?: (newPage: number, pageSize: number) => void;
+  /** Update the Pagination component with it's new page number and size. If using cursor based pagination, a CursorPageInfo object needs to be supplied */
+  updatePagination?: (newPage: number, pageSize: number, cursorArgs?: PaginationCursorChangedArgs) => void;
 
   /** Update the Sorters options with a set of new options */
   updateSorters?: (sortColumns?: Array<SingleColumnSort>, presetSorters?: CurrentSorter[]) => void;
@@ -67,7 +68,7 @@ export interface BackendService {
   processOnFilterChanged: (event: Event | KeyboardEvent | undefined, args: FilterChangedArgs) => string;
 
   /** Execute when the pagination changed */
-  processOnPaginationChanged: (event: Event | undefined, args: PaginationChangedArgs) => string;
+  processOnPaginationChanged: (event: Event | undefined, args: PaginationChangedArgs | (PaginationCursorChangedArgs & PaginationChangedArgs)) => string;
 
   /** Execute when any of the sorters changed */
   processOnSortChanged: (event: Event | undefined, args: SingleColumnSort | MultiColumnSort) => string;

packages/common/src/interfaces/cursorPageInfo.interface.ts

@@ -0,0 +1,13 @@
+export interface CursorPageInfo {
+  /** Do we have a next page from current cursor position? */
+  hasNextPage: boolean;
+
+  /** Do we have a previous page from current cursor position? */
+  hasPreviousPage: boolean;
+
+  /** What is the last cursor? */
+  endCursor: string;
+
+  /** What is the first cursor? */
+  startCursor: string;
+}

packages/common/src/interfaces/index.ts

@@ -36,6 +36,7 @@ export * from './currentPagination.interface';
 export * from './currentPinning.interface';
 export * from './currentRowSelection.interface';
 export * from './currentSorter.interface';
+export * from './cursorPageInfo.interface';
 export * from './customFooterOption.interface';
 export * from './customTooltipOption.interface';
 export * from './dataViewOption.interface';
@@ -120,6 +121,7 @@ export * from './onValidationErrorResult.interface';
 export * from './operatorDetail.interface';
 export * from './pagination.interface';
 export * from './paginationChangedArgs.interface';
+export * from './paginationCursorChangedArgs.interface';
 export * from './pagingInfo.interface';
 export * from './resizeByContentOption.interface';
 export * from './resizer.interface';

packages/common/src/interfaces/paginationCursorChangedArgs.interface.ts

@@ -0,0 +1,15 @@
+import type { PaginationChangedArgs } from './paginationChangedArgs.interface';
+
+export interface PaginationCursorChangedArgs extends PaginationChangedArgs {
+  /** Start our page After cursor X */
+  after?: string;
+
+  /** Start our page Before cursor X */
+  before?: string;
+
+  /** Get first X number of objects */
+  first?: number;
+
+  /** Get last X number of objects */
+  last?: number;
+}

packages/common/src/services/__tests__/pagination.service.spec.ts

@@ -2,7 +2,7 @@ import { of, throwError } from 'rxjs';
 
 import { PaginationService } from './../pagination.service';
 import { SharedService } from '../shared.service';
-import { Column, SlickDataView, GridOption, SlickGrid, SlickNamespace, BackendServiceApi, Pagination } from '../../interfaces/index';
+import { Column, CursorPageInfo, SlickDataView, GridOption, SlickGrid, SlickNamespace, BackendServiceApi, Pagination } from '../../interfaces/index';
 import { BackendUtilityService } from '../backendUtility.service';
 import { RxJsResourceStub } from '../../../../../test/rxjsResourceStub';
 
@@ -61,6 +61,23 @@ const mockGridOption = {
   }
 } as GridOption;
 
+const mockGridOptionWithCursorPaginationBackend = {
+  ...mockGridOption,
+  backendServiceApi: {
+    service: mockBackendService,
+    process: jest.fn(),
+    options: {
+      columnDefinitions: [{ id: 'name', field: 'name' }] as Column[],
+      datasetName: 'user',
+      isWithCursor: true,
+    }
+  },
+} as GridOption;
+
+const mockCursorPageInfo = {
+  startCursor: "b", endCursor: "c", hasNextPage: true, hasPreviousPage: true, // b-c simulates page 2
+} as CursorPageInfo;
+
 const gridStub = {
   autosizeColumns: jest.fn(),
   getColumnIndex: jest.fn(),
@@ -206,6 +223,27 @@ describe('PaginationService', () => {
       expect(service.getCurrentPageNumber()).toBe(1);
       expect(spy).toHaveBeenCalledWith(1, undefined);
     });
+
+    it('should expect current page to be 1 and "processOnPageChanged" method to be called with cursorArgs when backend service is cursor based', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+      service.setCursorPageInfo(mockCursorPageInfo);
+      service.goToFirstPage();
+
+      expect(service.dataFrom).toBe(1);
+      expect(service.dataTo).toBe(25);
+      expect(service.getCurrentPageNumber()).toBe(1);
+      expect(spy).toHaveBeenCalledWith(1, undefined, { first: 25, newPage: 1, pageSize: 25 });
+    });
+
+    it('should expect current page to be 1 and "processOnPageChanged" method NOT to be called', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+      service.init(gridStub, mockGridOption.pagination as Pagination, mockGridOption.backendServiceApi);
+      service.goToFirstPage(null, false);
+
+      expect(service.getCurrentPageNumber()).toBe(1);
+      expect(spy).not.toHaveBeenCalled();
+    });
   });
 
   describe('goToLastPage method', () => {
@@ -220,6 +258,29 @@ describe('PaginationService', () => {
       expect(service.getCurrentPageNumber()).toBe(4);
       expect(spy).toHaveBeenCalledWith(4, undefined);
     });
+
+    it('should call "goToLastPage" method and expect current page to be last page and "processOnPageChanged" method to be called with cursorArgs when backend service is cursor based', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+      service.setCursorPageInfo(mockCursorPageInfo);
+      service.goToLastPage();
+
+      expect(service.dataFrom).toBe(76);
+      expect(service.dataTo).toBe(85);
+      expect(service.getCurrentPageNumber()).toBe(4);
+      expect(spy).toHaveBeenCalledWith(4, undefined, { last: 25, newPage: 4, pageSize: 25 });
+    });
+
+    it('should call "goToLastPage" method and expect current page to be last page and "processOnPageChanged" method NOT to be called', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+
+      service.init(gridStub, mockGridOption.pagination as Pagination, mockGridOption.backendServiceApi);
+      service.goToLastPage(null, false);
+
+      expect(service.getCurrentPageNumber()).toBe(4);
+      expect(spy).not.toHaveBeenCalledWith();
+    });
   });
 
   describe('goToNextPage method', () => {
@@ -235,16 +296,27 @@ describe('PaginationService', () => {
       expect(spy).toHaveBeenCalledWith(3, undefined);
     });
 
-    it('should expect page to increment by 1 and "processOnPageChanged" method to be called', () => {
+    it('should expect page to increment by 1 and "processOnPageChanged" method to be called with cursorArgs when backend service is cursor based', () => {
       const spy = jest.spyOn(service, 'processOnPageChanged');
 
-      service.init(gridStub, mockGridOption.pagination as Pagination, mockGridOption.backendServiceApi);
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+      service.setCursorPageInfo(mockCursorPageInfo);
       service.goToNextPage();
 
       expect(service.dataFrom).toBe(51);
       expect(service.dataTo).toBe(75);
       expect(service.getCurrentPageNumber()).toBe(3);
-      expect(spy).toHaveBeenCalledWith(3, undefined);
+      expect(spy).toHaveBeenCalledWith(3, undefined, {first: 25, after: "c", newPage: 3, pageSize: 25 });
+    });
+
+    it('should expect page to increment by 1 and "processOnPageChanged" method NOT to be called', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+
+      service.init(gridStub, mockGridOption.pagination as Pagination, mockGridOption.backendServiceApi);
+      service.goToNextPage(null, false);
+
+      expect(service.getCurrentPageNumber()).toBe(3);
+      expect(spy).not.toHaveBeenCalled();
     });
 
     it('should not expect "processOnPageChanged" method to be called when we are already on last page', () => {
@@ -274,6 +346,29 @@ describe('PaginationService', () => {
       expect(spy).toHaveBeenCalledWith(1, undefined);
     });
 
+    it('should expect page to decrement by 1 and "processOnPageChanged" method to be called  with cursorArgs when backend service is cursor based', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+      service.setCursorPageInfo(mockCursorPageInfo);
+      service.goToPreviousPage();
+
+      expect(service.dataFrom).toBe(1);
+      expect(service.dataTo).toBe(25);
+      expect(service.getCurrentPageNumber()).toBe(1);
+      expect(spy).toHaveBeenCalledWith(1, undefined, {last: 25, before: "b", newPage: 1, pageSize: 25 });
+    });
+
+    it('should expect page to decrement by 1 and "processOnPageChanged" method NOT to be called', () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+      service.goToPreviousPage(null, false);
+
+      expect(service.getCurrentPageNumber()).toBe(1);
+      expect(spy).not.toHaveBeenCalled()
+    });
+
     it('should not expect "processOnPageChanged" method to be called when we are already on first page', () => {
       const spy = jest.spyOn(service, 'processOnPageChanged');
       mockGridOption.pagination!.pageNumber = 1;
@@ -338,6 +433,21 @@ describe('PaginationService', () => {
       expect(spy).not.toHaveBeenCalled();
       expect(output).toBeFalsy();
     });
+
+    it('should not expect "processOnPageChanged" method to be called when backend service is cursor based', async () => {
+      const spy = jest.spyOn(service, 'processOnPageChanged');
+      service.setCursorPageInfo(mockCursorPageInfo);
+      service.init(gridStub, mockGridOptionWithCursorPaginationBackend.pagination as Pagination, mockGridOptionWithCursorPaginationBackend.backendServiceApi);
+
+      const output = await service.goToPageNumber(3);
+
+      // stay on current page
+      expect(service.dataFrom).toBe(26);
+      expect(service.dataTo).toBe(50);
+      expect(service.getCurrentPageNumber()).toBe(2);
+      expect(spy).not.toHaveBeenCalled();
+      expect(output).toBeFalsy();
+    });
   });
 
   describe('processOnPageChanged method', () => {

packages/common/src/services/pagination.service.ts

@@ -4,7 +4,9 @@ import { dequal } from 'dequal/lite';
 import type {
   BackendServiceApi,
   CurrentPagination,
+  CursorPageInfo,
   Pagination,
+  PaginationCursorChangedArgs,
   ServicePagination,
   SlickDataView,
   SlickGrid,
@@ -32,6 +34,7 @@ export class PaginationService {
   protected _paginationOptions!: Pagination;
   protected _previousPagination?: Pagination;
   protected _subscriptions: EventSubscription[] = [];
+  protected _cursorPageInfo?: CursorPageInfo;
 
   /** SlickGrid Grid object */
   grid!: SlickGrid;
@@ -86,6 +89,27 @@ export class PaginationService {
     }
   }
 
+  /**
+   * https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89
+   * Cursor based pagination does not allow navigation to a page in the middle of a set of pages (eg: LinkedList vs Vector).
+   *  Further, Pagination with page numbers only makes sense in non-relay style pagination
+   *  Relay style pagination is better suited to infinite scrolling
+   *
+   * eg
+   *  relay pagination - Infinte scrolling appending data
+   *    page1: {startCursor: A, endCursor: B }
+   *    page2: {startCursor: A, endCursor: C }
+   *    page3: {startCursor: A, endCursor: D }
+   *
+   *  non-relay pagination - Getting page chunks
+   *    page1: {startCursor: A, endCursor: B }
+   *    page2: {startCursor: B, endCursor: C }
+   *    page3: {startCursor: C, endCursor: D }
+   */
+  get isCursorBased(): boolean {
+    return !!this._backendServiceApi?.options.isWithCursor;
+  }
+
   addRxJsResource(rxjs: RxJsFacade) {
     this.rxjs = rxjs;
   }
@@ -184,23 +208,44 @@ export class PaginationService {
 
   goToFirstPage(event?: any, triggerChangeEvent = true): Promise<ServicePagination> {
     this._pageNumber = 1;
-    return triggerChangeEvent ? this.processOnPageChanged(this._pageNumber, event) : Promise.resolve(this.getFullPagination());
+    if (triggerChangeEvent) {
+      return this.isCursorBased && this._cursorPageInfo
+        ? this.processOnPageChanged(this._pageNumber, event, { newPage: this._pageNumber, pageSize: this._itemsPerPage, first: this._itemsPerPage })
+        : this.processOnPageChanged(this._pageNumber, event);
+    }
+    return Promise.resolve(this.getFullPagination());
   }
 
   goToLastPage(event?: any, triggerChangeEvent = true): Promise<ServicePagination> {
     this._pageNumber = this._pageCount || 1;
-    return triggerChangeEvent ? this.processOnPageChanged(this._pageNumber || 1, event) : Promise.resolve(this.getFullPagination());
+    if (triggerChangeEvent) {
+      return this.isCursorBased && this._cursorPageInfo
+        ? this.processOnPageChanged(this._pageNumber, event, { newPage: this._pageNumber, pageSize: this._itemsPerPage, last: this._itemsPerPage })
+        : this.processOnPageChanged(this._pageNumber, event);
+    }
+    return Promise.resolve(this.getFullPagination());
   }
 
   goToNextPage(event?: any, triggerChangeEvent = true): Promise<boolean | ServicePagination> {
     if (this._pageNumber < this._pageCount) {
       this._pageNumber++;
-      return triggerChangeEvent ? this.processOnPageChanged(this._pageNumber, event) : Promise.resolve(this.getFullPagination());
+      if (triggerChangeEvent) {
+        return this.isCursorBased && this._cursorPageInfo
+          ? this.processOnPageChanged(this._pageNumber, event, { newPage: this._pageNumber, pageSize: this._itemsPerPage, first: this._itemsPerPage, after: this._cursorPageInfo.endCursor })
+          : this.processOnPageChanged(this._pageNumber, event);
+      } else {
+        return Promise.resolve(this.getFullPagination());
+      }
     }
     return Promise.resolve(false);
   }
 
   goToPageNumber(pageNumber: number, event?: any, triggerChangeEvent = true): Promise<boolean | ServicePagination> {
+    if (this.isCursorBased) {
+      console.assert(true, 'Cursor based navigation cannot navigate to arbitrary page');
+      return Promise.resolve(false);
+    }
+
     const previousPageNumber = this._pageNumber;
 
     if (pageNumber < 1) {
@@ -220,7 +265,13 @@ export class PaginationService {
   goToPreviousPage(event?: any, triggerChangeEvent = true): Promise<boolean | ServicePagination> {
     if (this._pageNumber > 1) {
       this._pageNumber--;
-      return triggerChangeEvent ? this.processOnPageChanged(this._pageNumber, event) : Promise.resolve(this.getFullPagination());
+      if (triggerChangeEvent) {
+        return this.isCursorBased && this._cursorPageInfo
+          ? this.processOnPageChanged(this._pageNumber, event, { newPage: this._pageNumber, pageSize: this._itemsPerPage, last: this._itemsPerPage, before: this._cursorPageInfo.startCursor })
+          : this.processOnPageChanged(this._pageNumber, event);
+      } else {
+        return Promise.resolve(this.getFullPagination());
+      }
     }
     return Promise.resolve(false);
   }
@@ -321,7 +372,9 @@ export class PaginationService {
     }
   }
 
-  processOnPageChanged(pageNumber: number, event?: Event | undefined): Promise<ServicePagination> {
+  processOnPageChanged(pageNumber: number, event?: Event | undefined, cursorArgs?: PaginationCursorChangedArgs): Promise<ServicePagination> {
+    console.assert(!this.isCursorBased || cursorArgs, 'Configured for cursor based pagination - cursorArgs expected');
+
     if (this.pubSubService.publish('onBeforePaginationChange', this.getFullPagination()) === false) {
       this.resetToPreviousPagination();
       return Promise.resolve(this.getFullPagination());
@@ -347,7 +400,9 @@ export class PaginationService {
         }
 
         if (this._backendServiceApi?.process) {
-          const query = this._backendServiceApi.service.processOnPaginationChanged(event, { newPage: pageNumber, pageSize: itemsPerPage });
+          const query = this.isCursorBased && cursorArgs
+            ? this._backendServiceApi.service.processOnPaginationChanged(event, cursorArgs)
+            : this._backendServiceApi.service.processOnPaginationChanged(event, { newPage: pageNumber, pageSize: itemsPerPage });
 
           // the processes can be Promises
           const process = this._backendServiceApi.process(query);
@@ -437,6 +492,10 @@ export class PaginationService {
     }
   }
 
+  setCursorPageInfo(pageInfo: CursorPageInfo) {
+    this._cursorPageInfo = pageInfo;
+  }
+
   updateTotalItems(totalItems: number, triggerChangedEvent = false) {
     this._totalItems = totalItems;
     if (this._paginationOptions) {