feat: add makeNumberCompareFn

src/array.test.ts

@@ -11,6 +11,7 @@ import {
   sortByArray,
   toggleElement,
   withoutIndex,
+  makeNumberCompareFn,
 } from './array';
 import { Maybe } from './types';
 
@@ -229,6 +230,59 @@ describe('makeStringCompareFn', () => {
   });
 });
 
+describe('makeNumberCompareFn', () => {
+  type MaybeKeyNumber = { key?: Maybe<number> };
+
+  it('creates a compare function that sorts numbers', () => {
+    const compareFn = makeNumberCompareFn<MaybeKeyNumber>(
+      (record) => record.key,
+    );
+    const original: Array<MaybeKeyNumber> = [
+      { key: 3 },
+      { key: 0 },
+      { key: undefined },
+      { key: 1 },
+      { key: null },
+      { key: 2 },
+      {},
+    ];
+    expect(original.sort(compareFn)).toEqual([
+      { key: 0 },
+      { key: undefined },
+      { key: null },
+      {},
+      { key: 1 },
+      { key: 2 },
+      { key: 3 },
+    ]);
+  });
+
+  it('accepts different fallback values', () => {
+    const compareFn = makeNumberCompareFn<MaybeKeyNumber>(
+      (record) => record.key,
+      9001,
+    );
+    const original: Array<MaybeKeyNumber> = [
+      { key: 3 },
+      { key: 0 },
+      { key: undefined },
+      { key: 1 },
+      { key: null },
+      { key: 2 },
+      {},
+    ];
+    expect(original.sort(compareFn)).toEqual([
+      { key: 0 },
+      { key: 1 },
+      { key: 2 },
+      { key: 3 },
+      { key: undefined },
+      { key: null },
+      {},
+    ]);
+  });
+});
+
 describe('localeCompareStrings', () => {
   it('sorts strings', () => {
     const original: Array<string> = ['c', '', 'a', 'b'];

src/array.ts

@@ -93,7 +93,7 @@ export function sortByArray<T extends string | number>(
 }
 
 /**
- * Takes a function that maps the values to sort and returns a compare function
+ * Takes a function that maps the values to sort to strings and returns a compare function
  * using `String.prototype.localeCompare`, usable in `Array.toSorted` or similar APIs.
  *
  * null, undefined and the empty string are not distinguished and first in sort order.
@@ -109,6 +109,24 @@ export function makeStringCompareFn<TSortable>(
   };
 }
 
+/**
+ * Takes a function that maps the values to sort to numbers and returns a compare function
+ * using subtraction, usable in `Array.toSorted` or similar APIs.
+ *
+ * null and undefined are coalesced to `fallbackValue`, by default 0, and thus not distinguished and first in sort order.
+ */
+export function makeNumberCompareFn<TSortable>(
+  map: (sortable: TSortable) => Maybe<number>,
+  fallbackValue: number = 0,
+): (a: TSortable, b: TSortable) => number {
+  return (a, b) => {
+    const mappedA = map(a) ?? fallbackValue;
+    const mappedB = map(b) ?? fallbackValue;
+
+    return mappedA - mappedB;
+  };
+}
+
 /**
  * Returns a compare function for values that are string, null or undefined,
  * using `String.prototype.localeCompare`, usable in `Array.toSorted` or similar APIs.