feat: option to improve Date Sorting by pre-parsing date items only o…

…nce (#412)

docs/column-functionalities/sorting.md

@@ -4,6 +4,7 @@
 - [Custom Sort Comparer](#custom-sort-comparer)
 - [Update Sorting Dynamically](#update-sorting-dynamically)
 - [Dynamic Query Field](#dynamic-query-field)
+- [Pre-Parse Date Columns for better perf](#pre-parse-date-columns-for-better-perf)
 
 ### Demo
 [Demo Page](https://ghiscoding.github.io/slickgrid-react/#/slickgrid/Example4) / [Demo ViewModel](https://github.com/ghiscoding/slickgrid-react/blob/master/src/examples/slickgrid/Example4.tsx)
@@ -140,3 +141,59 @@ queryFieldNameGetterFn: (dataContext) => {
   return dataContext.profit > 0 ? 'profitRatio' : 'lossRatio';
 },
 ```
+
+### Pre-Parse Date Columns for better perf
+##### requires v5.8.0 and higher
+
+Sorting very large dataset with dates can be extremely slow when dates formated date strings, the reason is because these strings need to first be parsed and converted to real JS Dates before the Sorting process can actually happen (i.e. US Date Format). However parsing a large dataset can be slow **and** to make it worst, a Sort will revisit the same items over and over which mean that the same date strings will have to be reparsed over and over (for example while trying to Sort a dataset of 100 items, I saw some items being revisit 10 times and I can only imagine that it is exponentially worst with a large dataset).
+
+So what can we do to make this faster with a more reasonable time? Well, we can simply pre-parse all date strings once and only once and convert them to JS Date objects. Then once we get Date objects, we'll simply read the UNIX timestamp which is what we need to Sort. The first pre-parse takes a bit of time and will be executed only on the first date column Sort (any sort afterward will read the pre-parsed Date objects).
+
+What perf do we get with pre-parsing versus regular non-parsing? The benchmark was pulled using 50K items with 2 date columns (with US date format)
+- without non-parsing: ~15sec
+- with pre-parsing: ~1.4sec (1st pre-parse) and any subsequent Date sort is about ~0.2sec => so about ~1.5sec total
+
+The summary, is that we get a 10x boost **but** not only that, we also get an extremely fast subsequent sort afterward (sorting Date objects is as fast as sorting Numbers).
+
+#### Usage
+
+You can use the `preParseDateColumns` grid option, it can be either set as either `boolean` or a `string` but there's big distinction between the 2 approaches (both approaches will mutate the dataset).
+1. `string` (i.e. set to `"__"`, it will parse a `"start"` date string and assign it as a `Date` object to a new `"__start"` prop)
+2. `boolean` (i.e. parse `"start"` date string and reassign it as a `Date` object on the same `"start"` prop)
+
+> **Note** this option **does not work** with Backend Services because it simply has no effect.
+
+For example if our dataset has 2 columns named "start" and "finish", then pre-parse the dataset,
+
+with the 1nd approach (`string`), let's use `"__"` (which is in reality a prefix) it will mutate the dataset by adding new props (where `Date` is a `Date` object)
+
+```diff
+data = [
+-  { id: 0, start: '02/28/24', finish: '03/02/24' },
+-  { id: 1, start: '01/14/24', finish: '02/13/24' },
++  { id: 0, start: '02/28/24', finish: '03/02/24', __start: Date, __finish: Date },
++  { id: 1, start: '01/14/24', finish: '02/13/24', __start: Date, __finish: Date },
+]
+```
+
+with the 2nd approach (`boolean`), it will instead mutate the dataset by overwriting the same properties
+
+```diff
+data = [
+-  { id: 0, start: '02/28/24', finish: '03/02/24' },
+-  { id: 1, start: '01/14/24', finish: '02/13/24' },
++  { id: 0, start: Date, finish: Date },
++  { id: 1, start: Date, finish: Date },
+]
+```
+
+Which approach to choose? Both have pros and cons, overwriting the same props might cause problems with the column `type` that you use, you will have to give it a try yoursel. On the other hand, with the other approach, it will duplicate all date properties and take a bit more memory usage and when changing cells we'll need to make sure to keep these props in sync, however you will likely have less `type` issues.
+
+What happens when we do any cell changes (for our use case, it would be Create/Update), for any Editors we simply subscribe to the `onCellChange` change event and we re-parse the date strings when detected. We also subscribe to certain CRUD functions as long as they come from the `GridService` then all is fine... However, if you use the DataView functions directly then we have no way of knowing when to parse because these functions from the DataView don't have any events. Lastly, if we overwrite the entire dataset, we will also detect this (via an internal flag) and the next time you sort a date then the pre-parse kicks in again.
+
+#### Can I call the pre-parse myself?
+
+Yes, if for example you want to pre-parse right after the grid is loaded, you could call the pre-parse yourself for either all items or a single item
+- all item pre-parsing: `this.sgb.sortService.preParseAllDateItems();`
+  - the items will be read directly from the DataView
+- a single item parsing: `this.sgb.sortService.preParseSingleDateItem(item);`

package.json

@@ -83,11 +83,11 @@
     "/src/slickgrid-react"
   ],
   "dependencies": {
-    "@slickgrid-universal/common": "~5.7.0",
-    "@slickgrid-universal/custom-footer-component": "~5.7.0",
-    "@slickgrid-universal/empty-warning-component": "~5.7.0",
-    "@slickgrid-universal/event-pub-sub": "~5.7.0",
-    "@slickgrid-universal/pagination-component": "~5.7.0",
+    "@slickgrid-universal/common": "~5.8.0",
+    "@slickgrid-universal/custom-footer-component": "~5.8.0",
+    "@slickgrid-universal/empty-warning-component": "~5.8.0",
+    "@slickgrid-universal/event-pub-sub": "~5.8.0",
+    "@slickgrid-universal/pagination-component": "~5.8.0",
     "dequal": "^2.0.3",
     "i18next": "^23.15.1",
     "sortablejs": "^1.15.3"
@@ -99,13 +99,13 @@
     "@formkit/tempo": "^0.1.2",
     "@popperjs/core": "^2.11.8",
     "@release-it/conventional-changelog": "^8.0.2",
-    "@slickgrid-universal/composite-editor-component": "~5.7.0",
-    "@slickgrid-universal/custom-tooltip-plugin": "~5.7.0",
-    "@slickgrid-universal/excel-export": "~5.7.0",
-    "@slickgrid-universal/graphql": "~5.7.0",
-    "@slickgrid-universal/odata": "~5.7.0",
-    "@slickgrid-universal/rxjs-observable": "~5.7.0",
-    "@slickgrid-universal/text-export": "~5.7.0",
+    "@slickgrid-universal/composite-editor-component": "~5.8.0",
+    "@slickgrid-universal/custom-tooltip-plugin": "~5.8.0",
+    "@slickgrid-universal/excel-export": "~5.8.0",
+    "@slickgrid-universal/graphql": "~5.8.0",
+    "@slickgrid-universal/odata": "~5.8.0",
+    "@slickgrid-universal/rxjs-observable": "~5.8.0",
+    "@slickgrid-universal/text-export": "~5.8.0",
     "@types/dompurify": "^3.0.5",
     "@types/fnando__sparkline": "^0.3.7",
     "@types/i18next-xhr-backend": "^1.4.2",
@@ -151,7 +151,7 @@
     "promise-polyfill": "^8.3.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "react-i18next": "^15.0.1",
+    "react-i18next": "^15.0.2",
     "react-router-dom": "^6.26.2",
     "regenerator-runtime": "^0.14.1",
     "release-it": "^17.6.0",

src/examples/slickgrid/Example4.tsx

@@ -26,7 +26,7 @@ interface State extends BaseSlickGridState {
 function randomBetween(min: number, max: number) {
   return Math.floor(Math.random() * (max - min + 1) + min);
 }
-const NB_ITEMS = 1500;
+const NB_ITEMS = 5500;
 const URL_SAMPLE_COLLECTION_DATA = 'assets/data/collection_500_numbers.json';
 
 interface Props { }
@@ -233,6 +233,7 @@ export default class Example4 extends React.Component<Props, State> {
         ],
       },
       externalResources: [new ExcelExportService()],
+      preParseDateColumns: '__' // or true
     };
   }
 
@@ -248,6 +249,10 @@ export default class Example4 extends React.Component<Props, State> {
     }));
   }
 
+  logItems() {
+    console.log(this.reactGrid.dataView?.getItems());
+  }
+
   mockData(itemCount: number, startingIndex = 0): any[] {
     // mock a dataset
     const tempDataset: any[] = [];
@@ -383,6 +388,9 @@ export default class Example4 extends React.Component<Props, State> {
           onClick={() => this.setSortingDynamically()}>
           Set Sorting Dynamically
         </button>
+        <button className="btn btn-outline-secondary btn-sm btn-icon" onClick={() => this.logItems()}>
+          <span title="console.log all dataset items">Log Items</span>
+        </button>
 
         <SlickgridReact gridId="grid4"
           columnDefinitions={this.state.columnDefinitions}

src/slickgrid-react/components/slickgrid-react.tsx

@@ -49,6 +49,7 @@ import {
   // utilities
   autoAddEditorFormatterToColumnsWithEditor,
   emptyElement,
+  isColumnDateType,
 } from '@slickgrid-universal/common';
 import { EventPubSubService } from '@slickgrid-universal/event-pub-sub';
 import { SlickFooterComponent } from '@slickgrid-universal/custom-footer-component';
@@ -70,6 +71,8 @@ import type { Subscription } from 'rxjs';
 import { GlobalContainerService } from '../services/singletons';
 import type { SlickgridReactProps } from './slickgridReactProps';
 
+const WARN_NO_PREPARSE_DATE_SIZE = 5000; // data size to warn user when pre-parse isn't enabled
+
 interface State {
   showPagination: boolean;
   _gridOptions: GridOption;
@@ -273,7 +276,7 @@ export class SlickgridReact<TData = any> extends React.Component<SlickgridReactP
     this.filterFactory = new FilterFactory(slickgridConfig, this.props.translaterService, this.collectionService);
     this.filterService = new FilterService(this.filterFactory as any, this._eventPubSubService, this.sharedService, this.backendUtilityService);
     this.resizerService = new ResizerService(this._eventPubSubService);
-    this.sortService = new SortService(this.sharedService, this._eventPubSubService, this.backendUtilityService);
+    this.sortService = new SortService(this.collectionService, this.sharedService, this._eventPubSubService, this.backendUtilityService);
     this.treeDataService = new TreeDataService(this._eventPubSubService, this.sharedService, this.sortService);
     this.paginationService = new PaginationService(this._eventPubSubService, this.sharedService, this.backendUtilityService);
 
@@ -402,6 +405,8 @@ export class SlickgridReact<TData = any> extends React.Component<SlickgridReactP
     if (this.gridOptions.darkMode) {
       this.setDarkMode(true);
     }
+
+    this.suggestDateParsingWhenHelpful();
   }
 
   initialization(eventHandler: SlickEventHandler) {
@@ -709,6 +714,7 @@ export class SlickgridReact<TData = any> extends React.Component<SlickgridReactP
     if (this.props.datasetHierarchical && this.props.datasetHierarchical !== prevProps.datasetHierarchical) {
       this.datasetHierarchical = this.props.datasetHierarchical;
     }
+    this.suggestDateParsingWhenHelpful();
   }
 
   columnDefinitionsChanged() {
@@ -825,6 +831,7 @@ export class SlickgridReact<TData = any> extends React.Component<SlickgridReactP
           this.handleOnItemCountChanged(dataView.getFilteredItemCount() || 0, dataView.getItemCount() || 0);
         });
         this._eventHandler.subscribe(dataView.onSetItemsCalled, (_e, args) => {
+          this.sharedService.isItemsDateParsed = false;
           this.handleOnItemCountChanged(dataView.getFilteredItemCount() || 0, args.itemCount);
 
           // when user has resize by content enabled, we'll force a full width calculation since we change our entire dataset
@@ -1556,6 +1563,15 @@ export class SlickgridReact<TData = any> extends React.Component<SlickgridReactP
     });
   }
 
+  protected suggestDateParsingWhenHelpful() {
+    if (this.dataView?.getItemCount() > WARN_NO_PREPARSE_DATE_SIZE && !this.gridOptions.preParseDateColumns && this.grid.getColumns().some(c => isColumnDateType(c.type))) {
+      console.warn(
+        '[Slickgrid-Universal] For getting better perf, we suggest you enable the `preParseDateColumns` grid option, ' +
+        'for more info visit:: https://ghiscoding.gitbook.io/slickgrid-universal/column-functionalities/sorting#pre-parse-date-columns-for-better-perf'
+      );
+    }
+  }
+
   /**
    * When the Editor(s) has a "editor.collection" property, we'll load the async collection.
    * Since this is called after the async call resolves, the pointer will not be the same as the "column" argument passed.

test/cypress/e2e/example04.cy.ts

@@ -56,13 +56,13 @@ describe('Example 4 - Client Side Sort/Filter Grid', () => {
         });
     });
 
-    it('should have some metrics shown in the grid footer well below 1500 items', () => {
+    it('should have some metrics shown in the grid footer well below 5500 items', () => {
       cy.get('#slickGridContainer-grid4')
         .find('.slick-custom-footer')
         .find('.right-footer')
         .should($span => {
           const text = removeExtraSpaces($span.text()); // remove all white spaces
-          expect(text).not.to.eq('1500 of 1500 items');
+          expect(text).not.to.eq('5500 of 5500 items');
         });
     });
 
@@ -171,7 +171,7 @@ describe('Example 4 - Client Side Sort/Filter Grid', () => {
         .find('.right-footer')
         .should($span => {
           const text = removeExtraSpaces($span.text()); // remove all white spaces
-          expect(text).to.eq('1500 of 1500 items');
+          expect(text).to.eq('5500 of 5500 items');
         });
     });