feat(orderBy): add support for custom comparators

With this change the 3rd argument is interpreted as a comparator function, used to compare the
values returned by the predicates. Leaving it empty falls back to the default comparator and a
value of `false` is a special case that also falls back to the default comparator but reverses the
order. Thus the new implementation is backwards compatible.

Helps with angular#12572 (maybe this is as close as we want to get).

Fixes angular#13238
Fixes angular#14455

Closes angular#5123
Closes angular#8112
Closes angular#10368

Author: gkalpak

src/ng/filter/orderBy.js

@@ -196,7 +196,7 @@
  */
 orderByFilter.$inject = ['$parse'];
 function orderByFilter($parse) {
-  return function(array, sortPredicate, reverseOrder) {
+  return function(array, sortPredicate, compareFn) {
 
     if (array == null) return array;
     if (!isArrayLike(array)) {
@@ -206,11 +206,13 @@ function orderByFilter($parse) {
     if (!isArray(sortPredicate)) { sortPredicate = [sortPredicate]; }
     if (sortPredicate.length === 0) { sortPredicate = ['+']; }
 
-    var predicates = processPredicates(sortPredicate, reverseOrder);
-    // Add a predicate at the end that evaluates to the element index. This makes the
-    // sort stable as it works as a tie-breaker when all the input predicates cannot
-    // distinguish between two elements.
-    predicates.push({ get: function() { return {}; }, descending: reverseOrder ? -1 : 1});
+    var predicates = processPredicates(sortPredicate);
+
+    // Define the `compare()` function. Use a default comparator if none is specified.
+    // A value of `true` means: Use the default comparator, but reverse the order.
+    var compare = isFunction(compareFn) ? compareFn :
+                  compareFn             ? reverseDefaultCompare :
+                                          defaultCompare;
 
     // The next three lines are a version of a Swartzian Transform idiom from Perl
     // (sometimes called the Decorate-Sort-Undecorate idiom)
@@ -222,26 +224,29 @@ function orderByFilter($parse) {
     return array;
 
     function getComparisonObject(value, index) {
+      // NOTE: We are adding an extra `tieBreaker` value based on the element's index.
+      // This will be used to keep the sort stable when all the input predicates cannot
+      // distinguish between two elements.
       return {
         value: value,
+        tieBreaker: {value: index, type: 'number'},
         predicateValues: predicates.map(function(predicate) {
           return getPredicateValue(predicate.get(value), index);
         })
       };
     }
 
     function doComparison(v1, v2) {
-      var result = 0;
       for (var index=0, length = predicates.length; index < length; ++index) {
-        result = compare(v1.predicateValues[index], v2.predicateValues[index]) * predicates[index].descending;
-        if (result) break;
+        var result = compare(v1.predicateValues[index], v2.predicateValues[index]) * predicates[index].descending;
+        if (result) return result;
       }
-      return result;
+
+      return compare(v1.tieBreaker, v2.tieBreaker);
     }
   };
 
-  function processPredicates(sortPredicate, reverseOrder) {
-    reverseOrder = reverseOrder ? -1 : 1;
+  function processPredicates(sortPredicate) {
     return sortPredicate.map(function(predicate) {
       var descending = 1, get = identity;
 
@@ -260,7 +265,7 @@ function orderByFilter($parse) {
           }
         }
       }
-      return { get: get, descending: descending * reverseOrder };
+      return { get: get, descending: descending };
     });
   }
 
@@ -277,7 +282,7 @@ function orderByFilter($parse) {
 
   function objectValue(value, index) {
     // If `valueOf` is a valid function use that
-    if (typeof value.valueOf === 'function') {
+    if (isFunction(value.valueOf)) {
       value = value.valueOf();
       if (isPrimitive(value)) return value;
     }
@@ -295,23 +300,36 @@ function orderByFilter($parse) {
     if (value === null) {
       type = 'string';
       value = 'null';
-    } else if (type === 'string') {
-      value = value.toLowerCase();
     } else if (type === 'object') {
       value = objectValue(value, index);
     }
     return { value: value, type: type };
   }
 
-  function compare(v1, v2) {
+  function defaultCompare(v1, v2) {
     var result = 0;
-    if (v1.type === v2.type) {
-      if (v1.value !== v2.value) {
-        result = v1.value < v2.value ? -1 : 1;
+
+    var type1 = v1.type;
+    var type2 = v2.type;
+    var value1 = v1.value;
+    var value2 = v2.value;
+
+    if (type1 === type2) {
+      if (type1 === 'string') {
+        value1 = value1.toLowerCase();
+        value2 = value2.toLowerCase();
+      }
+      if (value1 !== value2) {
+        result = value1 < value2 ? -1 : 1;
       }
     } else {
-      result = v1.type < v2.type ? -1 : 1;
+      result = type1 < type2 ? -1 : 1;
     }
+
     return result;
   }
+
+  function reverseDefaultCompare(v1, v2) {
+    return -1 * defaultCompare(v1, v2);
+  }
 }

test/ng/filter/orderBySpec.js

@@ -13,15 +13,18 @@ describe('Filter: orderBy', function() {
         toThrowMinErr('orderBy', 'notarray', 'Expected array but received: {}');
     });
 
+
     it('should not throw an exception if a null or undefined value is provided', function() {
       expect(orderBy(null)).toEqual(null);
       expect(orderBy(undefined)).toEqual(undefined);
     });
 
+
     it('should not throw an exception if an array-like object is provided', function() {
       expect(orderBy('cba')).toEqual(['a', 'b', 'c']);
     });
 
+
     it('should return sorted array if predicate is not provided', function() {
       expect(orderBy([2, 1, 3])).toEqual([1, 2, 3]);
 
@@ -44,6 +47,27 @@ describe('Filter: orderBy', function() {
     });
 
 
+    it('should compare strings case-insensitively in the default comparator', function() {
+      var items = [{id: 'item1'}, {id: 'Item2'}, {id: 'item3'}];
+
+      expect(orderBy(items, 'id')).toEqual([
+        items[0],
+        items[1],
+        items[2]
+       ]);
+    });
+
+
+    it('should not convert strings to lowercase for passing to a custom comparator', function() {
+      var items = [{id: 'item1'}, {id: 'Item2'}];
+      var comparator = jasmine.createSpy('comparator');
+
+      orderBy(items, 'id', comparator);
+
+      expect(comparator.calls.argsFor(0)).toContain({value: 'Item2', type: 'string'});
+    });
+
+
     it('should sort inherited from array', function() {
       function BaseCollection() {}
       BaseCollection.prototype = Array.prototype;
@@ -93,6 +117,7 @@ describe('Filter: orderBy', function() {
               { a:new Date('01/01/2014'), b:3 }]);
     });
 
+
     it('should compare timestamps when sorting dates', function() {
       expect(orderBy([
         new Date('01/01/2015'),
@@ -140,6 +165,7 @@ describe('Filter: orderBy', function() {
       expect(orderBy(array)).toEqualData(array);
     });
 
+
     it('should reverse array of objects with no predicate and reverse is `true`', function() {
       var array = [
         { id: 2 },
@@ -157,6 +183,38 @@ describe('Filter: orderBy', function() {
     });
 
 
+    it('should support a custom comparator', function() {
+      var items = [
+        {owner: 'ownerA', type: 'typeA'},
+        {owner: 'ownerB', type: 'typeB'},
+        {owner: 'ownerC', type: 'typeB'},
+        {owner: 'ownerD', type: 'typeB'}
+      ];
+      var predicates = ['type', '-owner'];
+      var comparator = function(o1, o2) {
+        var v1 = o1.value;
+        var v2 = o2.value;
+        var hasEra1 = v1.toLowerCase().indexOf('nerd') !== -1;
+        var hasEra2 = v2.toLowerCase().indexOf('nerd') !== -1;
+
+        // Shamelessly promote "nerds"
+        if (hasEra1 || hasEra2) {
+          return (hasEra1 && hasEra2) ? 0 : (hasEra1) ? -1 : 1;
+        }
+
+        // No "nerd"; lexicographic order
+        return (v1 === v2) ? 0 : (v1 < v2) ? -1 : 1;
+      }
+
+      expect(orderBy(items, predicates, comparator)).toEqual([
+        items[0],
+        items[2],
+        items[1],
+        items[3]
+      ]);
+    });
+
+
     it('should reverse array of objects with predicate of "-"', function() {
       var array = [
         { id: 2 },