Introduce Comparator and PairSorting (#1937)

Co-authored-by: Julien Deniau <julien@deniau.me>

__tests__/Comparator.ts

@@ -0,0 +1,66 @@
+import { List, OrderedSet, Seq, Comparator, PairSorting } from 'immutable';
+
+const sourceNumbers: readonly number[] = [3, 4, 5, 6, 7, 9, 10, 12, 90, 92, 95];
+
+const expectedSortedNumbers: readonly number[] = [
+  7, 95, 90, 92, 3, 5, 9, 4, 6, 10, 12,
+];
+
+const testComparator: Comparator<number> = (left, right) => {
+  //The number 7 always goes first...
+  if (left == 7) {
+    return PairSorting.LeftThenRight;
+  } else if (right == 7) {
+    return PairSorting.RightThenLeft;
+  }
+
+  //...followed by numbers >= 90, then by all the others.
+  if (left >= 90 && right < 90) {
+    return PairSorting.LeftThenRight;
+  } else if (left < 90 && right >= 90) {
+    return PairSorting.RightThenLeft;
+  }
+
+  //Within each group, even numbers go first...
+  if (left % 2 && !(right % 2)) {
+    return PairSorting.LeftThenRight;
+  } else if (!(left % 2) && right % 2) {
+    return PairSorting.RightThenLeft;
+  }
+
+  //...and, finally, sort the numbers of each subgroup in ascending order.
+  return left - right;
+};
+
+describe.each([
+  ['List', List],
+  ['OrderedSet', OrderedSet],
+  ['Seq.Indexed', Seq.Indexed],
+])('Comparator applied to %s', (_collectionName, testCollectionConstructor) => {
+  const sourceCollection = testCollectionConstructor(sourceNumbers);
+
+  const expectedSortedCollection = testCollectionConstructor(
+    expectedSortedNumbers
+  );
+
+  describe('when sorting', () => {
+    it('should support the enum as well as numeric return values', () => {
+      const actualCollection = sourceCollection.sort(testComparator);
+      expect(actualCollection).toEqual(expectedSortedCollection);
+    });
+  });
+
+  describe('when retrieving the max value', () => {
+    it('should support the enum as well as numeric return values', () => {
+      const actualMax = sourceCollection.max(testComparator);
+      expect(actualMax).toBe(12);
+    });
+  });
+
+  describe('when retrieving the min value', () => {
+    it('should support the enum as well as numeric return values', () => {
+      const actualMin = sourceCollection.min(testComparator);
+      expect(actualMin).toBe(7);
+    });
+  });
+});

src/Immutable.js

@@ -4,6 +4,7 @@ import { List } from './List';
 import { Map } from './Map';
 import { Stack } from './Stack';
 import { OrderedSet } from './OrderedSet';
+import { PairSorting } from './PairSorting';
 import { Set } from './Set';
 import { Record } from './Record';
 import { Range } from './Range';
@@ -62,6 +63,7 @@ export default {
   Stack: Stack,
   Set: Set,
   OrderedSet: OrderedSet,
+  PairSorting: PairSorting,
 
   Record: Record,
   Range: Range,
@@ -118,6 +120,7 @@ export {
   Stack,
   Set,
   OrderedSet,
+  PairSorting,
   Record,
   Range,
   Repeat,

src/PairSorting.js

@@ -0,0 +1,4 @@
+export const PairSorting = {
+  LeftThenRight: -1,
+  RightThenLeft: +1,
+};

type-definitions/immutable.d.ts

@@ -125,6 +125,27 @@ declare namespace Immutable {
     : // other case : should be kept as is
       T;
 
+  /**
+   * Describes which item in a pair should be placed first when sorting
+   *
+   * @ignore
+   */
+  export enum PairSorting {
+    LeftThenRight = -1,
+    RightThenLeft = +1,
+  }
+
+  /**
+   * Function comparing two items of the same type. It can return:
+   *
+   * * a PairSorting value, to indicate whether the left-hand item or the right-hand item should be placed before the other
+   *
+   * * the traditional numeric return value - especially -1, 0, or 1
+   *
+   * @ignore
+   */
+  export type Comparator<T> = (left: T, right: T) => PairSorting | number;
+
   /**
    * Lists are ordered indexed dense collections, much like a JavaScript
    * Array.
@@ -4526,6 +4547,7 @@ declare namespace Immutable {
      *   * Returns `0` if the elements should not be swapped.
      *   * Returns `-1` (or any negative number) if `valueA` comes before `valueB`
      *   * Returns `1` (or any positive number) if `valueA` comes after `valueB`
+     *   * Alternatively, can return a value of the `PairSorting` enum type
      *   * Is pure, i.e. it must always return the same value for the same pair
      *     of values.
      *
@@ -4548,7 +4570,7 @@ declare namespace Immutable {
      *
      * Note: This is always an eager operation.
      */
-    sort(comparator?: (valueA: V, valueB: V) => number): this;
+    sort(comparator?: Comparator<V>): this;
 
     /**
      * Like `sort`, but also accepts a `comparatorValueMapper` which allows for
@@ -4573,7 +4595,7 @@ declare namespace Immutable {
      */
     sortBy<C>(
       comparatorValueMapper: (value: V, key: K, iter: this) => C,
-      comparator?: (valueA: C, valueB: C) => number
+      comparator?: Comparator<C>
     ): this;
 
     /**
@@ -4972,7 +4994,7 @@ declare namespace Immutable {
      * If `comparator` returns 0 and either value is NaN, undefined, or null,
      * that value will be returned.
      */
-    max(comparator?: (valueA: V, valueB: V) => number): V | undefined;
+    max(comparator?: Comparator<V>): V | undefined;
 
     /**
      * Like `max`, but also accepts a `comparatorValueMapper` which allows for
@@ -4991,7 +5013,7 @@ declare namespace Immutable {
      */
     maxBy<C>(
       comparatorValueMapper: (value: V, key: K, iter: this) => C,
-      comparator?: (valueA: C, valueB: C) => number
+      comparator?: Comparator<C>
     ): V | undefined;
 
     /**
@@ -5009,7 +5031,7 @@ declare namespace Immutable {
      * If `comparator` returns 0 and either value is NaN, undefined, or null,
      * that value will be returned.
      */
-    min(comparator?: (valueA: V, valueB: V) => number): V | undefined;
+    min(comparator?: Comparator<V>): V | undefined;
 
     /**
      * Like `min`, but also accepts a `comparatorValueMapper` which allows for
@@ -5028,7 +5050,7 @@ declare namespace Immutable {
      */
     minBy<C>(
       comparatorValueMapper: (value: V, key: K, iter: this) => C,
-      comparator?: (valueA: C, valueB: C) => number
+      comparator?: Comparator<C>
     ): V | undefined;
 
     // Comparison

type-definitions/immutable.js.flow

@@ -60,6 +60,14 @@ type $IterableOf<C> = $Call<
   C
 >;
 
+const PairSorting: $ReadOnly<{ LeftThenRight: number, RightThenLeft: number }> =
+  {
+    LeftThenRight: -1,
+    RightThenLeft: +1,
+  };
+
+type Comparator<T> = (left: T, right: T) => number;
+
 declare class _Collection<K, +V> implements ValueObject {
   equals(other: mixed): boolean;
   hashCode(): number;
@@ -129,11 +137,11 @@ declare class _Collection<K, +V> implements ValueObject {
   entrySeq(): IndexedSeq<[K, V]>;
 
   reverse(): this;
-  sort(comparator?: (valueA: V, valueB: V) => number): this;
+  sort(comparator?: Comparator<V>): this;
 
   sortBy<C>(
     comparatorValueMapper: (value: V, key: K, iter: this) => C,
-    comparator?: (valueA: C, valueB: C) => number
+    comparator?: Comparator<C>
   ): this;
 
   groupBy<G>(
@@ -238,15 +246,15 @@ declare class _Collection<K, +V> implements ValueObject {
   keyOf(searchValue: V): K | void;
   lastKeyOf(searchValue: V): K | void;
 
-  max(comparator?: (valueA: V, valueB: V) => number): V;
+  max(comparator?: Comparator<V>): V;
   maxBy<C>(
     comparatorValueMapper: (value: V, key: K, iter: this) => C,
-    comparator?: (valueA: C, valueB: C) => number
+    comparator?: Comparator<C>
   ): V;
-  min(comparator?: (valueA: V, valueB: V) => number): V;
+  min(comparator?: Comparator<V>): V;
   minBy<C>(
     comparatorValueMapper: (value: V, key: K, iter: this) => C,
-    comparator?: (valueA: C, valueB: C) => number
+    comparator?: Comparator<C>
   ): V;
 
   isSubset(iter: Iterable<V>): boolean;
@@ -2351,6 +2359,7 @@ export default {
   Map,
   OrderedMap,
   OrderedSet,
+  PairSorting,
   Range,
   Repeat,
   Record,
@@ -2387,6 +2396,7 @@ export default {
 };
 
 export type {
+  Comparator,
   KeyedCollection,
   IndexedCollection,
   SetCollection,