Update(orderBy): Guaranteed stable sort

Falls back on built-in comparison function if user-provided comparison function
fails to break a tie between elements being ordered.

Closes #14881
BREAKING CHANGE: Using `orderBy` with a custom `comparator` function while
simultaneously setting `reverse` to `true` results in a potentially different
list order than previously.

Specifically, when the custom `comparator` fails to sort two objects (compares
them as being "equal"), the objects would previously have remained in their
original order in the array relative to each other. They will now switch places
as the `reverse` will be more accurately respected.

To migrate, make sure that your custom `comparator` properly differentiates
between all cases that your code base cares about and that "equal" cases are
not order dependent. We expect that due to the nature of this change, since the
entries are considered "equal", that very few projects will be affected by this
change in all but a minor visual manor that still respects the expected
operation being performed.

Author: BobChao87

src/ng/filter/orderBy.js

@@ -115,7 +115,7 @@
  *
  * @param {boolean=} reverse - If `true`, reverse the sorting order.
  * @param {(Function)=} comparator - The comparator function used to determine the relative order of
- *    value pairs. If omitted, the built-in comparator will be used.
+ *    value pairs. If omitted or finds two entries to be equal, the built-in comparator will be used.
  *
  * @returns {Array} - The sorted array.
  *
@@ -459,6 +459,9 @@
  * comparator function. For example, you might need to compare some strings in a locale-sensitive
  * way. (When specifying a custom comparator, you also need to pass a value for the `reverse`
  * argument - passing `false` retains the default sorting order, i.e. ascending.)
+ *
+ * If your comparator fails to differentiate between two items, they will fall back to the built-in
+ * comparator function, this produces a guarantee of stable sorting.
  *
    <example name="orderBy-custom-comparator" module="orderByExample4">
      <file name="index.html">
@@ -599,7 +602,7 @@ function orderByFilter($parse) {
         }
       }
 
-      return compare(v1.tieBreaker, v2.tieBreaker) * descending;
+      return (compare(v1.tieBreaker, v2.tieBreaker) || defaultCompare(v1.tieBreaker, v2.tieBreaker)) * descending;
     }
   };
 

test/ng/filter/orderBySpec.js

@@ -457,6 +457,21 @@ describe('Filter: orderBy', function() {
 
         expect(orderBy(items, expr, reverse, comparator)).toEqual(sorted);
       });
+
+      it('should use the default comparator to break ties on a provided comparator', function() {
+        // Some list that won't be sorted "naturally", i.e. should sort to ['a', 'B', 'c']
+        var items = ['c', 'a', 'B'];
+        var expr = null;
+        function comparator() {
+          return 0;
+        }
+        var reversed = ['B', 'a', 'c'];
+        var sorted = ['a', 'B', 'c'];
+
+        expect(orderBy(items)).toEqual(sorted);
+        expect(orderBy(items, expr, false, comparator)).toEqual(items);
+        expect(orderBy(items, expr, true, comparator)).toEqual(reversed);
+      });
     });
 
     describe('(object as `value`)', function() {