feat: add makeDateCompareFn

Author: spawnia

src/array.test.ts

@@ -12,6 +12,7 @@ import {
   toggleElement,
   withoutIndex,
   makeNumberCompareFn,
+  makeDateCompareFn,
 } from './array';
 import { Maybe } from './types';
 
@@ -283,6 +284,28 @@ describe('makeNumberCompareFn', () => {
   });
 });
 
+describe('makeDateCompareFn', () => {
+  it('sorts objects by date property', () => {
+    const arr = [
+      { name: 'b', date: new Date('2022-01-02') },
+      { name: 'a', date: new Date('2022-01-01') },
+      { name: 'c', date: new Date('2022-01-03') },
+    ];
+    const sorted = arr.sort(makeDateCompareFn((x) => x.date));
+    expect(sorted.map((x) => x.name)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('handles null/undefined dates', () => {
+    const arr = [
+      { name: 'a', date: undefined },
+      { name: 'b', date: new Date('2022-01-01') },
+      { name: 'c', date: null },
+    ];
+    const sorted = arr.sort(makeDateCompareFn((x) => x.date));
+    expect(sorted.map((x) => x.name)).toEqual(['a', 'c', 'b']);
+  });
+});
+
 describe('localeCompareStrings', () => {
   it('sorts strings', () => {
     const original: Array<string> = ['c', '', 'a', 'b'];

src/array.ts

@@ -127,6 +127,18 @@ export function makeNumberCompareFn<TSortable>(
   };
 }
 
+/**
+ * Takes a function that maps the values to sort to Dates and returns a compare function
+ * using their timestamps, usable in `Array.toSorted` or similar APIs.
+ *
+ * null and undefined are coalesced to 0 and thus not distinguished and first in sort order.
+ */
+export function makeDateCompareFn<TSortable>(
+  map: (sortable: TSortable) => Maybe<Date>,
+): (a: TSortable, b: TSortable) => number {
+  return makeNumberCompareFn((sortable) => map(sortable)?.getTime());
+}
+
 /**
  * Returns a compare function for values that are string, null or undefined,
  * using `String.prototype.localeCompare`, usable in `Array.toSorted` or similar APIs.